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#