# 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"
}
```

✓ Checkpoint: `secret` appears in this response only. From now on, `GET $BUSINESS_API/developer/api-keys` identifies the key by `prefix` and `last_four`, and the dashboard does the same in the **Key** column.

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

- [Choose the scopes of a restricted key](/docs/getting-started/restricted-keys)
- [How a key is tied to a context](/docs/getting-started/contexts)
- [Test keys in the sandbox](/docs/getting-started/sandbox)

