# Restricted keys

Give each integration a key that holds only the scopes it needs, and learn why key creation is refused when a scope does not fit.


## Secret or restricted

There are two kinds of key. A **Secret** key (`sk_live_` or `sk_test_`) receives, when it is created, every scope its creator can grant. A **Restricted** key (`sk_rlive_` or `sk_rtest_`) carries only the scopes you pick, so a leak exposes only those operations. The prefix shows kind and mode at a glance: `r` for restricted, `test` or `live` for the mode.

When a request sends `scopes` and leaves out `kind`, the key is restricted; without `scopes`, it is secret.

## Creation rules

- A restricted key needs at least one scope; with none, the response is `400` with `error_code` `validation.field_required` on the `scopes` field.
- Every scope must exist in the catalog; an unknown one returns `400` with `validation.invalid_choice`.
- The creator must hold every scope they put on the key; otherwise the response is `403`.
- The money-moving write scopes (`invoices:write`, `payments:write`, `billing_runs:write`, `collections:write`, `tariffs:write`, `business:subscription:change`, `business:subscription:cancel`) go on a test key only when the installation's operator has turned on test payments; otherwise asking for them on a restricted test key returns `400`, and a secret test key is created without them.
- Only a person creates keys: a request authenticated with an API key gets `403` with `code` `api_key_not_allowed`.
- `allowed_ips` takes up to 50 IP addresses or CIDR ranges; `expires_at`, when sent, must be in the future.

A key keeps working only while its creator still has active access and every scope the key carries. If one of those scopes is taken away from that person, requests with the key start getting `401`.

## Create a restricted key

In the dashboard, open **Developers** > **API keys**, click **New key** and pick **Restricted: your choice** under **Type**. Use **Filter permissions** to find each scope, tick them and click **Create key**. With the CLI, repeat `--scope` once per scope:

```bash
gotactl api-keys create --name readings-import --mode test \
  --scope business:readings:create --scope business:readings:import --out key.txt
```

Through the API, the request uses your session token, because a key cannot create keys:

```bash
curl -sS -X POST "$BUSINESS_API/developer/api-keys" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Readings import","kind":"restricted","mode":"test","scopes":["business:readings:create","business:readings:import"],"allowed_ips":["203.0.113.10"]}'
```

```json
{
  "id": "key_2pQ8aNcV5tY2kM7wE3rU9gZ4bXf",
  "name": "Readings import",
  "kind": "restricted",
  "mode": "test",
  "prefix": "sk_rtest_C3J2",
  "last_four": "VNPk",
  "scopes": ["business:readings:create", "business:readings:import"],
  "status": "active",
  "created_by": "usr_2pQ9fLhS3jD6qA1zC8vN5mK7eRt",
  "created_at": "2026-11-19T08:30:12Z",
  "allowed_ips": ["203.0.113.10"],
  "secret": "sk_rtest_C3J27XDCG2LmlZGEONYlgCtjfIZ4SOcMz9CPVNPk"
}
```

The `secret` field appears only in this response and in the one for rotating the key. To see which scopes you can grant, call `GET $BUSINESS_API/developer/scopes`: it returns `data` with the list, already narrowed to the scopes you hold.

## Scopes by task

| Task | Operation | Scope |
| :--- | :--- | :--- |
| List customers | `listCustomers` | `business:customers:read` |
| Create customers | `createCustomer` | `business:customers:create` |
| Submit a reading | `submitManualMeterReading` | `business:readings:create` |
| Import readings | `importMeterReadings` | `business:readings:import` |
| Read invoices | `listInvoices` | `invoices:read` |
| Issue a one-off invoice | `issueManualInvoice` | `invoices:write` |
| Record a payment | `recordPayment` | `payments:write` |
| Read events | `listDeveloperEvents` | `developer:read` |

## When a scope is missing

A key that holds only `business:customers:read` and tries to create a customer gets:

```json
{
  "type": "about:blank",
  "title": "Forbidden",
  "status": 403,
  "detail": "Access denied",
  "instance": "$BUSINESS_API/customers",
  "code": "FORBIDDEN",
  "error_code": "auth.forbidden",
  "request_id": "req_0b8e4d62a91f4c37b5d2e8f61a3c9074"
}
```

A restricted key cannot be widened: create another one with the right set and revoke the old one. Rotating keeps the same scopes, and only someone who holds all of them can rotate the key.

## Next steps

- [Key lifecycle: rotate and revoke](/docs/getting-started/api-keys)
- [Each operation's scopes in the API reference](/docs/api/business)
- [Get ready to go live](/docs/go-live)

