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
400witherror_codevalidation.field_requiredon thescopesfield. - Every scope must exist in the catalog; an unknown one returns
400withvalidation.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 returns400, and a secret test key is created without them. - Only a person creates keys: a request authenticated with an API key gets
403withcodeapi_key_not_allowed. allowed_ipstakes 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:
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:
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"]}'
{
"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:
{
"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.