Navigate to Setup > Authentication > Users. This tab is where you set up web console users and configure their permissions. Note that these user accounts are not granted access to the host itself (e.g. SSH or VM console), as those user accounts are configured separately at the host level.
There are five things you can do here:
Click the big '+ User' sign, and you will see a screen similar to the following.
A description of each of the fields:
As previously explained in the documentation for Notification Settings, it is also possible to manage a user's notification settings. To manage email subscriptions, simply click on the bell icon for any user and you should see a form like the following:
toggle any of the digests you would like to subscribe to and manage the frequency. For more information, see the Notification Settings Documentation
To connect to and use the DeepSurface API you must generate an API Key and API Secret for your user account. You can do this when creating a new user or when editing an existing user's settings.
When you click the Generate API Credentials button, an API Key and API Secret will be generated. Before clicking Save Changes, copy the API Secret to a safe location or to your Password Manager. You will not be able to access this API Secret after the user settings modal closes. You will be able to access the API Key at any time. You will need both the API Key and API Secret to connect to the DeepSurface API.
If you misplace your API Credentials, or simply wish to regenerate them, you may do so by clicking the Generate API Credentials button again and clicking OK when warned that previously generated credentials for the user will be invalidated. A new API Key and API Secret will then be generated and be available for use.
It is important to note that regenerating API Credentials causes existing credentials for a user to be immediately disabled, and any automation tools or scripts that use the DeepSurface API will need to be updated.
This page assumes that you can reach your DeepSurface console via https://hostname
.
Please refer to the Swagger UI documentation page on your DeepSurface console. If you can reach your DeepSurface console at https://hostname
, then you can reach the Swagger UI at https://hostname/api/v1/docs
and the accompanying OpenAPI JSON specification at https://hostname/api/v1/openapi.json
.
One set of API credentials can be generated per user on the user settings page. The full set of instructions for generating these credentials is present at the top of the https://hostname/api/v1/docs
page or explained above.
https://hostname/api/v1/token/oauth2
with payload username=API_KEY&password=API_SECRET
where API_KEY is your API Key and API_SECRET is your API Secret.access_token
. Extract the value and attach this to your headers as: Authorization:Bearer ACCESS_TOKEN
where ACCESS_TOKEN is the access_token value from the response JSON. Use this header for all subsequent requests.ACCESS_TOKEN=$(curl -X POST --data 'username=API_KEY&password=API_SECRET' https://hostname/api/v1/token/oauth2 | python3 -c "import json;import sys;print(json.loads(sys.stdin.read())['access_token'])")
curl -X POST --header "Authorization: Bearer $ACCESS_TOKEN" --header 'Content-Type: application/json' 'https://hostname/api/v1/model/$search' -d '{}'
[
{
"created" : 1622234277.25352,
"id" : "2ac4e5c4-53fc-4b77-80fd-88948962dcf8",
"identifier" : "observed",
"label" : "Observed",
"last_analyzed" : 0,
"modified" : 1622238770.71588,
"parent" : "2ac4e5c4-53fc-4b77-80fd-88948962dcf8",
"risk" : 0
},
{
"created" : 1622234277.25352,
"id" : "4dd69d13-c9da-4e4f-b039-07c6e2594066",
"identifier" : "base",
"label" : "Base",
"last_analyzed" : 1624731840.36375,
"modified" : 1624655584.96631,
"parent" : "2ac4e5c4-53fc-4b77-80fd-88948962dcf8",
"risk" : 0
}
]