HTTP API Reference

REST endpoints for the WordAuth OTP service. Base URL: https://api.wordauth.com

Authentication: All requests require an X-API-Key header containing a valid WordAuth API key.

POST

/v1/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.

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

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

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

POST

/v1/validate

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

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

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/generate
session_id	string \| null	No	Alternative to otp_id for session-based validation

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

{ "status": "ok" }