A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Auth0 API is how an app or AI agent administers an Auth0 tenant: listing and creating users, assigning roles, registering applications and connections, and searching tenant logs. Access is granted through a machine-to-machine access token whose scopes decide which operations are allowed, and an agent is limited to the tenant and the scopes that token carries. Auth0 can also stream tenant events, like a failed login or a user change, to a chosen destination as they happen.
How an app or AI agent connects to Auth0 determines what it can reach. The main route is a machine-to-machine token whose scopes decide which operations are allowed, and Auth0 publishes an official MCP server on top of the same API.
The Management API answers at the tenant's own domain under the /api/v2/ base path, such as https://acme-tenant.us.auth0.com/api/v2/. Every call sends a machine-to-machine access token as a bearer token, and the token's scopes decide which methods are allowed.
Auth0 publishes a first-party MCP server at github.com/auth0/auth0-mcp-server, announced on 2 September 2025. It lets an agent work with applications, APIs, Actions, logs, and Forms through the Management API. It authenticates with the OAuth 2.0 device authorization flow and stores tokens in the operating system keychain, and connects to clients such as Claude Desktop, Cursor, and Windsurf.
Log streams deliver each tenant log event to a chosen destination as it happens, including a custom HTTP webhook, Amazon EventBridge, Azure Event Grid, Datadog, Splunk, and Sumo Logic. Auth0 retries delivery up to three times and recommends log streams for monitoring rather than for a real-time decision in the application's critical path.
A machine-to-machine application authorized for the Management API uses the OAuth 2.0 client-credentials grant: it posts its client id and secret to the tenant's token endpoint with the audience set to the tenant's /api/v2/ path, and receives a signed JWT access token that lasts 24 hours by default. The token's scopes decide which methods are allowed.
The Auth0 MCP server authenticates a developer through the OAuth 2.0 device authorization flow and stores the resulting token in the operating system keychain. The token then carries the Management API scopes the agent is allowed to use.
The Management API is split into areas an agent can act on, such as users, roles, applications, connections, and logs. Each area has its own methods and its own scopes, and some reach far more than others, like resetting a password or deleting a user.
List and search users, read a single user, and create, update, and delete users in the tenant.
List and read roles, create a role, and assign roles to a user for role-based access control.
List and read clients (applications), and create, update, and delete them.
List and read connections to identity providers, and create a connection.
List and read organizations, create an organization, and add members to one.
Search tenant log events and read a single log event by id.
List the authorization grants on the tenant and delete a grant.
List and read the tenant's registered APIs, and create a new one.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
UsersList and search users, read a single user, and create, update, and delete users in the tenant.5 | ||||||
| GET | /api/v2/users | List or search users, with filtering, sorting, and pagination. | read | read:users | Current | |
Searching by a Lucene query uses the q parameter. read:user_idp_tokens is also accepted, but unlocks identity-provider tokens rather than replacing read:users. Acts onuser Permission (capability) read:usersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/users/{id} | Retrieve a single user's details by id. | read | read:users | Current | |
read:user_idp_tokens additionally returns the user's identity-provider tokens. Acts onuser Permission (capability) read:usersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/users | Create a user for a database or passwordless connection. | write | create:users | Current | |
The user is created in a named connection, such as a database connection. Acts onuser Permission (capability) create:usersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v2/users/{id} | Update a user's attributes, such as email, password, profile, or metadata. | write | update:users | Current | |
Changing the app_metadata field additionally needs update:users_app_metadata. Acts onuser Permission (capability) update:usersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/users/{id} | Permanently delete a user by id. | write | delete:users | Current | |
Deletion is permanent and removes the account from the tenant. Acts onuser Permission (capability) delete:usersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
RolesList and read roles, create a role, and assign roles to a user for role-based access control.4 | ||||||
| GET | /api/v2/roles | List the roles defined in the tenant. | read | read:roles | Current | |
Roles drive role-based access control for users. Acts onrole Permission (capability) read:rolesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/roles/{id} | Retrieve a specific role by id. | read | read:roles | Current | |
Returns the role's name, description, and id. Acts onrole Permission (capability) read:rolesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/roles | Create a role for role-based access control. | write | create:roles | Current | |
Permissions are added to the role in a separate call. Acts onrole Permission (capability) create:rolesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/users/{id}/roles | Assign one or more existing roles to a user. | write | update:users | Current | |
This method needs two scopes together: update:users and create:role_members. Acts onrole Permission (capability) update:usersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ApplicationsList and read clients (applications), and create, update, and delete them.5 | ||||||
| GET | /api/v2/clients | List clients, which are applications and SSO integrations. | read | read:clients | Current | |
read:client_keys and read:client_credentials unlock credential fields rather than replacing read:clients. Acts onclient Permission (capability) read:clientsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/clients/{id} | Retrieve a client (application) by id. | read | read:clients | Current | |
Credential fields need read:client_keys or read:client_credentials in addition. Acts onclient Permission (capability) read:clientsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/clients | Create a new application or SSO integration. | write | create:clients | Current | |
Returns the new client's id and, for confidential apps, a client secret. Acts onclient Permission (capability) create:clientsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /api/v2/clients/{id} | Update a client's settings. | write | update:clients | Current | |
Changing the client secret or signing key additionally needs update:client_keys. Acts onclient Permission (capability) update:clientsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/clients/{id} | Delete a client and its related configuration. | write | delete:clients | Current | |
Deletion removes the application and breaks any integration using it. Acts onclient Permission (capability) delete:clientsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ConnectionsList and read connections to identity providers, and create a connection.3 | ||||||
| GET | /api/v2/connections | List connections, optionally filtered by strategy. | read | read:connections | Current | |
A connection links the tenant to an identity provider, such as a database or a social login. Acts onconnection Permission (capability) read:connectionsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/connections/{id} | Retrieve a connection's details and identity-provider configuration. | read | read:connections | Current | |
Returns the strategy and the provider-specific options for the connection. Acts onconnection Permission (capability) read:connectionsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/connections | Create a new connection to an identity provider. | write | create:connections | Current | |
The strategy field sets the kind of provider the connection uses. Acts onconnection Permission (capability) create:connectionsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OrganizationsList and read organizations, create an organization, and add members to one.4 | ||||||
| GET | /api/v2/organizations | List all organizations in the tenant. | read | read:organizations | Current | |
read:organizations_summary returns a lighter summary view of each organization. Acts onorganization Permission (capability) read:organizationsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/organizations/{id} | Retrieve a single organization by id. | read | read:organizations | Current | |
read:organizations_summary returns a lighter summary view. Acts onorganization Permission (capability) read:organizationsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/organizations | Create a new organization. | write | create:organizations | Current | |
An organization groups members and the connections enabled for them. Acts onorganization Permission (capability) create:organizationsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/organizations/{id}/members | Add existing users as members of an organization. | write | create:organization_members | Current | |
Members are referenced by user id and must already exist in the tenant. Acts onorganization Permission (capability) create:organization_membersVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
LogsSearch tenant log events and read a single log event by id.2 | ||||||
| GET | /api/v2/logs | Search and retrieve tenant log events matching the given criteria. | read | read:logs | Current | |
read:logs_users additionally returns log detail tied to specific users. Large result sets are best read with checkpoint pagination. Acts onlog event Permission (capability) read:logsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/logs/{id} | Retrieve an individual log event by id. | read | read:logs | Current | |
read:logs_users additionally returns user-linked detail. Acts onlog event Permission (capability) read:logsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
GrantsList the authorization grants on the tenant and delete a grant.2 | ||||||
| GET | /api/v2/grants | List the authorization grants on the account. | read | read:grants | Current | |
A grant records the access a user gave to an application. Acts ongrant Permission (capability) read:grantsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /api/v2/grants/{id} | Delete a grant by id. | write | delete:grants | Current | |
Deleting a grant revokes the application's access for that user. Acts ongrant Permission (capability) delete:grantsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
APIs (resource servers)List and read the tenant's registered APIs, and create a new one.3 | ||||||
| GET | /api/v2/resource-servers | List all APIs (resource servers) in the tenant. | read | read:resource_servers | Current | |
A resource server is an API that tokens can be issued for. Acts onresource server Permission (capability) read:resource_serversVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/v2/resource-servers/{id} | Retrieve an API's details by id. | read | read:resource_servers | Current | |
Returns the API's identifier, scopes, and token settings. Acts onresource server Permission (capability) read:resource_serversVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/v2/resource-servers | Register a new API (resource server). | write | create:resource_servers | Current | |
The identifier field, usually a URL, names the API that tokens are issued for. Acts onresource server Permission (capability) create:resource_serversVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Auth0 can stream tenant events to an app or AI agent instead of the app repeatedly asking. Log streams deliver each log event, such as a successful or failed login, a signup, or a Management API change, to an HTTP endpoint or a partner destination as it happens.
| Event | What it signals | Triggered by |
|---|---|---|
Authentication events | Fires on sign-in activity, such as a successful login, a failed login, a logout, a signup, a silent authentication, or a token exchange. | In-app only |
Management API events | Fires when a Management API operation succeeds or fails, such as a user, role, or application change. | In-app only |
User and behavioral events | Fires on account-level activity, such as a user account change, device authorization, or single sign-on. | In-app only |
Actions events | Fires for events raised by Auth0 Actions, the custom code run at points in a flow. | In-app only |
System events | Fires for tenant-level system activity that is not tied to a single user sign-in. | In-app only |
Auth0 limits how fast an app or AI agent can call the Management API through a token-bucket model that varies by tenant type and subscription level, returning a 429 when a bucket is empty.
Auth0 limits the Management API with a token-bucket model: each bucket has a maximum size, which sets how large a burst is allowed, and a refill rate, which sets the steady pace of requests. The applicable limits vary by API, by tenant type (production versus development or staging), and by subscription level (Free, Essential, Professional, Enterprise, and the private-cloud tiers). Every response carries three headers that report the current state: x-ratelimit-limit (the maximum requests available), x-ratelimit-remaining (how many remain before the bucket refills), and x-ratelimit-reset (a UNIX timestamp for when requests are added back). Exceeding a bucket returns HTTP 429 Too Many Requests, at which point a client should back off until the reset time.
List endpoints use offset pagination through the page parameter, which is zero-based, and the per_page parameter, which tops out at 100. Adding include_totals=true wraps the results in an object with start, limit, length, and total counts instead of returning a bare array. Large datasets, such as users and logs, can use checkpoint pagination instead, a forward-only cursor through the from and take parameters that avoids the deep-paging limits of offset paging. The user-search endpoint never returns more than 1,000 users for the same query, even across pages.
Requests and responses are JSON and must be sent with a Content-Type of application/json. There is no single documented payload size limit across the whole API. The main bound on response size is the per_page cap of 100 results and the 1,000-result ceiling on user search.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request is malformed or a parameter is missing or invalid. | Correct the request body or parameters and resend. |
| 401 | Unauthorized | The Management API access token is missing, invalid, or expired. | Mint a fresh token through the client-credentials grant and send it in the Authorization header. |
| 403 | Forbidden | The token is valid but its scopes do not allow the requested operation. | Authorize the machine-to-machine application for the missing scope, then mint a new token. |
| 404 | Not Found | The resource does not exist, or the token cannot see it. | Confirm the id and that the token has access to the resource. |
| 429 | Too Many Requests | A rate-limit bucket was exhausted. The x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset headers report the current state. | Read x-ratelimit-reset and back off until requests are added back to the bucket. |
Auth0 versions the Management API by major number. The current version is v2, and the older v1 reached end of life in 2020. New endpoints and changes ship continuously through dated release notes rather than a new version string.
v2 is the current Management API, called from the tenant's /api/v2/ base path. It replaced v1, which reached end of life on the public cloud on 13 July 2020 and was removed from the private cloud in the November 2020 release. Additive changes ship continuously through Auth0's dated release notes rather than a new version string.
Refresh token metadata reached general availability, adding endpoints to read, update, and delete a single refresh token by id. It was published on Monday 22 June 2026.
An early-access release added bulk refresh-token management, including listing refresh tokens and revoking up to 100 by id in one call. It was published on Thursday 11 June 2026.
Session metadata reached general availability, adding endpoints to read and update a single session by id. It was published on Tuesday 10 February 2026.
Management API v1 reached end of life on the public cloud on 13 July 2020 and was removed from the private cloud in the November 2020 release, leaving v2 as the only supported version.
An integration calls the v2 base path and picks up additive changes through the changelog.
Auth0 changelog ↗Bollard AI sits between a team's AI agents and Auth0. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.