Verifying an OTP code

Verifying a one-time passcode

Contents

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

Overview

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

Verifies a 6-digit one-time passcode ("OTP") which was sent to a user by otp-request, or by add-user or alter-user when a phone number was stored. The same endpoint verifies both email addresses and phone numbers: the contact detail being verified is determined by the verification_code_key, so it does not need to be supplied again.

On success:

• for an email verification code, the user's email_status is set to 1 (verified)
• for a phone number verification code, the user's phone_number_status is set to 3 (verified)

For an overview of both verification flows, see Verifying user contact details.

Codes are valid for 5 minutes. Up to 5 attempts can be made per code; after that the code is invalidated and a new one must be requested. A code can only be used once. If the user's email address, phone number or chain changed after the code was requested, the code is no longer accepted, because it was issued for a different value.

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 the code was issued for.
• 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
verification_code	(string, mandatory) The 6-digit code which the user received by email or SMS.
verification_code_key	(string, mandatory) The key returned when the code was requested, by otp-request, add-user or alter-user.

Sample request

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

verification_code=418302&verification_code_key=8c2f910285d8adbe7c316f2d2be9a991

Sample response

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "result_type": "otp-verify",
        "state": "OK"
    }
}

Possible error responses

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

Code	Name and Description	HTTP Status Code
3	http_vars_missing The verification_code or verification_code_key parameter is missing.	400
5	password_error_or_non_existent The verification code is invalid or has expired, or no user was found for the code.	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
548	phone_number_verification_rate_limit_exceeded Too many attempts have been made with this verification code, and the code has been invalidated.	400
549	phone_number_verification_mismatch The phone number or chain on the user account changed after the verification code was requested.	409
550	json_malformed_data An internal data issue occurred during the verification process.	500
558	email_verification_mismatch The email address or chain on the user account changed after the verification code was requested.	409