Chaves restritas
Dê a cada integração uma chave com apenas as permissões de que precisa, e saiba porque o pedido de criação é recusado quando uma permissão não serve.
Chave secreta ou restrita#
Há dois tipos de chave. A chave Secreta (sk_live_ ou sk_test_) recebe, no momento da criação, todas as permissões que quem a cria pode conceder. A chave Restrita (sk_rlive_ ou sk_rtest_) leva só as permissões escolhidas, por isso uma fuga expõe apenas essas operações. O prefixo diz logo o tipo e o modo: r para restrita, test ou live para o modo.
Se o pedido trouxer scopes e não indicar kind, a chave fica restrita; sem scopes, fica secreta.
Regras ao criar#
- Uma chave restrita precisa de pelo menos uma permissão; sem nenhuma, a resposta é
400comerror_codevalidation.field_requiredno camposcopes. - Cada permissão tem de existir no catálogo; uma desconhecida devolve
400comvalidation.invalid_choice. - Quem cria a chave tem de ter cada permissão que lhe dá; caso contrário, a resposta é
403. - As permissões de escrita que movem dinheiro (
invoices:write,payments:write,billing_runs:write,collections:write,tariffs:write,business:subscription:change,business:subscription:cancel) só entram numa chave de teste quando o operador da instalação activou os pagamentos de teste; caso contrário, pedi-las numa chave restrita de teste devolve400, e uma chave secreta de teste fica sem elas. - Só uma pessoa cria chaves: um pedido feito com uma chave de API recebe
403comcodeapi_key_not_allowed. allowed_ipsaceita até 50 endereços IP ou intervalos CIDR;expires_at, se vier, tem de estar no futuro.
A chave continua a funcionar só enquanto quem a criou mantiver acesso activo e todas as permissões que ela leva. Se alguma for retirada a essa pessoa, os pedidos com a chave passam a receber 401.
Criar uma chave restrita#
No painel, abra Programadores > Chaves de API, carregue em Nova chave e escolha Restrita: à sua escolha em Tipo. Use Filtrar permissões para encontrar cada uma, marque-as e carregue em Criar chave. Pela CLI, repita --scope por cada permissão:
gotactl api-keys create --name importacao-leituras --mode test \
--scope business:readings:create --scope business:readings:import --out key.txt
Pela API, o pedido usa o token da sua sessão, porque uma chave não pode criar chaves:
curl -sS -X POST "$BUSINESS_API/developer/api-keys" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Importação de leituras","kind":"restricted","mode":"test","scopes":["business:readings:create","business:readings:import"],"allowed_ips":["203.0.113.10"]}'
{
"id": "key_2pQ8aNcV5tY2kM7wE3rU9gZ4bXf",
"name": "Importação de leituras",
"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"
}
O campo secret só vem nesta resposta e na de rodar a chave. Para ver que permissões pode dar, peça GET $BUSINESS_API/developer/scopes: devolve data com a lista, já limitada às que tem.
Permissões por tarefa#
| Tarefa | Operação | Permissão |
|---|---|---|
| Listar clientes | listCustomers |
business:customers:read |
| Criar clientes | createCustomer |
business:customers:create |
| Registar uma leitura | submitManualMeterReading |
business:readings:create |
| Importar leituras | importMeterReadings |
business:readings:import |
| Consultar facturas | listInvoices |
invoices:read |
| Emitir uma factura avulsa | issueManualInvoice |
invoices:write |
| Registar um pagamento | recordPayment |
payments:write |
| Consultar eventos | listDeveloperEvents |
developer:read |
Quando falta uma permissão#
Uma chave que só tem business:customers:read e tenta criar um cliente recebe:
{
"type": "about:blank",
"title": "Forbidden",
"status": 403,
"detail": "Access denied",
"instance": "$BUSINESS_API/customers",
"code": "FORBIDDEN",
"error_code": "auth.forbidden",
"request_id": "req_0b8e4d62a91f4c37b5d2e8f61a3c9074"
}
Uma chave restrita não pode ser alargada: crie outra com o conjunto certo e revogue a antiga. Rodar uma chave mantém as mesmas permissões, e só quem tem todas elas a pode rodar.