API keys

Bearer credentials for the REST API. See Authentication for how they are used and how to keep them safe.

List keys

GET /keys/

Returns array<ApiKey>. Prefix and last-used only, never the secret.

Create a key

POST /keys/create

Body { name: string }. Returns an ApiKey plus key: string. The full secret, shown this one time only.

cURL

curl https://api.sautipbx.com/api/keys/create \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "production server" }'

# → 201 Created: the full "key" is shown this one time only
# { "uuid": "...", "prefix": "sk_live_ab", "key": "sk_live_abcd..." }

Node

const res = await fetch("https://api.sautipbx.com/api/keys/create", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "production server" }),
});
const { key } = await res.json();
// store `key` now: it will not be shown again

Python

import requests

res = requests.post(
    "https://api.sautipbx.com/api/keys/create",
    headers={"Authorization": "Bearer sk_live_..."},
    json={"name": "production server"},
)
key = res.json()["key"]
# store `key` now: it will not be shown again

Shown once

We store only a hash, so a lost secret cannot be recovered. Revoke the key and create a new one.

Ten active keys per account

An account may hold 10 active keys. Creating an eleventh returns 409:

// HTTP 409
{
  "detail": "This account already has 10 active API keys, which is the limit of 10. Revoke one you no longer use, then create this one."
}

Revoked keys do not count, so revoking one frees a slot immediately.

More keys never buy more throughput: the request-rate limit is counted per account, across every key. Keys are for telling your callers apart and for revoking one of them without touching the rest.

Rotating a key

Create the new key first, deploy it, then revoke the old one. If you are already at 10, revoke a key you have retired before you create the new one, or the create fails with the 409 above. Handle that status in any script that rotates keys automatically.

Revoke a key

POST /keys/revoke

Body { uuid: string }. Returns { message: string }.

The ApiKey object

Field	Type	Description
uuid	string	Stable identifier (use with revoke).
name	string	Your label.
prefix	string	First characters of the key, to tell keys apart.
is_active	boolean	Whether the key still works.