The AuthGuard API for integrators: overview and conventions

The AuthGuard API serves each organization's address (for example https://<slug>.authguard.pt). Integrators use four surfaces: approval requests (intents), webhooks, OpenID Connect/SAML and SCIM. Organization administration is not an integration API: it requires a human session with a recent passkey.

Which surfaces are there?

Conventions

• JSON in UTF-8; bodies up to each route's limit.
• Errors in one envelope: {"error":{"code":"…","message":"…","field":"…"}}. Always use the code, never the text. See Errors and limits.
• Idempotency: creations take Idempotency-Key; repeating with the same key and body returns the original result (Idempotent-Replayed: true); the same key with another body is 409.
• Cursor pagination: lists return an opaque cursor; a stale cursor gives invalid_cursor and the read restarts.
• Limits: 429 rate_limited and 503 service_busy carry Retry-After; wait that long.
• Resource versions: administrative writes use expectedRevision; a stale revision gives 409.

The contract

The full contract is the OpenAPI 3.1 document docs/openapi/authguard-v1.yaml. See OpenAPI.

SDKs

There are SDKs for TypeScript, Python, Java, .NET and Go. See SDKs.