Requesting an OTP code

Requesting a one-time passcode

Overview
Permissions and Authentication
Headers
HTTP Parameters
Sample requests
Sample response
Possible error responses

Overview

Call name: otp-request
Endpoint URL: https://{API hostname}/auth/otp-request
Request methods: POST
Request Content-Types: application/x-www-form-urlencoded
Response Content-Type: application/json
Auth required: yes

Requests a 6-digit one-time passcode ("OTP") to be sent to a user, so that the user can confirm a contact detail on their account. The purpose parameter selects which contact detail is being verified:

phone_number_verification_rate_limit — the code is sent by SMS to the user's phone number.
email_verification_rate_limit — the code is sent by email to the user's email address.

The code is verified with otp-verify using the verification_code_key returned by this endpoint. For an overview of both verification flows, see Verifying user contact details.

The contact detail supplied in the request must match the one stored on the user account, and the relevant verification setting must be enabled on the user's chain (verify_phone_numbers for phone numbers, email_verification_method set to otp for email addresses). Both are set with alter-chain.

Requests are rate limited to one per 60 seconds, counted both per contact detail per chain and per user per chain.

Permissions and Authentication

This API call requires a valid Spaaza session. The session can be as follows:

User authentication: a session generated by an end-user login. The session user must be the user identified by user_id.
Admin authentication: the performing user needs to be logged in and have write access to the chain to which the user is connected.

Headers

The following headers can/must be passed to the API call:

Parameter	Description
X-Spaaza-Session-User-Id	(mandatory) The user ID of the session, see Authentication.
X-Spaaza-Session-Key	(mandatory) The session key of the session, see Authentication.
X-Spaaza-API-Version	(optional) The API version, see versioning.

HTTP Parameters

The following HTTP parameters can be passed to the API:

Parameter	Description
purpose	(string, mandatory) Which contact detail is being verified. Either `phone_number_verification_rate_limit` or `email_verification_rate_limit`.
user_id	(integer, mandatory) The ID of the user whose contact detail is being verified.
chain_id	(integer, mandatory) The ID of the chain the user belongs to.
e164PhoneNumber	(string, mandatory when `purpose` is `phone_number_verification_rate_limit`) The phone number to verify, in E.164 format. It must match the phone number on the user account.
email	(string, mandatory when `purpose` is `email_verification_rate_limit`) The email address to verify. It must match the email address (`username`) on the user account, ignoring case.

Sample requests

Requesting a code by email:

POST https://{API hostname}/auth/otp-request
Content-Type: application/x-www-form-urlencoded

purpose=email_verification_rate_limit&email=john.smith%40example.com&user_id=3635922&chain_id=1743

Requesting a code by SMS:

POST https://{API hostname}/auth/otp-request
Content-Type: application/x-www-form-urlencoded

purpose=phone_number_verification_rate_limit&e164PhoneNumber=%2B31655222555&user_id=3635922&chain_id=1743

Sample response

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "rate_limit_seconds_until_reset": 60,
        "result_type": "otp-request",
        "verification_code_expiry_date": "2026-07-29T09:15:54+00:00",
        "verification_code_key": "8c2f910285d8adbe7c316f2d2be9a991"
    }
}

The response fields are:

verification_code_key — the key which must be submitted to otp-verify together with the code the user received. The code itself is never returned in the response.
verification_code_expiry_date — the moment the code expires. Codes are valid for 5 minutes.
rate_limit_seconds_until_reset — the number of seconds until another code can be requested.

Possible error responses

The following represents a list of possible error responses for the otp-request endpoint:

Code	Name and Description	HTTP Status Code
3	http_vars_missing A required parameter is missing, or `user_id` / `chain_id` is not an integer, or the supplied phone number is not a valid E.164 number.	400
6	no_valid_session The user needs to be logged in and a valid session key needs to be sent.	401
424	access_denied The session user does not match the target user and does not have admin privileges on the chain.	403
510	dispatching_event_error The verification message could not be dispatched.	400
534	invalid_parameter The `purpose` value is not one of the allowed values, or the supplied email address is not a valid email address.	400
548	phone_number_verification_rate_limit_exceeded The rate limit for phone number verification has been exceeded.	400
549	phone_number_verification_mismatch No user was found for the `user_id`, the user does not belong to the `chain_id`, or the phone number does not match the account.	409
551	json_encoding_error An error occurred while processing verification data.	500
554	phone_number_verification_not_enabled Phone number verification is not enabled for the chain.	400
557	email_verification_rate_limit_exceeded The rate limit for email verification has been exceeded.	400
558	email_verification_mismatch No user was found for the `user_id`, the user does not belong to the `chain_id`, or the email address does not match the account.	409
559	email_verification_not_enabled The chain's `email_verification_method` is not set to `otp`.	400

Requesting a one-time passcode​

Contents​

Overview​

Permissions and Authentication​

Headers​

HTTP Parameters​

Sample requests​

Sample response​

Possible error responses​