API AuthGuard para integradores: visão geral e convenções

A API AuthGuard serve o endereço de cada organização (por exemplo, https://<slug>.authguard.pt). Os integradores usam quatro superfícies: pedidos de aprovação (intents), webhooks, OpenID Connect/SAML e SCIM. A administração da organização não é uma API de integração: exige uma sessão humana com passkey recente.

Que superfícies existem?

Convenções

• JSON em UTF-8; corpos até ao limite de cada rota.
• Erros num envelope único: {"error":{"code":"…","message":"…","field":"…"}}. Use sempre o code, nunca o texto. Ver Erros e limites.
• Idempotência: as criações aceitam Idempotency-Key; repetir com a mesma chave e o mesmo corpo devolve o resultado original (Idempotent-Replayed: true); a mesma chave com outro corpo é 409.
• Paginação por cursor: listas devolvem um cursor opaco; um cursor antigo dá invalid_cursor e a leitura recomeça.
• Limites: 429 rate_limited e 503 service_busy trazem Retry-After; espere esse tempo.
• Versões de recurso: escritas administrativas usam expectedRevision; uma revisão antiga dá 409.

O contrato

O contrato completo é o documento OpenAPI 3.1 docs/openapi/authguard-v1.yaml. Ver OpenAPI.

SDKs

Há SDKs para TypeScript, Python, Java, .NET e Go. Ver SDKs.