Consumidores

Consumidor é a aplicação que chama a sua API — não uma pessoa. Um consumidor tem nome, estado, chaves e um conjunto de APIs nas quais está autorizado.

O gateway autentica aplicações, não pessoas. Se você precisa identificar usuários finais, isso é papel do seu backend (ou de um JWT do seu próprio provedor de identidade, no modo JWT_OIDC, em que o gateway valida o token e o seu backend lê as claims).

Campos

Campo	Regra
name	1 a 80 caracteres; único dentro da organização entre consumidores não excluídos
description	até 1000 caracteres
status	ACTIVE ou SUSPENDED (o valor REVOKED existe no modelo, para o registro histórico)
active_credentials	quantas chaves ativas o consumidor tem (derivado)

Autorização é por API

O consumidor não tem acesso global: cada API tem sua própria lista de consumidores autorizados. Autorizar e retirar autorização são operações idempotentes.

Operação	Resultado
PUT /v1/apis/{apiId}/consumers/{consumerId}	201 quando a autorização nasce, 200 quando já existia
DELETE /v1/apis/{apiId}/consumers/{consumerId}	204

Sem autorização, a chave do consumidor naquela API responde 403 — não 401. A chave é válida; o acesso é que não foi concedido. É a diferença que mais confunde no começo.

Um consumidor autorizado em pedidos não acessa faturamento, ainda que seja da mesma organização.

Suspender e excluir

PATCH com {"status":"SUSPENDED"} tira o consumidor do runtime: as chaves dele passam a receber 401. É o jeito correto de "desligar um integrador" sem apagar histórico — e é reversível.

Excluir (DELETE) é lógico: revoga todas as chaves, remove as autorizações e libera o nome para reuso. A auditoria guarda o histórico.

Mudanças aqui não passam por publicação

Consumidores, chaves e autorizações são estado de runtime, não parte da revisão da API. Criar um consumidor ou autorizar uma API aplica direto, sem publicar de novo. Isso é intencional: você não quer "republicar a API" só para dar acesso a um novo parceiro.

Chaves do consumidor

Cada consumidor pode ter até 5 chaves ativas ao mesmo tempo. Todas valem enquanto estiverem ativas — é assim que se faz rotação sem queda. Acima do limite: 409 credential_limit_reached.

A chave é mostrada uma única vez, no momento da emissão. O detalhe de emissão, rotação, revogação e expiração está em Chaves de API.

Sequência típica

# 1. cria o consumidor
curl -sS -X POST "$BASE/v1/consumers" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: consumidor-portal-01' \
  -d '{"name":"portal-web","description":"Portal do cliente"}'

# 2. emite a chave (o valor aparece UMA vez)
curl -sS -X POST "$BASE/v1/consumers/$CONSUMER_ID/credentials" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: chave-portal-web-01' \
  -d '{"name":"producao","expires_at":"2027-10-22T00:00:00Z"}'

# 3. autoriza na API
curl -sS -X PUT "$BASE/v1/apis/$API_ID/consumers/$CONSUMER_ID" \
  -H "Authorization: Bearer $TOKEN"

Limites e regras

Item	Valor
Chaves ativas por consumidor	5 (acima: 409 credential_limit_reached)
Validade máxima de uma chave	2 anos
Chave de consumidor suspenso	401
Consumidor de outra organização	404
Nome repetido na organização	409 consumer_name_taken

Perguntas frequentes

Um consumidor pode ter mais de uma chave? Sim, até o limite, e todas valem ao mesmo tempo.

Excluir e recriar com o mesmo nome mantém o acesso? Não. O consumidor novo é outro objeto, sem chaves e sem autorizações.

Consumidor é por API ou global? O objeto é da organização; a autorização é por API.

Posso dar acesso a uma API inteira sem consumidor? Só no modo PUBLIC, e aí não há consumidor nem controle por aplicação.

Próximos passos

• Chaves de API: o segredo que o consumidor apresenta.
• Segurança e autenticação: o que o gateway valida em cada modo.
• Logs de acesso: como identificar o consumidor em uma requisição.