Cloud Administration Assign Hardware Token API

The Cloud Administration Assign Hardware Token API enables Help Desk Administrators to assign a single hardware token to a user.

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 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 assign a hardware token to a user by providing a token serial number and optional token name.

Method Request URL Response Content Type Response Body Response Codes
PATCH /AdminInterface/restapi/v1/users/<userId>/sidTokens/assign application/json User status 200, 400, 403, 404, 409, 500

Example Request Data

The following example displays a hardware token assignment request.

PATCH /AdminInterface/restapi/v1/users/<userId>/sidTokens/assign

Content-Type: application/json

Authorization: Bearer <JWT token>

Example Request Body

{

"tokenSerialNumber" : "000123456789",

"tokenName" : "My SecurID Token 789"

}

Request Property Descriptions

The following table shows request property descriptions and other associated information.

Property Description Required? Max Length Data Type
tokenSerialNumber Serial number of the hardware token that is to be assigned. Yes 36 String
tokenName Name of the hardware token. If not specified, the server automatically sets it to the serial number of the hardware token. No 255 String

Example Response

The following example response shows the state of a single hardware token with basic assignment related information.

{

"userId": "86beae30-8706-4a41-8b02-d6092ed3f896",

"tokenSerialNumber": "000123456789",

"tokenState": "Activation Pending",

"assignedAt": "2021-06-13T04:38:51.961Z",

"assignedBy": "ed042594-b230-4b68-9191-9bfa759d0866@securid.com"

}

Response Property Descriptions

The following table shows response property descriptions and the associated data types.

Property Description Data Type
userId Identifies the user to whom the hardware token is assigned or registered. String
tokenSerialNumber Serial number of the hardware token. String
tokenState State of the hardware token: Unassigned, Activation Pending, or Activated. String
assignedAt The timestamp when the hardware token was assigned to a user or 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
assignedBy Identifies the administrator who has assigned the hardware token. String

Response Codes

The following table shows response codes and descriptions for this API.

Code Description
200 The hardware token is successfully assigned to the user.
400 Invalid parameters provided (such as invalid token serial number, token name, or user ID format).
403 User is not authorized to perform the request. (Possible causes: Lack of administrator rights or invalid JSON web token provided).
404 Either the user ID or the hardware token serial number does not exist.
409

The request has inconsistent or conflicting state preventing it from getting completed (such as expired token, disabled user ID, or hardware token already assigned to the user).
500 The request cannot be completed due to an internal server error.
429 Too many requests.