Cloud Administration Authenticator Details API Version 2Cloud Administration Authenticator Details API Version 2
The Cloud Administration Authenticator Details API (Version 2) enables Help Desk Administrators to retrieve a list of authenticators for a user, including the SecurID700 hardware tokens and SecurID DS100 OTP and FIDO credentials, by providing a user ID.
Note: The API
can retrieve a list of user authenticators for a single user per request.
AuthenticationAuthentication
Clients calling this API must authenticate themselves by including a JSON Web Token in a request. For instructions on using this token, see Authentication for the Cloud Administration REST APIs.
Administrative RolesAdministrative Roles
This API can use an API key that is associated with either the Super Administrator or the Help Desk Administrator role. For more information, see Manage the Cloud Administration REST API Keys.
Software Developer KitSoftware Developer Kit
You can download the API Software Developer Kit (SDK) from Cloud Administration REST API Download.
Request RequirementsRequest Requirements
Use the following information to retrieve information about a particular user's authenticator.
Method | Request URL | Response Content Type | Response Body | Response Codes |
---|---|---|---|---|
GET | /AdminInterface/restapi/v2/users/ <userId>/devices | application/json | User authenticator details with property | 200, 400, 403, 404, 500 |
Resource IdentifierResource Identifier
Resource ID | Description | Type |
---|---|---|
<userId> | Unique user identifier that is sent in response to the Cloud Administration User Details API. | Boolean |
Request ParameterRequest Parameter
The authenticator details API allows the following parameter:
Request Parameter | Description | Type |
---|---|---|
<includeBrowsers> | Set to True to include the browser authenticator type, or False to exclude the browser authenticator type. When you omit this identifier, the browser authenticator type is excluded. | Boolean |
Example Request DataExample Request Data
The following example displays a request to retrieve all authenticator types other than the browser authenticator type.
GET /AdminInterface/restapi/v2/users/<userId>/devices
Accept: application/json
Authorization: Bearer <JWT token>
The resource identifier <userId> is a unique user identifier that is sent in the response to the Cloud Administration User Details API.
Example ResponseExample Response
The following example response shows the status of all authenticators for a single user.
GET /AdminInterface/restapi/v2/users/<userId>/devices
{
"devices":[
{
"id":"21",
"name":"vstt1lft-24@via.comdevicenamebvg",
"userId":"d936a1a4-d797-4c45-9ed4-acc877241a1c",
"deviceType":"iOS 8.1.2",
"registeredDate":"2021-06-02T20:55:45.562Z",
"capabilities":"FCAM,BCAM,ACC,FINGERPRINT",
"browser":false
},
{
"id": "194",
"name": "Chrome_94.0.4606.61_1660878496964",
"userId": "702fca94-fa11-e86c-26f7-e49505051e48",
"deviceType": "Chrome 94.0.4606.61",
"registeredDate": "2022-08-19T03:08:58.754Z",
"capabilities": null,
"browser": true
}
],
"sidTokens":[
{
"id":"2f8f4221-fc8a-46f6-b08f-73b9ee2b96f6",
"name":"OomqI",
"userId":"d936a1a4-d797-4c45-9ed4-acc877241a1c",
"deviceType":"SecurID 700",
"registeredDate":"2021-06-02T20:58:51.501Z",
"tokenSerialNumber":"000000200005",
"updatedAt":"2021-06-02T20:58:51.503Z",
"tokenState":"Activated",
"expiryDate":"2027-02-12T00:00:00.000Z",
"tokenStatus":"Enabled",
"assignedAt":"2021-06-02T20:58:51.501Z",
"assignedBy":"vstt1lft-24@via.com",
"pinSet":true,
"tokenStatusChangedAt":null,
"tokenStatusChangedBy":null
},
{
"id": "d4f8b2e7-f6e4-e102-bb28-ee0b5d37c2f2",
"name": "user’s SecurID DS100",
"userId": "26c1e3d6-b31c-803e-cf7f-bdbe7687a72b",
"deviceType": "SecurID DS100",
"registeredDate": "2022-06-08T07:58:13.432Z",
"tokenSerialNumber": "014010008035",
"updatedAt": "2022-06-08T09:47:50.496Z",
"tokenState": "Activated",
"expiryDate": null,
"tokenStatus": "Enabled",
"tokenStatusReason": null,
"assignedAt": "2022-06-08T07:58:13.432Z",
"assignedBy": user.one@mycompany.com,
"pinSet": true,
"tokenStatusChangedAt": " null",
"tokenStatusChangedBy": " null",
"deviceSerialNumber": "140100080"
}
],
"fidoTokens":[
{
"id":"8wioDlecm5DRYitXCOyfQFlEnrJMTv_UcBPeMMKPLy3_r5RB5Qp77pmMVuO9aKHVl301LbAaVOcv6uXyyDL3w",
"name":"vstt1lft-24@via.com_FidoToken",
"userId":"d936a1a4-d797-4c45-9ed4-acc877241a1c",
"deviceType":"FIDO Token",
"registeredDate":"2021-06-02T20:57:46.000Z"
"status":"Enabled"
}
]
}
Response Property DescriptionsResponse Property Descriptions
The following table shows response property descriptions and data types.
Property | Description | Data Type |
---|---|---|
id | Identifies the authenticator. | String |
name | Name of the authenticator. | String |
userId | Identifies the user associated with this authenticator. | String |
deviceType | Device type information related to the authenticator or browser. | String |
registeredDate registeredDate (for FIDO authenticator) |
Timestamp when the authenticator was registered. For information about formatting timestamps in ISO 8601 format, see https://www.w3.org/TR/NOTE-datetime. Timestamp when the FIDO authenticator was registered. |
String |
capabilities (for devices other than sidToken or FIDO Token) |
The capability of the device, for example Fingerprint. |
String |
browser | This value tells the system whether the user is using a browser authenticator or not. Values: true - A browser is being used, or false - No browser is being used. |
String |
The Following Properties are for Hardware Tokens Only | ||
tokenSerialNumber | Serial number osf the hardware token. | String |
deviceSerialNumber | The serial number of the SecurID DS100 hardware authenticator. The number is displayed on the back of the authenticator. | String |
updatedAt | Last updated timestamp of the hardware token. For information on formatting timestamps in ISO 8601 format, see https://www.w3.org/TR/NOTE-datetime. | String |
tokenState | State of the hardware token: Unassigned, Activation Pending, or Activated. | String |
expiryDate | Hardware token expiration date. For information on formatting timestamps in ISO 8601 format, see https://www.w3.org/TR/NOTE-datetime. | String |
tokenStatus | Status of the hardware token: Enabled or Disabled. | String |
assignedAt | The timestamp when the administrator has assigned the hardware token to the user, or when the user registered a token that was not pre-assigned. For information on formatting timestamps in ISO 8601 format, see https://www.w3.org/TR/NOTE-datetime. | String |
assignedBy | Identifies the user who registered the hardware token or the administrator who assigned the hardware token to a user. | String |
pinSet | Flag that tells the system whether the user has set a PIN or not for the hardware token. Values: True - PIN is set and False - PIN is not set. |
String |
tokenStatusChangedAt | The timestamp when the hardware token was enabled or disabled. For information on formatting timestamps in ISO 8601 format, see https://www.w3.org/TR/NOTE-datetime. | String |
tokenStatusChangedBy | Identifies the administrator who enabled or disabled the hardware token. | String |
status | Status of the FIDO authenticator: Enabled or Disabled | String |
Response CodesResponse Codes
The following table shows response codes and descriptions for this API.
Code | Description |
---|---|
200 | User and authenticator are successfully found. |
400 | User ID is not provided as a request identifier. |
403 | User is not authorized to perform the request. |
404 | User is not found. |
500 | Internal error occurred while processing the request. |
429 | Too many requests. |