Skip to main content

Validate OTP Authentication API guide

Updated June 23, 2020

Use this guide to enable the SecureAuth Authentication API to validate generated one-time passcodes (OTPs) through the /otp/validate POST endpoint.

After the /auth endpoint is called and an OTP is generated, the passcode is stored in the designated IdP property and then validated at this endpoint.

Prerequisites

  • Complete the steps in the Authentication API guide.

  • Configure the realm on the SecureAuth® Identity Platform 19.07 or later, in the Advanced Settings (formerly Classic Experience) Web Admin, following the next steps below.

Configure Identity Platform Web Admin

Use these steps to map an auxiliary ID (Aux ID) for the OTP validation to use, enable one OTP option, and then set the AUX ID for the OTP Validation Property. This enables communication with the Identity Platform to validate one-time passcodes (OTPs) from email, phone calls, SMS, and Notification Passcode. These steps set up all the pieces needed to use the /otp/validate POST endpoint for OTP validation.

  1. In the Data tab, go to the Profile Fields section.

  2. Map a Field to a Property to use for the OTP validation.

    60570004.png

  3. Save the changes.

  4. In the Multi-Factor Methods tab, go to the Multi-Factor Configuration section.

  5. Enable at least one OTP option:

    • OTP via Phone Call

    • OTP via SMS/Text

    • OTP via Email

    • OTP via Notification Passcode

      60570005.png

  6. Save the changes.

  7. In the API tab, go to the API Key section.

  8. Check Enable API for this realm.

    60555645.png

  9. Click Generate Credentials to create a new Application ID and Application Key.

    The Application ID and Application Key are unique for each realm.

    The API key looks like it comprises 64 random characters, but it actually comprises 32 two-character base-16 hexadecimal values.

    This is important to note when using the API key to produce the HMAC hash.

  10. Click Select & Copy to copy the contents from the fields

    These values are required when you configure the header.

  11. In the API Permissions section, check Enable Authentication API.

    otp_validate_prop.png

  12. Set the OTP Validation Property dropdown to the Aux ID you set in the Data tab above. You can then use the /otp/validate POST endpoint to validate generated one-time passcodes (OTPs), which is described in the next section.

  13. Save the changes.

POST endpoint

HTTP Method

Endpoint

Example

POST

/api/v2/otp/validate

https://secureauth.company.com/secureauth2/api/v2/otp/validate
In this section: