Verify

Verifies a One-Time Password (OTP) code. The OTP must be in a pending state and not expired. If the code is incorrect, the attempt count is incremented. After reaching the maximum number of attempts, the OTP status is changed to failed.

Endpoint

POST /otp/verify

Authentication: Tenant authentication required

Description

The verify endpoint validates an OTP code against the stored OTP. This endpoint is used to confirm that the user has received and entered the correct OTP code before proceeding with operations such as password reset, email verification, phone verification, or OTP-based sign-in.

After successful verification:

• The OTP status is changed from pending to verified
• The OTP can now be consumed (if required by the flow)
• A success response is returned

If the OTP is already verified, the endpoint returns success without performing any additional checks.

Important: The OTP must be verified before it can be consumed. Verification is a separate step from consumption and is required in most OTP flows.

Request

Body

{
  "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "scope": "reset_password",
  "code": "123456"
}

Parameter	Type	Required	Description	Constraints
id	string	Yes	OTP token ID (from create endpoint)	Non-empty string
scope	string	Yes	OTP scope/purpose	Must be one of: email_verification, phone_verification, reset_password, otp_signin
code	string	Yes	OTP code received by the user	Non-empty string

Response

Status Code: 201 Created

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "data": {
    "success": true
  }
}

Field	Type	Description
success	boolean	Always true on success

Rate Limiting

Rate limiting is applied to prevent abuse and ensure system stability. The verify endpoint has the following rate limits:

Limit Type	Rate	Window
Per IP	30 requests	1 hour

When rate limits are exceeded, the API returns a 429 Too Many Requests status code.

For information about rate limit headers, see Rate Limiting in the overview.

Errors

For detailed explanations of all error codes, see the Error Codes page where you can find all system errors.

400 Bad Request - Validation Error

Occurs when the request body fails validation. Common causes include missing required fields or invalid scope value.

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "The provided request data is invalid.",
    "code": "VALIDATION_ERROR",
    "status": 400,
    "validation": {
      "id": "Required",
      "scope": "Invalid enum value",
      "code": "Required"
    }
  }
}

Field	Error Message	Cause
id	Required	OTP ID is missing
scope	Invalid enum value	Scope is not one of the allowed values
code	Required	OTP code is missing

404 Not Found - OTP Not Found

Occurs when the OTP with the provided ID and scope does not exist in the system.

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "OTP not found",
    "code": "OTP_NOT_FOUND",
    "status": 404
  }
}

422 Unprocessable Entity - OTP Verification Error

Occurs when the OTP cannot be verified. This includes cases where the OTP is not in a pending state, has expired, the code is incorrect, or the maximum number of attempts has been reached.

Error codes:

• OTP_NOT_PENDING - OTP is not in a pending state (may already be verified, consumed, expired, failed, or cancelled)
• OTP_EXPIRED - OTP has expired
• OTP_CODE_INCORRECT - OTP code is incorrect (attempt count is incremented)
• OTP_MAX_ATTEMPTS - OTP has reached the maximum number of attempts (status is changed to failed)

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "OTP is not pending",
    "code": "OTP_NOT_PENDING",
    "status": 422
  }
}

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "OTP has expired",
    "code": "OTP_EXPIRED",
    "status": 422
  }
}

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "OTP code is incorrect",
    "code": "OTP_CODE_INCORRECT",
    "status": 422
  }
}

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "OTP has reached the maximum number of attempts",
    "code": "OTP_MAX_ATTEMPTS",
    "status": 422
  }
}

429 Too Many Requests - Rate Limit Exceeded

Occurs when the rate limit is exceeded. See Rate Limiting section for details.

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "Too many requests",
    "code": "TOO_MANY_REQUESTS",
    "status": 429
  }
}

500 Internal Server Error

Occurs when an internal error happens during OTP verification. Common causes include tenant configuration issues or other unexpected system state.

Error codes:

• TENANT_NOT_CONFIGURED - Tenant OTP configuration is missing or invalid
• INTERNAL_SERVER - General internal server error

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "Tenant OTP configuration is missing",
    "code": "TENANT_NOT_CONFIGURED",
    "status": 500
  }
}

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "error": {
    "message": "Something went wrong on our side.",
    "code": "INTERNAL_SERVER",
    "status": 500
  }
}

Notes

• The OTP must be verified before it can be consumed