API keys

How to create secret and restricted keys, recognise them by prefix and last four characters, rotate them with an overlap and revoke them at once.

An API key authenticates a server or an automation against the API without a user session. Each key belongs to the context it was created in, and only a person can manage keys: a request authenticated with an API key that tries to create, rotate or revoke keys gets 403 with code: "api_key_not_allowed", whatever scopes that key holds.

Kinds and prefixes#

The prefix encodes the key's mode and kind, so you can tell what a key is from a config file or a log line before you use it.

Prefix Kind (kind) Mode (mode)
sk_live_ secret live
sk_rlive_ restricted live
sk_test_ secret test
sk_rtest_ restricted test

sk is the default start. An installation can set its own (2 to 8 lowercase letters or digits) with branding.api_key_prefix, so its keys read <prefix>_live_ and so on. Keys made with an earlier prefix, such as mt_live_, keep working: a key is looked up by its hash, and every prefix of this shape is accepted.

A secret key receives every grantable scope its creator holds at creation time. A restricted key receives only the scopes listed in scopes; each one must exist in the catalog and be held by the creator. A sandbox issues test keys only, and everywhere else issues live keys only. Outside a sandbox, a test key never carries money-moving scopes such as invoices:write or payments:write.

Create a key#

In the dashboard, open Developers > API keys and click New key. Fill in Name, pick a Type (Secret: your permissions or Restricted: your choice), a Mode and, optionally, Allowed addresses. Creating keys needs the developer:write scope, which the utility's Owner and Administrator roles include.

Through the API, send a person's access token, not a key:

bash
curl -sS -X POST "$BUSINESS_API/developer/api-keys" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Readings integration","mode":"test","scopes":["business:readings:create"]}'
json
{
  "id": "key_2nH7sQ4vTb9LxW3mKc8RzPe1JdY",
  "tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
  "context_id": "mbr_2mB5uL0rXy2SgA8oMd4WiQ9tEkF",
  "context_type": "tenant",
  "name": "Readings integration",
  "kind": "restricted",
  "mode": "test",
  "prefix": "sk_rtest_4fQ9",
  "last_four": "Xi3q",
  "scopes": ["business:readings:create"],
  "status": "active",
  "created_by": "usr_2mB4tK9qWx1RfZ7nLc3VhP8sDjE",
  "created_at": "2026-11-19T08:42:10Z",
  "secret": "sk_rtest_4fQ9xKp2LmZ7vR3nT8cWbY6hJ1sDgA5eNuVoXi3q"
}

From the command line, gotactl api-keys create --name "Readings integration" --mode test --scope business:readings:create --out key.txt sends the same request. The flags are --name (key name), --mode (live or test), --scope (a scope to grant, repeatable), --out (write the secret to a 0600 file instead of stdout) and --show-secret (print the secret even on a TTY).

Rotate a key#

Rotating (the API calls it roll) issues a new key with the same name, kind, mode, scopes, allowed addresses and expiry, and keeps the old key working for the overlap. Send overlap_seconds between 0 and 604800; without it the overlap is 24 hours, and it never runs past the old key's own expiry.

bash
curl -sS -X POST "$BUSINESS_API/developer/api-keys/key_2nH7sQ4vTb9LxW3mKc8RzPe1JdY/roll" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"overlap_seconds":3600}'

The 201 response carries the new key, with rolled_from_id set to the old id and a fresh secret. In the dashboard, the Rotate action opens Rotate this key? with an Overlap field (Ends immediately, 1 hour, 24 hours or 7 days). Only an active key that has not been rotated yet can be rotated; otherwise the response is 409 with error_code: "state.invalid_transition".

Revoke a key#

DELETE $BUSINESS_API/developer/api-keys/{id} ends the key immediately and returns 204. In the dashboard, use Revoke. The next request made with that key gets 401 with detail: "Credentials have been revoked". A key whose overlap has run out gets 401 with detail: "Credentials have expired".

Next steps#