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

Authentication

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

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

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

The following example displays a request.

POST /AdminInterface/restapi/v1/sidTokens/lookup

Accept: application/json

Authorization: Bearer <JWT token>

Example Request Body

{

"tokenSerialNumber": "000000200002"

}

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