TOTP Credential Management APIs

This guide provides an overview and instructions on how to use the new REST APIs added to Keycloak via a custom extension. These APIs facilitate management of TOTP credential.

API Endpoint Structure

The base URL for these APIs will typically be:

YOUR_KEYCLOAK_BASE_URL/admin/realms/YOUR_REALM/totp-resources/

Where:

• YOUR_KEYCLOAK_BASE_URL is the URL of your Keycloak instance.

• YOUR_REALM is the realm your users belong to.

note

Important: All requests to these APIs must be accompanied with a valid access token for the user.

The generate API

The generate API is used to obtain the necessary information (encoded secret and QR code) to display to the user for setting up their TOTP authenticator application.

Endpoint

GET YOUR_KEYCLOAK_BASE_URL/admin/realms/YOUR_REALM/totp-resources/generate

Request

• Method: GET

• Headers:

  • Content-Type:application/json

  • Authorization:Bearer USER_ACCESS_TOKEN

Response

A successful response will return a JSON object containing the encoded secret and the base64-encoded QR code image.

• Status Code:200 OK

• Body:

JSON

{
    "encodedSecret": "YOUR_ENCODED_TOTP_SECRET",
    "qrCode": "BASE64_ENCODED_QR_CODE_IMAGE"
}

This generate API call is typically the first step when a user initiates TOTP setup. The qrCode (base64 encoded) can be directly embedded into an <img> tag on your registration page, allowing the user to scan it with their authenticator app.

The register API

The register API is used to finalize the TOTP credential registration for a user after they have scanned the QR code and obtained their initial OTP code.

Endpoint

POST YOUR_KEYCLOAK_BASE_URL/admin/realms/YOUR_REALM/totp-resources/register

Request

• Method:POST

• Headers:

  • Content-Type:application/json

  • Authorization:Bearer USER_ACCESS_TOKEN

• Body:

json

{
    "deviceName": "My Authenticator App",
    "encodedSecret": "YOUR_ENCODED_TOTP_SECRET",
    "initialCode": "123456",
    "overwrite": true
}

• deviceName (String, required): A friendly name for the device (e.g., "My Phone", "Google Authenticator"). This helps users identify their TOTP devices.

• encodedSecret (String, required): The encoded secret obtained from the generate API.

• initialCode (String, required): The current OTP code generated by the user's authenticator app after scanning the QR code. This is used to verify the setup.

• overwrite (Boolean, required): If true, any existing TOTP credential for the user will be replaced. If false and a TOTP credential already exists, the registration will fail.

Response

• Status Code:

  • 201 Created: Successfully registered the TOTP credential.
  • 400 Bad Request: If any required parameter is missing.
  • 409 Conflict: overwrite is false and a credential already exists.
  • 401 Unauthorized: If the user access token is invalid or missing.
  • 500 Internal Server Error: Failed to register the TOTP credential.

This API call should be made after the user has successfully scanned the QR code and provided the first OTP generated by their authenticator app. This ensures that the setup was successful on their device.

The verify API

The verify API is used to validate an OTP code provided by a user against their registered TOTP credential.

Endpoint

POST YOUR_KEYCLOAK_BASE_URL/admin/realms/YOUR_REALM/totp-resources/verify

Request

• Method:POST

• Headers:

  • Content-Type:application/json

  • Authorization:Bearer USER_ACCESS_TOKEN

• Body:

json

{
    "code": "123456",
    "deviceName": "My Authenticator App"
}

• code (String, required): The OTP code entered by the user.

• deviceName (String, required): The name of the device the OTP is associated with.

Response

• Status Code:

  • 200 OK: The OTP code is valid.

  • 400 Bad Request: The code or devicename is missing.

  • 401 Unauthorized: The TOTP credential is missing or TOTP code is invalid.

This verify API is useful to verify that user TOTP has been registered correctly.