On this page

Authentication

Beta

Keys, the scopes they carry, and what the API refuses.

3 min read

Every request carries an API key as a bearer token:

Authorization: Bearer gsk_Ab3dEf6hIj9k_...

Keys are created on the Developers page of the dashboard. The full key is shown once, when it is created, and never again — we store only a hash of it, so we cannot show it to you later and neither can anyone who reads our database.

The visible start of a key (gsk_Ab3dEf6hIj9k) is safe to log and to show in a list: it identifies the key without being usable.

Scopes

Scopes are chosen when a key is created and cannot be changed afterwards. Create a key with only what its job needs — a key that can read but not buy is the difference between a leak that costs nothing and one that spends your balance.

ScopeWhat it allows
services:readThe catalogue: services, countries, prices
balance:readThe account's balance
activations:readActivations and the messages they received
activations:writeBuying, cancelling, and asking for a replacement number
rentals:readRentals and their messages
rentals:writeRenting, extending and cancelling long-term numbers

Every endpoint in the reference names the scope it needs. A key without it gets 403 and insufficient_scope, with the missing scope in the body:

{
  "code": "insufficient_scope",
  "status": 403,
  "detail": "This endpoint requires the activations:write scope.",
  "required_scope": "activations:write",
  "request_id": "req_8f3a2c"
}

What is refused

A website sign-in token. The dashboard's session token is not an API credential; /v1 answers it with 401 and authentication_required. The two are separate on purpose, so a stolen browser session cannot spend through the API and a leaked key cannot read your account pages.

A revoked key, immediately — 401 and api_key_revoked. Revoking one key leaves the others working.

Every key on the account, if API access is withdrawn or the account is restricted. Restoring access does not bring the old keys back; create new ones.

Rotating a key

Create the new key, deploy it, then revoke the old one. An account can hold five active keys at a time, which is enough to rotate without a gap and to keep separate keys for separate environments.

The one endpoint that needs no key

The OpenAPI document — it is what tells you how to get a key, so asking for one first would be a poor joke.