Cloud 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.

Authentication

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 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 Kit

You can download the API Software Developer Kit (SDK) from Cloud Administration REST API Download.

Request 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 Identifier

Resource ID Description Type
<userId> Unique user identifier that is sent in response to the Cloud Administration User Details API. Boolean

Request 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 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 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 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.
For FIDO authenticators, the following fields are created:
_at registration_time

 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 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.