Cloud Administration Retrieve Hardware Token Details APICloud Administration Retrieve Hardware Token Details API
The Cloud Administration Retrieve Hardware Token Details API enables Help Desk Administrators to retrieve a hardware token record by providing a token serial number.
AuthenticationAuthentication
Clients calling this API must authenticate themselves by including a JSON web token in the request. For instructions on using this token, see Authentication for the Cloud Administration APIs.
Administrative RolesAdministrative Roles
This API can use an API key associated with either Super Administrator or Help Desk Administrator role. For more information, see Manage the Cloud Administration 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 a hardware token by providing a token serial number.
Method | Request URL | Response Content Type | Response Body | Response Codes |
---|---|---|---|---|
POST | /AdminInterface/restapi/v1/sidTokens/lookup | application/json | Token details with property | 200, 400, 403, 404, 500 |
Example Request DataExample Request Data
The following example displays a request.
POST /AdminInterface/restapi/v1/sidTokens/lookup
Accept: application/json
Authorization: Bearer <JWT token>
Example Request BodyExample Request Body
{
"tokenSerialNumber": "000000200002"
}
Request Property DescriptionsRequest Property Descriptions
The following table shows request property descriptions and other associated information.
Property | Description | Required? | Max Length | Data Type |
---|---|---|---|---|
tokenSerialNumber | The serial number of the hardware token. The number is displayed at the back of the SecurID700 token. | Yes | 36 | String |
Example ResponseExample Response
The following example response shows the status of a single hardware token with the token serial number specified in the request.
{
"deviceType": "SID700",
"tokenStatus": "Enabled",
"assignedBy": null,
"registeredDate": null,
"assignedAt": null,
"tokenStatusChangedAt": null,
"userId": null,
"expiryDate": "2027-02-12T00:00:00.000Z",
"tokenSerialNumber": "000000200002",
"pinSet": false,
"name": null,
"id": "486177dd-5e3a-4094-a98f-9ee03f4ad0cd",
"tokenState": "Unassigned",
"tokenStatusChangedBy": null,
"updatedAt": "2021-06-04T16:16:56.879Z"
}
Response Property DescriptionsResponse Property Descriptions
The following table shows response property descriptions and the associated data types.
Property | Description | Data Type |
---|---|---|
id | Identifies the hardware token. | String |
name | Name of the hardware token. | String |
userId | Identifies the user to whom the hardware token is assigned or registered. | String |
deviceType | Device type information related to the hardware token. | String |
registeredDate | Timestamp when the hardware token was registered (enrolled) by a user. This date is null when the token is assigned to a user by the administrator and the user has not registered it. | String |
tokenSerialNumber | Serial number of the hardware token. | 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 hardware token was assigned to a user by the administrator. Alternatively, this can be the timestamp when a 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 |
pinSet | Flag that tells the system whether the user has set a PIN or not. Possible values: True - PIN is set. False - PIN is not set. |
Boolean |
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 |
Response CodesResponse Codes
The following table shows response codes and descriptions for this API.
Code | Description |
---|---|
200 | Hardware token is successfully found. |
400 | Hardware token serial number is not provided as a parameter. |
403 | User is not authorized to perform the request. |
404 | Hardware token with serial number is not found. |
500 | Internal error occurred while processing the request. |
429 | Too many requests. |