Create

Creates and sends a One-Time Password (OTP) to the specified recipient via email or SMS. When a new OTP is created, any previously pending OTPs for the same scope, method, and recipient are automatically cancelled.

Endpoint

POST /otp/create

Authentication: Tenant authentication required

Description

The create endpoint generates a new OTP and sends it to the user via the specified delivery method (email or SMS). This endpoint is used for email verification and phone verification flows.

Important: The reset_password and otp_signin scopes cannot be created using this endpoint. These OTPs are automatically created by their respective logic flows (password reset and OTP sign-in endpoints).

After successful OTP creation:

• A new OTP record is created in the system
• Any previously pending OTPs for the same scope, method, and recipient are automatically cancelled
• The OTP code is sent to the recipient via the specified method (email or SMS)
• OTP information (ID, expiration time, resend interval) is returned in the response

Note: In the staging environment, OTP codes are not sent via email or SMS. Instead, they are shared in the webmixhub-otp Slack channel for testing purposes.

Request

Body

{
  "scope": "email_verification",
  "scopeId": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "method": "email",
  "recipient": "user@example.com"
}

Parameter	Type	Required	Description	Constraints
scope	string	Yes	OTP scope/purpose	Must be one of: email_verification, phone_verification. Note: reset_password and otp_signin scopes are created automatically by their respective logic flows and cannot be created using this endpoint
scopeId	string	No	Optional identifier for the scope	Non-empty string
method	string	Yes	Delivery method	Must be "email" or "sms"
recipient	string	Yes	Email address or phone number	Valid email format (for email method) or valid phone number (for SMS method)

Response

Status Code: 201 Created

{
  "meta": {
    "requestId": "req-12345",
    "timestamp": "2025-01-15T10:30:00.000Z"
  },
  "data": {
    "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
    "createdAt": "2025-01-15T10:30:00.000Z",
    "expiresAt": "2025-01-15T10:35:00.000Z",
    "resendIntervalSeconds": 60
  }
}

Field	Type	Description
id	string	OTP token ID (use for verify/resend/cancel)
createdAt	string	ISO 8601 creation timestamp
expiresAt	string	ISO 8601 expiration timestamp
resendIntervalSeconds	number	Minimum seconds before resend is allowed

Rate Limiting

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

Limit Type	Rate	Window
Per IP	20 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 invalid scope value, invalid method value, invalid email format, or missing required fields.

{
  "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": {
      "scope": "Invalid enum value",
      "method": "Invalid enum value",
      "recipient": "Invalid email format"
    }
  }
}

Field	Error Message	Cause
scope	Invalid enum value	Scope is not one of the allowed values
method	Invalid enum value	Method is not "email" or "sms"
recipient	Invalid email format	Recipient format is invalid (for email method)
recipient	Required	Recipient is missing

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 creation. 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

• Use the returned id to verify, resend, or cancel the OTP
• In staging environment, OTP codes are shared in the webmixhub-otp Slack channel instead of being sent via email or SMS