---
title: API Reference
project: Authaz
updated: 2026-05-07T23:22:24.439Z
---


# 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

```bash
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](#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:

```bash
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*:

```bash
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 scoping

Tenant scope comes from one of three places, in order of precedence:

1. **The path.** `/applications/{appId}/tenants/{tenantId}/...` always scopes to that tenant.
2. **The Bearer token.** A user JWT with a `tenant_id` claim auto-scopes the call.
3. **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.

## Sections

The OpenAPI spec groups endpoints into the categories below. Click through to the interactive browser to see every method, schema, and example response.

### Identity

| 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. |

### Access credentials

| 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. |

### Operations

| 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. |

### OAuth 2.0 / OIDC

| Endpoint | What it does |
|----------|-------------|
| `GET /.well-known/openid-configuration` | Discovery metadata. |
| `GET /.well-known/jwks.json` | Public keys for token verification. |
| `GET /oauth2/authorize` | Start the auth code flow. |
| `POST /oauth2/token` | Exchange code, refresh, or run client credentials. |
| `POST /oauth2/revoke` | Revoke a refresh token. |
| `GET /oauth2/userinfo` | OIDC userinfo claims. |
| `POST /oauth2/device_authorization` | Device-code flow for CLIs and TVs. |

## Conventions

- **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).

### Pagination

List endpoints use `pageSize` (default 20, max 100) and a `cursor` from the previous response's `next` field.

```bash
# First page
curl "https://your-app.authaz.io/api/v1/users?pageSize=50" \
  -H "X-API-Key: mgmt_01h..."
```

```json
{
  "data": [ /* up to 50 records */ ],
  "next": "eyJjcmVhdGVkQXQiOiIyMDI1LTA0LTAxVDE1OjMyOjAwWiJ9"
}
```

```bash
# 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`.

### Errors

Every error response has the same shape:

```json
{
  "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 |
|---|---|---|
| `401` | Unauthenticated | Missing or invalid credentials |
| `403` | Forbidden | Credentials valid; lack the required permission or wrong tenant |
| `404` | Not found | Resource doesn't exist or is scoped to another tenant |
| `409` | Conflict | Duplicate resource (e.g. user with that email already exists) |
| `422` | Validation | `field` names the offending input |
| `429` | Rate-limited | Retry after the seconds in `Retry-After` |
| `5xx` | Server | Safe to retry idempotent calls with backoff |

## Versioning

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.

## Next steps

- [Quickstart — cURL](../quickstart/curl.md) — try the OAuth flow against the API.
- [Quickstart — .NET](../quickstart/dotnet.md) — typed client for the Management API.
- [Multi-tenancy](../multi-tenancy.md) — tenant-scoped variants of the endpoints above.