/Quickstart

Get started

Quickstart

Send your first one-time passcode in one call - bring your own code - or run the fully managed two-call verify. About five minutes.

1. Get an API key

Every request authenticates with a bearer key. Use a test key (sk_test_…) while you build - it runs in the sandbox and never sends a real SMS. See Authentication for the details.

bash
export OTPRELAY_API_KEY="sk_test_your_key_here"

2. Send a verification

Send the user's phone number in E.164 format - that's the only required field. OTPRelay generates the code, sends it by SMS from the shared OTPRelay sender, and returns a verification with status: "pending". There is nothing to register.

bash
curl https://api.otprelay.io/v1/verifications \  -H "Authorization: Bearer sk_test_••••" \  -H "Content-Type: application/json" \  -d '{    "to": "+966512345678"  }'

In test mode, the code is predictable

Sandbox verifications accept 000000 as the valid code (or set custom_code when sending), so you can write end-to-end tests without a real handset.

3. Check the code

When the user types the passcode, send it back with the same phone number. A correct code returns status: "approved" and verified: true.

bash
curl https://api.otprelay.io/v1/verifications/check \  -H "Authorization: Bearer sk_test_••••" \  -H "Content-Type: application/json" \  -d '{    "to": "+966512345678",    "code": "418207"  }'

Prefer your own code?

If you already generate the OTP yourself, skip the managed verify and use OTPRelay purely for delivery. POST the number and the code you generated to /v1/messages - OTPRelay wraps it in the pre-cleared template and delivers it with automatic route and operator failover. You compare the code on your side; OTPRelay never stores or checks it.

bash
curl https://api.otprelay.io/v1/messages \  -H "Authorization: Bearer sk_test_••••" \  -H "Content-Type: application/json" \  -d '{    "to": "+966512345678",    "code": "418207"  }'

See the full request and response - Send a code.

What's next