Migration Guide: OTP-Based Authentication

Overview

To strengthen account security, authenticating with username and password requires an additional one-time password (OTP), which is sent to the user via e-mail. Unlike the password-only authentication flow, where submitting valid credentials to the auth endpoint returns a JWT token pair directly, the OTP-based flow only issues the token pair after successful OTP verification.

Authentication via API token is not affected and does not require an OTP.

Comparison at a Glance

	Previous flow	OTP-based flow
Username/password login	Token pair returned immediately	OTP verification required before tokens are issued
API token authentication	No OTP	No OTP (unchanged)
Auth response body	`token_type`, `access_token`, `refresh_token`	Additionally contains `auth_status`

OTP Auth Flow

Submit credentials

Send the credentials to the Authenticate with Identifier & Password endpoint as in the previous flow:

{
  "accessors": ["voucher_owner"],
  "identifier": "<user_email>",
  "password": "<user_password>"
}

Receive `otp_required` response

If the credentials are correct, the endpoint responds without tokens:

{
  "meta": null,
  "data": {
    "token_type": null,
    "access_token": null,
    "refresh_token": null,
    "auth_status": "otp_required"
  }
}

The attribute auth_status with the value "otp_required" indicates that an OTP is required to complete authentication.

No tokens are issued at this stage: token_type, access_token, and refresh_token are null.

The request automatically triggered an e-mail to the user containing a 6-digit OTP.

Submit credentials together with the OTP

Send the credentials again to the same endpoint, this time including the otp attribute with the 6-digit code from the e-mail:

{
  "accessors": ["voucher_owner"],
  "identifier": "<user_email>",
  "password": "<user_password>",
  "otp": "123456"
}

Receive the token pair

If both the credentials and the OTP are correct, the response contains the token pair, with auth_status set to "authenticated":

{
  "meta": null,
  "data": {
    "token_type": "bearer",
    "access_token": "ey...",
    "refresh_token": "ey...",
    "auth_status": "authenticated"
  }
}

The tokens can now be used as usual for any ruther API requests.

Error Handling and OTP Expiry

If the submitted OTP is incorrect, the endpoint responds with an unauthorized error. Note that a successful otp_required response in Step 1 already confirms that the credentials themselves are correct, so an unauthorized error in Step 3 typically indicates an invalid or expired OTP.

To request a new OTP (e.g. after expiry), simply restart the flow: call the endpoint again without the otp attribute (Step 1). This triggers a new OTP e-mail.

Migration Checklist for API Clients

After submitting credentials, inspect data.auth_status in the response instead of expecting tokens immediately.

If auth_status is "otp_required", prompt the user for the 6-digit code sent to their e-mail address.

Re-submit the credentials to the same endpoint, including the additional otp field.

Proceed with the token pair once auth_status is "authenticated".

Handle unauthorized errors in the OTP step, e.g. by allowing the user to re-enter the code or restart the flow to receive a new OTP.

No changes are required for clients authenticating via API token.

Migration Guide: OTP-Based Authentication

Overview#

Comparison at a Glance#

OTP Auth Flow#

Error Handling and OTP Expiry#

Migration Checklist for API Clients#

Overview

Comparison at a Glance

OTP Auth Flow

Error Handling and OTP Expiry

Migration Checklist for API Clients