Reset Account Pin Code
This guide outlines how to enable a user to reset their PIN code. Note users must know their original PIN code to reset it. Otherwise, they must follow the Account Recovery flow outlined in this guide.
Caution: If a user loses both their PIN code and the answers to their Security Questions, they will be permanently locked out of their account, losing access to all of their wallets and assets.
1. Run Sample App
Once you have the iOS or Android sample app setup locally you will then
- Run the simulator
- Acquire an App ID from the developer console wallet configurator
- Add the App ID to the sample app
2. Acquire Session Token
Next, you will need to acquire a session token. To do this, you will make a request to thePOST /users/token
using the previously created userId
in Step 1. The userToken
is a 60-minute session token used to initiate requests requiring a user challenge (PIN code entry). After 60 minutes, the session expires, and a new userToken
must be generated via the same endpoint.
From this response, you will acquire the encryptionKey
and userToken
which you should provide in the respective sample app fields. Additionally, you will use the userToken
in Step 2.
curl --request POST \
--url 'https://api.circle.com/v1/w3s/users/token' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'authorization: Bearer <API_KEY>' \
--data '
{
"userId": "2f1dcb5e-312a-4b15-8240-abeffc0e3463"
}
'
{
"data": {
"userToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCC9.eyJkZXZlbG9wZXJFbnRpdHlFbnZpcm9ubWVudCI6IlRFU1QiLCJlbnRpdHlJZCI6IjRlMDdhOGM5LTIxOTAtNDVlNC1hNjc0LWQyMGFkNjg4MWI3YyIsImV4cCI6MTY5MDU1MjcwNywiaWF0IjoxNjkwNTQ5MTA3LCJpbnRlcm5hbFVzZXJJZCI6ImQ2ZjkzODliLWQ5MzUtNWFlYy1iOTVhLWNjNTk1NjA2YWM5NiIsImlzcyI6Imh0dHBzOi8vcHJvZ3JhbW1hYmxlLXdhbGxldC5jaXJjbGUuY29tIiwianRpIjoiMmE0YmJlMzAtZTdkZi00YmM2LThiODMtNTk0NGUyMzE2ODlkIiwic3ViIjoiZXh0X3VzZXJfaWRfOSJ9.dhfByhxZFbJx0XWlzxneadT4RQWdnxLu3FSN9ln65hCDOfavaTL1sc4h-jUR8i4zMmfdURw3FFcQIdSbm-BUg6M7FP_fp-cs9xBbNmRZa31gMd1aKdcajJ9SvlVrfUowYfGXM3VcNF8rtTFtW-gk1-KzU4u10U35XXbbMcW1moxE0Rqx_fKotDgk2VdITuuds5d5TiQzAXECqeCOCtNoDKktMkglltbnLxOaRl2ReZjGt-ctD2V0DbYNO4T_ndPSUDI6qD7dXQRed5uDcezJYoha3Qj3tFGBglEnox2Y6DWTbllqjwmfTGrU8Pr0yz4jQz7suGwmiCzHPxcpYxMzYQ",
"encryptionKey": "Tlcyxz7Ts9ztRLQq5+pic0MIETblYimOo2d7idV/UFM="
}
}
3. Initialize PIN reset and Acquire Challenge ID
Make a request to PUT /user/pin
using the userToken
returned from Step 1. This call returns a challengeId
, which is used with the Circle Programmable Wallet SDK to have the user reset their PIN code.
curl --request PUT \
--url 'https://api.circle.com/v1/w3s/user/pin' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'authorization: Bearer <API_KEY>' \
--header 'X-User-Token: <USER_TOKEN>' \
--data '
{
"idempotencyKey": "2532e703-d5a6-4927-b914-adf1c7017984"
}
'
{
"data": {
"challengeId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5"
}
}
4. Reset the PIN in the Sample App
Using the sample application, enter the userToken
and secretKey
returned from Step 1. Enter the challengeId
returned from Step 2.Â
You should be ready to execute the reset PIN code workflow via the Circle Programmable Wallet SDK. Once you’ve entered the required fields indicated in Step 3, click Execute to continue.Â

The sample application takes you through the authentication and PIN code reset process, which includes the user entering their PIN code to authorize the reset and entering a new PIN code.

5. Check the Challenge Status
Make a request GET /user/challenges/{id}
using the challengeId
received from Step 2 to retrieve the status of the challenge. Additionally, Circle sends a notification to a subscribed endpoint once the PIN code reset is complete. For a full list of possible statuses
, see the Asynchronous States and Statuses guide.
curl --request GET \
--url 'https://api.circle.com/v1/w3s//user/challenges/{id}' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'authorization: Bearer <API_KEY>' \
--header 'X-User-Token: <USER_TOKEN>'
{
"data": {
"challenge": {
"id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
"correlationIds": [
"54399e5a-1bf6-4921-9559-10c1115678cd"
],
"status": "COMPLETED",
"type": "CHANGE_PIN"
}
}
}
Updated 2 days ago
The user has successfully reset their PIN code! Move on to recover an account guide to complete: