PT EN

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 é 400 com error_code validation.field_required no campo scopes.
  • Cada permissão tem de existir no catálogo; uma desconhecida devolve 400 com validation.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 devolve 400, e uma chave secreta de teste fica sem elas.
  • Só uma pessoa cria chaves: um pedido feito com uma chave de API recebe 403 com code api_key_not_allowed.
  • allowed_ips aceita 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:

bash
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:

bash
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"]}'
json
{
  "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:

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

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.

Próximos passos#