Authentication

Every request to the otp.com API authenticates with an API key, sent as a Bearer token in the Authorization header.

Authorization: Bearer otp_live_YOUR_API_KEY

Server keys and publishable keys

There are two kinds of key, and they are not interchangeable.

Prefix	Belongs in	Can do
otp_live_… / otp_test_…	Your backend, and nowhere else	Everything: send, verify, resend, status, and exchange.
otp_pk_live_… / otp_pk_test_…	Inside your mobile app	Start a verification and answer one, through the mobile SDKs. Nothing else.

A server key is the key the rest of this reference assumes. It reads recipients and spends your balance, so it belongs in an environment variable on a machine you control.

A publishable key is meant to be readable. It ships inside your app binary, where anyone can extract it, and that is safe because of what it cannot do: it is scoped to one app, it cannot read which recipient was verified, and it cannot exchange a verification. The mobile SDKs also sign every send with a hardware-backed device key, so a publishable key lifted out of your binary is of no use outside your app.

That split is the reason a verification succeeding on a device is not a result you can act on. The device receives a short-lived verification_token and nothing else; your backend exchanges it at POST /verifications/exchange with your server key, and only that response says which recipient was verified. See Mobile SDKs for the flow end to end.

Test vs live keys

You create keys per app on the API Keys screen, in one of two environments:

Prefix	Environment	Behavior
otp_test_…, otp_pk_test_…	Sandbox	No real message is sent, nothing is charged. The accepted code is always 123456.
otp_live_…, otp_pk_live_…	Production	Real delivery over your configured channels, billed per verification sent.

Use a test key while you build and in automated tests. Switch to a live key only when you are ready to send real codes. A test publishable key also skips the device proof the SDKs normally require, which is what lets you integrate on a simulator or an emulator.

Keeping keys safe

• Never ship a server key anywhere a user can reach it, browser or app. A leaked live server key can send real messages against your balance and read the recipients behind your verifications. The publishable key exists precisely so a mobile app never has to hold one.
• Read the server key from an environment variable, not from source. Rotate it if it is ever exposed.
• Keys can be revoked at any time on the API Keys screen. A revoked or invalid key returns 401.

Errors

A missing, malformed, or revoked key returns HTTP 401 with the standard error envelope, as does a publishable key used on an endpoint that requires a server key:

{
  "error": {
    "type": "HTTPException",
    "message": "Missing, invalid, or revoked API key."
  }
}

See Error codes for the full list.