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.

For information about managing access to this API, see Accessing the Cloud Administration APIs.

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.

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, 429, 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).
429	Too many requests.
500	The request cannot be completed due to an internal server error.

Don't see what you're looking for?