Getting started

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_here

The 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

KeySends messagesUses creditWorks before approvalAnswer includes the code
otp_test_… (sandbox)NeverNeverYesYes, as test_code
otp_live_…YesYesNoNever

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:

ScopeAllows
sendPOST /api/v1/verify/send
checkPOST /api/v1/verify/check
readGET /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 .env file 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.

View as Markdown