API Reference - Authaz - Docs
Authaz Docs Reference API Reference ·
The Authaz Management API is the same surface the dashboard uses. Every endpoint is documented in the interactive reference (rendered from our OpenAPI spec). This page covers how to authenticate and what's where.
Your first call#
curl https://your-app.authaz.io/api/v1/users \ -H "X-API-Key: $AUTHAZ_API_KEY " A 200 returns the first page of users — a data array plus a next cursor (see Pagination below). A 401 means the key is wrong. A 403 means it's valid but lacks the required permission. The interactive reference has the exact response schema for every endpoint.
Authentication#
Two methods work on every endpoint. Pick whichever fits the caller.
X-API-Key (Management API key)# Long-lived keys generated in the dashboard. The default for backend services and CI:
curl https://your-app.authaz.io/api/v1/users \ -H "X-API-Key: mgmt_01h..." API keys are scoped to one application and (optionally) one tenant. They can also be restricted by permission — give your CI a key that can only users:read, not users:delete.
Authorization: Bearer (JWT)# Use a user's access token to act as that user :
curl https://your-app.authaz.io/api/v1/users \ -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." Every endpoint enforces both API-key permissions and the user's permissions. This is what powers customer-facing dashboards: a single Management API key, plus a per-user Bearer token, gives the user exactly their own slice.
You can send both headers at once. The API key is the authentication; the Bearer adds tenant scoping and per-user permission narrowing on top.
Tenant scope comes from one of three places, in order of precedence:
The path. /applications/{appId}/tenants/{tenantId}/... always scopes to that tenant.The Bearer token. A user JWT with a tenant_id claim auto-scopes the call.The API key. Tenant-scoped API keys carry their tenant in their stored metadata. You'll never see a ?tenantId= query parameter. If a path doesn't include /tenants/{tenantId}/, scope comes from the credentials.
The OpenAPI spec groups endpoints into the categories below. Click through to the interactive browser to see every method, schema, and example response.
Section What's inside Organizations Read your organization, manage billing settings, deactivate. Applications CRUD applications, stats, custom domains, branding. Tenants CRUD tenants and per-tenant configuration. Users List, get, suspend, activate, unlock, delete, MFA reset, session listing.
Authentication & authorization# Section What's inside Auth Providers Per-application config for password, OAuth, magic link, M2M, API keys, passkey. Roles Define roles and their permissions, per application or per tenant. Permissions Authorization checks: check, bulk-check, role checks, listings. Role Assignments Assign and revoke roles for users (and credentials, and API keys). Policies Password policy, MFA policy, session policy, account-lockout policy.
Section What's inside Credentials (M2M) Create, rotate, revoke OAuth client-credential pairs and JWKS uploads. API Keys User-bound keys, standalone keys, introspection, rotation, revocation.
Section What's inside Invitations Send, list, resend, revoke invitations. Branding Logo, colors, copy overrides for Authaz Sign-In. Email Email-provider config (Resend / SES) and per-flow templates. Sessions Validate, list, revoke active user sessions. Trail Logs (Audit) Search and stream audit events. Analytics Active user counts, sign-in stats, MFA adoption.
Endpoint What it does GET /.well-known/openid-configurationDiscovery metadata. GET /.well-known/jwks.jsonPublic keys for token verification. GET /oauth2/authorizeStart the auth code flow. POST /oauth2/tokenExchange code, refresh, or run client credentials. POST /oauth2/revokeRevoke a refresh token. GET /oauth2/userinfoOIDC userinfo claims. POST /oauth2/device_authorizationDevice-code flow for CLIs and TVs.
IDs — all resource IDs are UUIDv7 strings. They sort lexically by creation time.Idempotency — destructive operations (delete, revoke) accept an Idempotency-Key header. Pair with a UUID for safe retries.Rate limits — every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. 429s come with Retry-After (in seconds).
List endpoints use pageSize (default 20, max 100) and a cursor from the previous response's next field.
# First page curl "https://your-app.authaz.io/api/v1/users?pageSize=50" \ -H "X-API-Key: mgmt_01h..." { "data" : [ /* up to 50 records */ ], "next" : "eyJjcmVhdGVkQXQiOiIyMDI1LTA0LTAxVDE1OjMyOjAwWiJ9" } # Next page — pass the cursor verbatim curl "https://your-app.authaz.io/api/v1/users?cursor=eyJjcmVhdGVkQXQiOiIyMDI1LTA0LTAxVDE1OjMyOjAwWiJ9" \ -H "X-API-Key: mgmt_01h..." When next is null or absent, you've reached the end. Cursors are opaque — don't decode or construct them yourself; treat them as string.
Every error response has the same shape:
{ "code" : "validation_error" , "message" : "email is required" , "field" : "email" } field is set on validation errors and points to the offending input. The HTTP status reflects the class:
Status Class Typical cause 401Unauthenticated Missing or invalid credentials 403Forbidden Credentials valid; lack the required permission or wrong tenant 404Not found Resource doesn't exist or is scoped to another tenant 409Conflict Duplicate resource (e.g. user with that email already exists) 422Validation field names the offending input429Rate-limited Retry after the seconds in Retry-After 5xxServer Safe to retry idempotent calls with backoff
The API is versioned in the URL: /api/v1/.... Breaking changes ship in a new version (/api/v2/...); the old version stays alive for at least 12 months. Non-breaking changes (new fields, new endpoints, new optional parameters) ship continuously and don't bump the version.
