API overview

uia-auth-management-api sits between internal callers and the Auth0 Management API. Callers authenticate to it with a CSI-issued access token, and it holds the Auth0 machine-to-machine credentials itself. No app receives Management API credentials directly.

Why a proxy

• Auth0 tenant credentials stay in one service instead of in every consumer
• Authorization is scoped per endpoint rather than per tenant
• Rate limiting and token caching are handled once
• The surface exposed to product teams stays narrow and stable

Base URLs

Each environment points at its own Auth0 tenant. See Tenants and environments.

Authentication

Every request carries a bearer token. The API validates the signature, issuer, audience, and expiry, then checks that the token holds the scopes the endpoint requires. See M2M requirements and best practices.

Resources

Conventions

Pagination

List endpoints take page and per_page. Pass include_totals=true for an envelope with a total count instead of a bare array. Offset pagination is capped, so filter rather than paging deeply.

Path identifiers

Identifiers are opaque and can contain characters that need URL encoding, particularly user ids.

Partial updates

Updates are PATCH and only the fields you send are changed. Array fields are replaced rather than merged.

Consistency

Writes are immediately visible when reading by id. Search is eventually consistent, so a record created a moment ago may not appear in query results yet.

Errors

Every failure returns the same envelope, including a requestId that matches the x-request-id response header. See Error codes.

Specification

The OpenAPI 3.1 document is generated from the service’s own validation schemas and served at /openapi.json, with a browsable reference at /docs.

Health

GET /health is unauthenticated and is used by the load balancer. It reports process liveness, not Auth0 availability.