OTP

4 endpoints

Generate and validate one-time passwords. OTP generate/validate use your app domain at /api/v1/otp/*. Settings are sub-org scoped.

otp.generate

otp.verify

otp.send.email

otp.send.sms

otp.settings.read

otp.settings.write

Generate and validate one-time passwords. OTP generate/validate use your app domain at /api/v1/otp/*. Settings are sub-org scoped.

POST

/v1/otp/generate

Generate a new two-word OTP. The code is always returned in the response; SMS and email delivery are optional and do not affect the response.

Request Headers

Param	Type	Required	Description
X-API-Key	string	Yes	Your WordAuth API key

Request Body

Param	Type	Required	Description
session_id	string \| null	No	Associate the OTP with a caller session
ttl_seconds	integer	No	OTP expiry in seconds (default: 300)
email	string \| null	No	Send the OTP to this email address
phone	string \| null	No	Send the OTP to this phone number via SMS

Response — 200

{ "otp_id": "3f6a1b2c-...", // store this to validate later "code": "red bird", "session_id": null, "expires_at": "2026-04-01T12:05:00Z" }

POST

/v1/otp/validate

Validate a previously-generated OTP. Either otp_id or session_id must be provided alongside code.

Request Headers

Param	Type	Required	Description
X-API-Key	string	Yes	Your WordAuth API key

Request Body

Param	Type	Required	Description
code	string	Yes	The word pair entered by the user
otp_id	string \| null	No	The otp_id returned from /v1/otp/generate
session_id	string \| null	No	Alternative to otp_id for session-based validation

Response — 200

// Success { "valid": true } // Failure { "valid": false, "message": "Code has expired" }

GET

/healthz

Health check endpoint for load balancers and container platforms. Performs no database checks — suitable as a liveness probe.

Response — 200

{ "status": "ok" }

OTP settings

GET

/v1/otp/settings

Get OTP policy settings for a sub-organization. Requires otp.settings.read.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

Response — 200

{ "settings": { "mode": "phrase", "ttl_seconds": 300 } }

PATCH

/v1/otp/settings

Update OTP mode, TTL, rate limits, and delivery channels. Requires otp.settings.write.

Query Parameters

Param	Type	Required	Description
subOrgId	string	No	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

Request Body

Param	Type	Required	Description
mode	string	No	phrase, digit, or both
ttl_seconds	integer	No	OTP expiry in seconds (default: 300)
channel_sms	boolean	No	Enable SMS delivery channel
channel_email	boolean	No	Enable email delivery channel
subOrgId	string	Yes	Sub-organization ID. Required for org-wide keys on write operations; optional on list when the key is scoped to one sub-org.

Response — 200

{ "settings": { /* updated */ } }