Cloud Administration Assign Hardware Token APICloud 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.
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 RolesAdministrative 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 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 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 DataExample Request Data
The following example displays a hardware token assignment request.
Authorization: Bearer <JWT token>
Example Request BodyExample Request Body
"tokenSerialNumber" : "000123456789",
"tokenName" : "My SecurID Token 789"
Request Property DescriptionsRequest 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 ResponseExample Response
The following example response shows the state of a single hardware token with basic assignment related information.
"tokenState": "Activation Pending",
Response Property DescriptionsResponse Property Descriptions
The following table shows response property descriptions and the associated data types.
|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 CodesResponse Codes
The following table shows response codes and descriptions for this API.
|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.|
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.|