Authentication
API keys, test and live mode, and where keys must (and must never) be kept.
Every request carries an API key:
Authorization: Bearer otp_live_your_key_hereThe X-API-Key: <key> header is accepted too. Keys are created and revoked on the dashboard (API keys). A key is shown once, when it is made; OTP.ps keeps only a hash of it.
Two kinds of key
| Key | Sends messages | Uses credit | Works before approval | Answer includes the code |
|---|---|---|---|---|
otp_test_… (sandbox) | Never | Never | Yes | Yes, as test_code |
otp_live_… | Yes | Yes | No | Never |
Test and live are completely separate: a verification made with a test key can't be checked or read with a live key, and the reverse. Limits are counted separately too. See Sandbox.
Permissions and daily limits
Each key has permissions (scopes), chosen when you create it:
| Scope | Allows |
|---|---|
send | POST /api/v1/verify/send |
check | POST /api/v1/verify/check |
read | GET /api/v1/verify/{id}, /balance, /usage, /limits |
Give each key only what it needs: a reporting script needs read only. Without the needed scope the API answers 403 insufficient_scope. Keys created before permissions existed have all three.
A key can also have its own daily message limit, on top of the account's spending limits: once reached, that key alone answers 429 spending_limit_reached until the next day. GET /api/v1/limits shows a key's permissions and limits.
Keep keys on the server
- Put the key in an environment variable (
OTP_PS_API_KEY) on your backend. Never commit it to Git; add your.envfile to.gitignore. - Never put a key in browser JavaScript, a mobile app, a React/Vue/Next.js client component, or anything the customer downloads. The API sends no CORS headers, so a browser can't call it anyway.
- Your website or app calls your own backend (for example
/api/otp/send), and your backend calls OTP.ps. - Use separate keys per application, so one can be revoked without stopping the others.
- If a key leaks, revoke it on the dashboard at once and create a new one.
Errors
A missing, malformed or revoked key answers 401 unauthorized. A live key on an account that isn't approved yet answers 403 account_pending. See Errors.