O contrato OpenAPI

O contrato público da API é um documento OpenAPI 3.1 mantido junto ao código: docs/openapi/authguard-v1.yaml, com o anexo docs/openapi/authguard-oauth-token.json para o endpoint de token.

O que contém?

• Todas as rotas públicas, agrupadas por etiquetas (por exemplo Intents, Meta, SCIM, OIDC).
• Os esquemas de pedido e de resposta, com additionalProperties: false: campos desconhecidos são recusados.
• As respostas de erro partilhadas, com o envelope {"error":{"code","message","field"}}.
• Os cabeçalhos relevantes: Idempotency-Key, Idempotent-Replayed, Retry-After, Cache-Control: no-store.

Como é mantido?

O documento é validado em cada alteração com o Redocly (regras recommended-strict) e por verificações do próprio projeto que comparam o contrato com as rotas do servidor. Uma rota nova sem contrato não passa a integração contínua.

Posso gerar um cliente?

Pode, com qualquer gerador OpenAPI 3.1. Para pedidos de aprovação, webhooks, recibos e OIDC, prefira os SDKs: tratam da idempotência, das repetições e das verificações criptográficas. Ver SDKs.

Onde obtenho o documento?

Peça-o ao seu fornecedor ou ao parceiro, junto com a versão do serviço que usa. O documento descreve também rotas de administração, que exigem uma sessão humana com passkey e não servem para integrações.

Compatibilidade

Respostas existentes não mudam de forma sem aviso; campos novos opcionais podem surgir. Construa os seus clientes para ignorar campos que não conhecem nas respostas, mas não envie campos que o contrato não define.