Chaves de API
Como criar chaves secretas e restritas, identificá-las pelo prefixo e pelos últimos quatro caracteres, rodá-las com sobreposição e revogá-las de imediato.
Uma chave de API autentica um servidor ou uma automação perante a API, sem sessão de utilizador. Cada chave pertence ao contexto em que foi criada e só pode ser gerida por uma pessoa: um pedido autenticado com uma chave de API que tente criar, rodar ou revogar chaves é recusado com 403 e code: "api_key_not_allowed", sejam quais forem as permissões dessa chave.
Tipos e prefixos#
O prefixo diz o modo e o tipo da chave, o que permite reconhecer uma chave num ficheiro de configuração ou num registo antes de a usar.
| Prefixo | Tipo (kind) |
Modo (mode) |
|---|---|---|
sk_live_ |
secret |
live |
sk_rlive_ |
restricted |
live |
sk_test_ |
secret |
test |
sk_rtest_ |
restricted |
test |
sk é o início por omissão. Uma instalação pode definir o seu (2 a 8 letras minúsculas ou algarismos) em branding.api_key_prefix, e as suas chaves começam então por <prefixo>_live_ e assim por diante. As chaves criadas com um prefixo anterior, como mt_live_, continuam a funcionar: a chave é procurada pelo seu hash, e qualquer prefixo com esta forma é aceite.
Uma chave secreta recebe todas as permissões atribuíveis que quem a cria detém nesse momento. Uma chave restrita recebe só as permissões indicadas em scopes, e cada uma tem de existir no catálogo e estar na posse de quem cria a chave. Num sandbox só se emitem chaves de teste; fora do sandbox, só chaves reais. Uma chave de teste nunca guarda permissões que movem dinheiro (invoices:write, payments:write, entre outras) fora de um sandbox.
Criar uma chave#
No painel, abra Programadores > Chaves de API e clique em Nova chave. Preencha Nome, escolha o Tipo (Secreta: as suas permissões ou Restrita: à sua escolha), o Modo e, se quiser, Endereços permitidos. A operação exige a permissão developer:write, que os papéis Proprietário e Administrador da empresa incluem.
Pela API, o pedido usa o token de acesso de uma pessoa, não uma chave:
curl -sS -X POST "$BUSINESS_API/developer/api-keys" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Integração de leituras","mode":"test","scopes":["business:readings:create"]}'
{
"id": "key_2nH7sQ4vTb9LxW3mKc8RzPe1JdY",
"tenant_id": "ten_2jR5wQ8nLm3KxT9vB6cYpZ1dHgF",
"context_id": "mbr_2mB5uL0rXy2SgA8oMd4WiQ9tEkF",
"context_type": "tenant",
"name": "Integração de leituras",
"kind": "restricted",
"mode": "test",
"prefix": "sk_rtest_4fQ9",
"last_four": "Xi3q",
"scopes": ["business:readings:create"],
"status": "active",
"created_by": "usr_2mB4tK9qWx1RfZ7nLc3VhP8sDjE",
"created_at": "2026-11-19T08:42:10Z",
"secret": "sk_rtest_4fQ9xKp2LmZ7vR3nT8cWbY6hJ1sDgA5eNuVoXi3q"
}
Na linha de comandos, gotactl api-keys create --name "Integração de leituras" --mode test --scope business:readings:create --out chave.txt faz o mesmo pedido. As opções são --name (nome da chave), --mode (modo, live ou test), --scope (permissão a conceder, repetível), --out (grava o segredo num ficheiro com permissões 0600 em vez de o mostrar) e --show-secret (mostra o segredo no terminal mesmo num TTY).
Rodar uma chave#
Rodar cria uma chave nova com o mesmo nome, tipo, modo, permissões, endereços permitidos e validade, e mantém a antiga a funcionar durante a sobreposição. Envie overlap_seconds entre 0 e 604800; sem valor, a sobreposição é de 24 horas e nunca ultrapassa a validade da chave antiga.
curl -sS -X POST "$BUSINESS_API/developer/api-keys/key_2nH7sQ4vTb9LxW3mKc8RzPe1JdY/roll" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"overlap_seconds":3600}'
A resposta 201 traz a chave nova com rolled_from_id igual ao id antigo e um secret novo. No painel, a acção Rodar abre Rodar esta chave? com o campo Sobreposição (Termina de imediato, 1 hora, 24 horas ou 7 dias). Só uma chave activa que ainda não foi rodada pode ser rodada; caso contrário, a resposta é 409 com error_code: "state.invalid_transition".
Revogar uma chave#
DELETE $BUSINESS_API/developer/api-keys/{id} termina a chave de imediato e responde 204. No painel, use Revogar. O pedido seguinte com essa chave recebe 401 com detail: "Credentials have been revoked". Uma chave cuja sobreposição terminou recebe 401 com detail: "Credentials have expired".