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

```bash
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"]}'
```

```json
{
  "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"
}
```

✓ Checkpoint: o campo `secret` aparece apenas nesta resposta. A partir daqui, `GET $BUSINESS_API/developer/api-keys` mostra a chave só por `prefix` e `last_four`, e o painel faz o mesmo na coluna **Chave**.

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.

```bash
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"`.

## Próximos passos

- [Escolher as permissões de uma chave restrita](/docs/getting-started/restricted-keys)
- [Como uma chave fica ligada a um contexto](/docs/getting-started/contexts)
- [Chaves de teste no sandbox](/docs/getting-started/sandbox)

