Ir para o conteúdo

Autenticação e escopos

Todo endpoint protegido do contrato de leitura do IRIS é controlado por uma chave de API. Este guia cobre como apresentar a chave, os dois escopos, o ciclo de vida da chave e a semântica exata de 401 / 403 / 429 — tudo alinhado com os handlers ao vivo.

O header X-API-Key

Envie sua chave no header de requisição X-API-Key em toda chamada a uma rota protegida:

curl -sS "$IRIS_BASE_URL/v1/brands?limit=1" -H "X-API-Key: $IRIS_API_KEY"

A chave é uma string opaca emitida pelo operador (placeholder iris_xxx nesta documentação). O servidor a verifica em toda requisição; a chave bruta nunca é registrada em log.

O servidor MCP usa o mesmo header X-API-Key, enviado por requisição sobre o transporte Streamable HTTP — veja o guia MCP. (Para o transporte stdio, a chave é lida da variável de ambiente IRIS_API_KEY.)

Rotas públicas que não precisam de chave

/health, /docs e /metrics são os únicos caminhos que funcionam sem chave. Tudo sob /v1 exige uma.

Escopos

Uma chave carrega um conjunto de escopos (scopes) que determinam quais partes do contrato ela pode ler:

Escopo Concede acesso a
brands:read O contrato de marcas: GET /v1/brands, GET /v1/brands/:nroSolicitud.
insights:read O contrato operacional: GET /v1/freshness, GET /v1/sync-runs.

Um array de escopos vazio é irrestrito — uma chave emitida sem escopos recebe todos os escopos de leitura. Uma chave com um array de escopos não vazio recebe somente os escopos listados; chamar uma rota cujo escopo exigido está ausente é rejeitado com 403 forbidden.

As ferramentas MCP seguem a mesma regra: tanto search_brands quanto get_brand_detail exigem brands:read (ou uma chave irrestrita, de escopo vazio).

Ciclo de vida da chave (gerenciado pelo operador)

As chaves são criadas, rotacionadas, revogadas e expiradas pelo operador via CLI de administração. Como integrador, você não gerencia chaves por conta própria; você solicita mudanças ao seu operador.

  • Rotacionar — o operador lhe emite uma nova chave e desativa a antiga. Troque o valor de X-API-Key que seu cliente envia; nenhuma mudança de código além do segredo.
  • Revogar — uma chave revogada para de funcionar imediatamente: as chamadas seguintes retornam 401 unauthorized, exatamente como para uma chave desconhecida.
  • Expiração — uma chave pode carregar uma data de expiração. Após passar da expiração, ela é tratada como inválida e retorna 401 unauthorized. Peça ao seu operador para reemitir antes da expiração para evitar indisponibilidade.

Cada chave também pertence a um consumer e carrega uma cota mensal (veja abaixo).

Semântica de status

Estes são os resultados exatos que as camadas de autenticação e cota produzem:

401 unauthorized

Retornado quando a chave está ausente, malformada, desconhecida ou revogada/expirada.

{ "error": { "code": "unauthorized", "message": "Missing or invalid API key", "requestId": "..." } }

403 forbidden

Retornado quando a chave é válida e ativa, mas não tem o escopo que a rota exige. A mensagem nomeia o escopo faltante:

{ "error": { "code": "forbidden", "message": "API key lacks required scope: insights:read", "requestId": "..." } }

429 quota_exceeded

Retornado quando a cota mensal da chave está esgotada. Carrega um header Retry-After com os segundos até a janela de cota reiniciar:

HTTP/1.1 429 Too Many Requests
Retry-After: 1209600

{ "error": { "code": "quota_exceeded", "message": "Monthly quota exceeded", "requestId": "..." } }

Um limite separado de rajada de curto prazo (padrão 100 requisições/minuto por chave) também retorna 429. Tanto o limite de rajada quanto a cota mensal se aplicam de forma idêntica em REST e no MCP, já que ambos os transportes se autenticam contra as mesmas chaves e compartilham o mesmo contador de cota.

O envelope de erro uniforme { error: { code, message, requestId } } está descrito no guia de primeiros passos. Use requestId (também ecoado no header de resposta x-request-id) ao relatar um problema ao seu operador.

Veja também

  • Primeiros passos — URL base, primeira chamada, paginação, envelope de erro.
  • Conecte seu agente de IA (MCP) — mesma chave, mesmos escopos, via MCP.
  • A referência OpenAPI ao vivo em /docs — segurança e schema por endpoint.