Authentication and API keys

Every request to the API carries an API key in the Authorization header, over HTTPS only:

GET /v1/balance HTTP/1.1Host: api.messaging.500calls.comAuthorization: Bearer 500c_live_…

A key belongs to your organisation, not to the person who created it, so it keeps working when people leave.

Keep keys on your server

A key can send messages and spend your balance. Keep it in a secret manager or an environment variable on your server, never in a web page, a mobile app or a code repository. The API sends no CORS headers, so browsers cannot call it. Never write a key to a log. If one leaks, revoke it, or rotate it with no grace period.

Test keys

Scopes

Each key holds one or more scopes, and each endpoint needs one:

A key without the endpoint's scope gets 403 with the code insufficient_scope. Give each integration only the scopes it needs. The API reference names each endpoint's scope.

Create a key

Owners, admins and developers create keys in the dashboard under Developers, then API keys, after confirming their password. The full key, starting 500c_live_, is shown once, when it is created. After that the dashboard shows only its first 16 characters, the display prefix, so you can tell keys apart. An organisation can have 20 active keys by default, and a key can have an expiry date. The dashboard shows when each key was last used, so unused keys are easy to find.

Rotate a key

Rotating creates a replacement key and lets the old one keep working for a grace period you choose, from none to 7 days. Deploy the new key, then let the old one lapse.

Revoke a key

Revoking stops a key at once. Revoked and expired keys stay that way.

When a request is refused

The checks run in this order, and the first that fails answers:

1. The Authorization header is present and well formed, and the key is active and not expired: otherwise 401 unauthenticated.
2. For a send or a cancel, your organisation has verified its e-mail address: otherwise 403 email_not_verified.
3. For a send or a cancel, your organisation is not suspended: otherwise 403 tenant_suspended.
4. The key holds the endpoint's scope: otherwise 403 insufficient_scope.
5. Your organisation is within its rate limit: otherwise 429 rate_limited. See rate limits.

One check comes before all of these: an address that fails authentication 30 times in a minute gets 429 rate_limited for 10 minutes, before its key is even read.

A missing header, an unknown key, a revoked key and an expired key all get the same 401 on purpose, so a guessed key learns nothing. IP allowlists for keys are coming; until then a key works from any address.