Skip to main content

Chaves de API

Uma chave de API é a credencial de um consumidor. Ela é mostrada uma única vez, no momento da emissão, e depois só aparece mascarada.

Formato​

nnag_ + 43 caracteres [0-9A-Za-z]

São 32 bytes aleatórios codificados em base62 — 256 bits de entropia. Na listagem e em qualquer leitura posterior você vê apenas nnag_****<4 últimos> (por exemplo nnag_****a9Zx) e o prefixo exibível nnag_XXXX.

Como o produto guarda​

OndeO quêPara quê
Verificaçãoum resumo criptográfico da chavebusca e verificação em cada requisição
Reconstruçãoa chave cifrada, com uma chave de criptografia do produtoreprovisionar o runtime se a configuração dele se perder; apagada depois que a revogação é confirmada nas réplicas
Runtimecredencial cifrada no armazenamento de configuração do gateway, com chave própriaautenticar a requisição

Nunca há texto claro em disco nem em log. A chave cifrada existe porque, se o runtime perder a configuração, o gateway precisa reconstruí-la a partir da base, inclusive as chaves.

Emitir​

curl -sS -X POST "$BASE/v1/consumers/$CONSUMER_ID/credentials" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: emissao-chave-2026-10-22' \
  -d '{"name":"producao","expires_at":"2027-10-22T00:00:00Z"}'

Resposta 201 — o campo key aparece só aqui:

{
  "id": "0192f3a4-1111-7000-8000-000000000001",
  "consumer_id": "0192f3a4-2222-7000-8000-000000000002",
  "name": "producao",
  "prefix": "nnag_7Hq2",
  "masked_key": "nnag_****a9Zx",
  "status": "ACTIVE",
  "expires_at": "2027-10-22T00:00:00Z",
  "key": "nnag_EXEMPLO…"
}

A resposta vem com Cache-Control: no-store. Se a mesma requisição for repetida com a mesma Idempotency-Key, você recebe os metadados de novo — não a chave. Por isso: guarde a chave antes de fechar a tela.

Rotação sem queda​

O caminho é sempre "emitir a nova, migrar, revogar a antiga" — nunca o contrário:

  1. Emita uma segunda chave para o mesmo consumidor (até 5 ativas).
  2. Distribua a nova chave para a aplicação e confirme que ela está em uso.
  3. Revogue a antiga.

As duas funcionam simultaneamente, então não existe janela de erro. A propagação da nova chave e da revogação para as máquinas do gateway é feita por observação da configuração; num ambiente real, conte com segundos.

Revogar​

DELETE /v1/consumers/{id}/credentials/{credentialId} marca REVOKED e espera alguns segundos (10 s por padrão) a confirmação de ausência da credencial em todas as máquinas do gateway:

{
  "id": "0192f3a4-1111-7000-8000-000000000001",
  "consumer_id": "0192f3a4-2222-7000-8000-000000000002",
  "status": "REVOKED",
  "revoked_at": "2026-10-22T12:05:00Z",
  "propagation": {"confirmed": true, "replicas": 2, "confirmed_replicas": 2}
}

Se confirmed vier false, a revogação já está registrada e o runtime continua sendo atualizado; o campo só informa que a confirmação não chegou dentro da janela. Consulte de novo em instantes.

Duas garantias que valem saber:

  • repetir o DELETE não espera de novo: só a transição ACTIVE → REVOKED aguarda a confirmação; as chamadas seguintes respondem na hora com o estado atual;
  • confirmada a ausência em todas as máquinas, o texto cifrado da chave é apagado do banco. A linha continua existindo para histórico e auditoria, com masked_key.

Chave vazou: o que fazer​

  1. Revogue a chave (o DELETE no recurso da credencial).
  2. Confirme propagation.confirmed = true.
  3. Emita uma chave nova e redistribua.
  4. Se a chave estava em código público, considere suspender o consumidor inteiro (PATCH {"status":"SUSPENDED"}) enquanto investiga.
  5. Registre o incidente internamente.

Uma chave revogada não volta: o runtime é derivado do banco, e o banco só readmite credencial ACTIVE.

Não "rotacione" sem revogar: duas chaves ativas ao mesmo tempo é o desenho para migração, não para remediação.

Expiração​

expires_at é opcional, mas recomendado. A validade máxima aceita é de 2 anos. Quando a data passa, a chave deixa de autenticar e o estado vira EXPIRED. Renovar = emitir outra.

Boas práticas​

  • Guarde a chave em cofre de segredos, nunca no repositório.
  • Uma chave por ambiente por aplicação (producao, homologacao) — nunca uma chave compartilhada entre serviços, porque a revogação fica impossível sem quebrar todo mundo.
  • Nomeie as chaves (name) com o que elas identificam: producao, integracao-fulano, job-relatorio.
  • Não coloque a chave na URL: o gateway remove o argumento reservado e a chave não autentica, além de vazar em logs.
  • Se o consumidor usa o cabeçalho Ocp-Apim-Subscription-Key (compatibilidade com Azure API Management), escolha esse nome na política de segurança. O gateway aceita apenas o cabeçalho escolhido: o outro é removido antes da autenticação.

Próximos passos​