Broadleaf Microservices
  • v1.0.0-latest-prod

One Time Passcodes with the Passcode Service

Overview

The Passcode endpoints enable the creation, consumption, and management of one-time passcodes.

Passcodes

Passcodes are randomly generated Strings. The length of a passcode and the set of valid characters to use can be configured with the PasswordTokenProperties class.

Purpose

Every passcode is created with a "purpose". The purpose is a String that will be stored with the passcode. During passcode consumption, the purpose from the consumption request will be validated against the purpose saved with the passcode. The purpose must match in order for the passcode to be successfully consumed.

Creating a Passcode

Call the "retrieve" endpoint with a username and a purpose. It will return a token id and a token value. The token value should be given to the user to consume. The id can be used by the app to check status or invalidate the passcode.

Request
curl --location --request GET 'https://localhost:8443/passcode/retrieve?purpose=TEST_PURPOSE&username=test@test.com&client_id=heatclinic' \
--header 'Authorization: Bearer eyJ...SUA' \
Response
{
    "id": "01FM98Y1WCT0KT0AT56TMJ1973",
    "token": "FCobPMiwtlHtr67TM6izFOL506L6T4k5"
}

Consuming a Passcode

Call the "consume" endpoint with the passcode, purpose, and username. The service will ensure the following are valid:

  • The given User owns the passcode being consumed.

  • The passcode has not been consumed already.

  • The passcode has not expired.

Successful consumption will return the token id. Unsuccessful consumption will return a 400.

Request
curl --location --request POST 'https://localhost:8443/passcode/consume?client_id=heatclinic' \
--header 'Authorization: Bearer eyJ...SUA' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'passcode=FCobPMiwtlHtr67TM6izFOL506L6T4k5' \
--data-urlencode 'purpose=TEST_PURPOSE' \
--data-urlencode 'username=test@test.com'
Response
{
    "id": "01FM98Y1WCT0KT0AT56TMJ1973"
}

Get the Status of a Passcode

Send a passcode ID to the "status" endpoint to get a boolean that indicates if the passcode is still valid.

Request
curl --location --request GET 'https://localhost:8443/passcode/status?passcode_id=01FM98Y1WCT0KT0AT56TMJ1973&client_id=heatclinic' \
--header 'Authorization: Bearer eyJ...SUA'
Response
{
    "id": "01FM98Y1WCT0KT0AT56TMJ1973",
    "valid": false
}

Invalidating a Passcode

An active passcode can be invalidated with the "invalidate" endpoint. Send the passcode ID and the token will be marked as used.

Request
curl --location --request POST 'https://localhost:8443/passcode/invalidate?client_id=heatclinic' \
--header 'Authorization: Bearer eyJ...SUA' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'passcode_id=01FM98Y1WCT0KT0AT56TMJ1973'
Response
{
    "id": "01FM98Y1WCT0KT0AT56TMJ1973",
    "valid": false
}