Authentication

The API uses bearer tokens. Every request must carry your token in the Authorization header.

Authorization: Bearer YOUR_API_TOKEN

Create and revoke tokens from Settings → API Keys & Webhooks. A token is shown only once at creation, store it securely and never expose it in client-side code.

Scopes (abilities)

Limit what each token is allowed to do.

Each token is granted one or more scopes. A request to an endpoint outside the token's scopes returns 403. Available scopes:

Idempotency

Make retries safe so you never double-send.

Side-effecting POSTs (sms/send, otp/send, voice/send) accept an Idempotency-Key header. If a request is retried with the same key, the original response is replayed instead of performing the action again, so a network retry never double-sends or double-charges.

Idempotency-Key: a-unique-key-per-request

A replayed response carries Idempotent-Replayed: true. Concurrent duplicates return 409.

IP allowlisting

Restrict which source addresses can call your API.

You can restrict your API to specific source IPs from the admin allowlist. With no IPs configured the API is open; once any IP is added, requests from other addresses return 403 (ip_not_allowed).

Rate limits

How many requests you can make.

Requests are throttled per token (default 120/min); standard X-RateLimit-* headers are returned. OTP sends are additionally rate-limited per source IP. Exceeding a limit returns 429 with Retry-After.

Errors

How failures are reported.

Errors return a JSON body with a message and a machine-readable error code.