Cloud Administration Clear PIN for Hardware Token API

The Cloud Administration Clear PIN for Hardware Token API enables Help Desk Administrators to clear the PIN for a hardware token assigned to a user.

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 and clear the PIN.

Method Request URL Response Content Type Response Body Response Codes
PATCH /AdminInterface/restapi/v2/users/<userId>/sidTokens/clearPin application/json Token details with property 200, 404, 409, 500

Example Request Data

The following example displays a request.

PATCH /AdminInterface/restapi/v2/users/<userId>/sidTokens/clearPin

Accept: application/json

Authorization: Bearer <JWT token>

Example Request Body

{

"tokenSerialNumber" : "1231314525"

}

Request Property Descriptions

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

Property Description Required? Max Length Data Type
tokenSerialNumber The token serial number associated with a user. The number is displayed at the back of the SecurID700 hardware token. Yes 36 String

Example Response

The following example response shows whether the PIN is cleared or not for a single hardware token, with token serial number specified in the request.

{

"userId": "eb2e12ae-1112-451b-98e1-dfe4e6afd60d",

"tokenSerialNumber": "1231314525",

"pinSet": "false"

}

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
pinSet Flag that tells the system whether the user has set a PIN or not. This is managed by the system and is mainly for informational purposes.
Possible values:
True - PIN is set. False - PIN is not set.
Boolean

Response Codes

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

Code Description
200 Successfully cleared the PIN for the hardware token assigned to the user.
404 Either user does not exist or hardware token does not exist in the Cloud Authentication Service.
409 Cannot clear the PIN for a hardware token because it is not assigned to a particular user.
500 Internal server error occurred.
The following message is returned: Unable to Enable/Disable a hardware token.