A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Clerk API is how an app or AI agent manages an application's accounts from a server: listing and creating users, banning or deleting one, building organizations and their memberships, and revoking live sessions. Access is granted through a single secret key tied to one instance, and that key is instance-level with no per-endpoint scopes, so it reaches every user, organization, and session in the instance. Clerk dates each API version and a request pins one explicitly, and a state change can be pushed to a webhook so an integration learns about activity without polling.
How an app or AI agent connects to Clerk determines what it can reach. There is the Backend API for managing users and organizations from a server, a webhook stream for receiving account events, and an official server that exposes Clerk's docs to coding agents, and each is governed by the key or secret behind it.
The Backend API takes JSON request bodies, returns JSON, and pages through lists with limit and offset query parameters, at https://api.clerk.com/v1. Every request authenticates with the instance secret key (sk_test_... or sk_live_...) as a Bearer token. The key is instance-wide: it can call every endpoint, so there are no per-endpoint scopes to narrow it.
Clerk delivers events through Svix, POSTing a signed JSON payload to a registered HTTPS endpoint when something changes, like user.created or organization.updated. The receiver verifies the Svix signature headers (svix-id, svix-timestamp, svix-signature) against the endpoint's signing secret to confirm the message came from Clerk. Svix retries failed deliveries on a schedule.
Clerk publishes an official remote Model Context Protocol server at https://mcp.clerk.com/mcp that gives AI coding assistants up-to-date Clerk SDK snippets and implementation guidance. It is a documentation and code-pattern server, not a tool layer over the Backend API, so it does not read or change live users, organizations, or sessions. Launched in public beta in January 2026.
A secret key authenticates every Backend API call, sent as a Bearer token. It is instance-level: a single key can call every endpoint and reach every user, organization, and session in the instance, with no granular per-endpoint scopes. Each key belongs to one instance, either development (sk_test_...) or production (sk_live_...), and must never appear in client code. A leaked key reaches everything, so rotate it if exposed.
The Clerk Backend API is split into areas an agent can act on, like users, organizations and their memberships, sessions, and invitations. Each area has its own methods, and a write here can ban a person, delete an account, or revoke a live session.
Methods for listing, reading, creating, updating, and removing user accounts.
Methods for working with organizations: the tenant or team objects users belong to.
Methods for adding, listing, changing, and removing who belongs to an organization.
Methods for inviting people to sign up to the application by email.
Methods for inviting people into a specific organization.
Methods for listing, reading, revoking, and verifying authenticated sessions.
Methods for controlling who can sign up or sign in, by email address or phone number.
Methods for minting one-time tokens that sign a user in or impersonate one.
Methods for reading and editing the email and SMS messages Clerk sends.
Methods for managing the JWT templates that shape session tokens for other services.
Methods for listing, reading, and verifying client objects, a device's view of sessions.
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 | |
|---|---|---|---|---|---|---|
UsersMethods for listing, reading, creating, updating, and removing user accounts.8 | ||||||
| GET | /users | List all users in the instance, filtered and ordered by query parameters. | read | — | Current | |
Read-only. The secret key grants instance-wide access; Clerk has no per-endpoint scopes. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /users/{user_id} | Retrieve a single user by ID. | read | — | Current | |
Read-only. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /users | Create a new user with the given details. | write | — | Current | |
A core write that provisions a real account; fires user.created. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook event user.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /users/{user_id} | Update an existing user's attributes. | write | — | Current | |
As of 2026-05-12, metadata fields moved to the dedicated metadata endpoint; fires user.updated. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook event user.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /users/{user_id} | Permanently delete a user. | write | — | Current | |
Irreversible; removes the account and fires user.deleted. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook event user.deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /users/{user_id}/ban | Ban a user, marking them banned and signing out their sessions. | write | — | Current | |
Blocks the user from signing in until unbanned. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook event user.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /users/{user_id}/lock | Lock a user, temporarily preventing sign-in. | write | — | Current | |
A lock can be lifted with the unlock method. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook event user.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /users/{user_id}/metadata | Merge and update a user's public, private, and unsafe metadata. | write | — | Current | |
Limited to 10 requests per 10 seconds per user. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook event user.updatedRate limit10 requests / 10s per user SourceOfficial documentation ↗ | ||||||
OrganizationsMethods for working with organizations: the tenant or team objects users belong to.5 | ||||||
| GET | /organizations | List all organizations in the instance. | read | — | Current | |
Read-only. Acts onorganization Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /organizations/{organization_id} | Retrieve an organization by ID or slug. | read | — | Current | |
Read-only. Acts onorganization Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /organizations | Create a new organization. | write | — | Current | |
Fires organization.created and an organizationMembership.created for the creator. Acts onorganization Permission (capability)None required VersionAvailable since the API’s base version Webhook event organization.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /organizations/{organization_id} | Update an organization's attributes. | write | — | Current | |
As of 2026-05-12, metadata fields moved to the metadata endpoint; fires organization.updated. Acts onorganization Permission (capability)None required VersionAvailable since the API’s base version Webhook event organization.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /organizations/{organization_id} | Permanently delete an organization. | write | — | Current | |
Irreversible; removes the organization and its memberships, and fires organization.deleted. Acts onorganization Permission (capability)None required VersionAvailable since the API’s base version Webhook event organization.deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Organization MembershipsMethods for adding, listing, changing, and removing who belongs to an organization.4 | ||||||
| POST | /organizations/{organization_id}/memberships | Add a user to an organization with a given role. | write | — | Current | |
Fires organizationMembership.created. Acts onorganization_membership Permission (capability)None required VersionAvailable since the API’s base version Webhook event organizationMembership.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /organizations/{organization_id}/memberships | List all members of an organization. | read | — | Current | |
Read-only. Acts onorganization_membership Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /organizations/{organization_id}/memberships/{user_id} | Change a member's role within an organization. | write | — | Current | |
Fires organizationMembership.updated. Acts onorganization_membership Permission (capability)None required VersionAvailable since the API’s base version Webhook event organizationMembership.updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /organizations/{organization_id}/memberships/{user_id} | Remove a member from an organization. | write | — | Current | |
Fires organizationMembership.deleted. Acts onorganization_membership Permission (capability)None required VersionAvailable since the API’s base version Webhook event organizationMembership.deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
InvitationsMethods for inviting people to sign up to the application by email.3 | ||||||
| POST | /invitations | Create an invitation for a given email address to join the application. | write | — | Current | |
Sends an email. Limited to 100 invitations per hour. Acts oninvitation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limit100 / hour SourceOfficial documentation ↗ | ||||||
| GET | /invitations | List all invitations and their status. | read | — | Current | |
Read-only. Acts oninvitation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /invitations/{invitation_id}/revoke | Revoke a pending invitation so it can no longer be used. | write | — | Current | |
Only works on pending invitations. Acts oninvitation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Organization InvitationsMethods for inviting people into a specific organization.1 | ||||||
| POST | /organizations/{organization_id}/invitations | Create and send an invitation into a specific organization. | write | — | Current | |
Sends an email. Limited to 250 per hour; fires organizationInvitation.created. Acts onorganization_invitation Permission (capability)None required VersionAvailable since the API’s base version Webhook event organizationInvitation.createdRate limit250 / hour SourceOfficial documentation ↗ | ||||||
SessionsMethods for listing, reading, revoking, and verifying authenticated sessions.4 | ||||||
| GET | /sessions | List sessions in the instance, filtered by user, client, or status. | read | — | Current | |
Read-only. Acts onsession Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /sessions/{session_id} | Retrieve a single session by ID. | read | — | Current | |
Read-only. Acts onsession Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /sessions/{session_id}/revoke | Revoke a session, ending it and signing the person out. | write | — | Current | |
Ends a live session and fires session.revoked. Acts onsession Permission (capability)None required VersionAvailable since the API’s base version Webhook event session.revokedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /sessions/{session_id}/tokens | Mint a short-lived session token for the given session. | write | — | Current | |
Returns a JWT that authenticates the session against other services. Acts onsession_token Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Allow-list / Block-listMethods for controlling who can sign up or sign in, by email address or phone number.2 | ||||||
| POST | /allowlist_identifiers | Add an email address or phone number to the allow-list. | write | — | Current | |
Controls who is permitted to sign up or sign in. Acts onallowlist_identifier Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /blocklist_identifiers | Add an email address or phone number to the block-list. | write | — | Current | |
Blocks the identifier from signing up or signing in. Acts onblocklist_identifier Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Sign-in & Actor TokensMethods for minting one-time tokens that sign a user in or impersonate one.2 | ||||||
| POST | /sign_in_tokens | Create a one-time sign-in token that signs a user in without a password. | write | — | Current | |
The token grants sign-in for the named user; treat it like a credential. Acts onsign_in_token Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /actor_tokens | Create an actor token so one user can sign in on behalf of another (impersonation). | write | — | Current | |
Enables impersonation; the actor signs in as the target user. Acts onactor_token Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Email & SMS TemplatesMethods for reading and editing the email and SMS messages Clerk sends.2 | ||||||
| GET | /templates/{template_type} | List all email or SMS templates of a given type. | read | — | Current | |
Read-only. template_type is email or sms. Acts ontemplate Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /templates/{template_type}/{slug} | Update the email or SMS template for a given type and slug. | write | — | Current | |
Changes the wording sent to every user for that message. Acts ontemplate Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
JWT TemplatesMethods for managing the JWT templates that shape session tokens for other services.2 | ||||||
| GET | /jwt_templates | List all JWT templates in the instance. | read | — | Current | |
Read-only. Acts onjwt_template Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /jwt_templates | Create a JWT template that shapes the claims in session tokens. | write | — | Current | |
Defines claims that downstream services read and trust. Acts onjwt_template Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ClientsMethods for listing, reading, and verifying client objects, a device's view of sessions.2 | ||||||
| GET | /clients | List all clients, each a device's view of its sessions and sign-in state. | read | — | Current | |
Read-only. Acts onclient Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /clients/verify | Verify a client token and return the client it belongs to. | read | — | Current | |
A verification check; reads state without changing it. Acts onclient Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Clerk can notify an app when something happens in an instance, like a user being created or an organization being updated. Delivery runs on Svix, which signs each message and retries failed deliveries, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
user.created | A new user account was created in the instance. | /users |
user.updated | A user's details changed, including a ban, lock, or metadata update. | /users/{user_id}/users/{user_id}/ban/users/{user_id}/lock/users/{user_id}/metadata |
user.deleted | A user account was permanently deleted. | /users/{user_id} |
organization.created | A new organization was created. | /organizations |
organization.updated | An organization's details changed. | /organizations/{organization_id} |
organization.deleted | An organization was deleted, along with its memberships. | /organizations/{organization_id} |
organizationMembership.created | A user was added as a member of an organization. | /organizations/{organization_id}/memberships/organizations |
organizationMembership.updated | A member's role within an organization changed. | /organizations/{organization_id}/memberships/{user_id} |
organizationMembership.deleted | A member was removed from an organization. | /organizations/{organization_id}/memberships/{user_id} |
organizationInvitation.created | An invitation into an organization was created and sent. | /organizations/{organization_id}/invitations |
session.revoked | A session was revoked, signing the person out of that session. | /sessions/{session_id}/revoke |
Clerk limits how fast an app can call the Backend API, counted against the secret key making the request, with tighter caps on a few endpoints that send email or write metadata.
Clerk meters Backend API requests against the secret key making the call, not by a per-method cost. A production instance allows 1000 requests per 10 seconds across the instance, and a development instance allows 100 per 10 seconds. A few endpoints carry their own tighter limits: sending invitations is capped at 100 per hour (25 per hour in bulk), organization invitations at 250 per hour (50 in bulk), and merging a user's or organization's metadata at 10 requests per 10 seconds for that object. Going over returns HTTP 429 with a Retry-After header giving the seconds until the block clears.
List endpoints page with limit and offset query parameters. limit sets the page size, defaulting to 10 and capped at 500, and offset sets how many records to skip. Many list responses include a total_count alongside the page of data, so a client can page through the full set.
A list endpoint returns at most 500 records per page, the maximum value of limit. Some filter parameters accept up to 100 values, for example listing users by up to 100 email addresses at once.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | authentication_invalid | The request was not authenticated, for example a missing, malformed, or wrong secret key (could_not_authenticate_request). | Send a valid secret key for the right instance as a Bearer token, and rotate the key if it may be compromised. |
| 403 | authorization_invalid | The request was authenticated but not permitted for this action or resource. | Confirm the instance and the resource match the key, and that the action is allowed for it. |
| 404 | resource_not_found | The requested object does not exist in this instance, or the path is wrong. | Verify the ID and that it belongs to the same instance as the key. |
| 422 | form_param_value_invalid | The request body failed validation, for example a missing or invalid parameter (form_param_missing, form_param_value_invalid). This status covers most request errors. | Read the long_message and the meta.param_name field, fix the parameter, and resend. |
| 429 | too_many_requests | The rate limit for the secret key, or for a specific endpoint, was exceeded. | Back off using the Retry-After header, then retry. Smooth the request rate. |
Clerk dates each API version and a request pins one with a header, so an integration moves to a new version deliberately rather than being changed underneath it.
Clerk identifies each API version by its release date and a request pins one with the Clerk-API-Version header. A new dated version is cut only for changes that are not backward-compatible.
A dated version bringing more consistency to the Clerk Billing API endpoints.
A dated version introducing session token version 2.
A dated version changing the SAML sign-in response.
The first Clerk API version. Every later change up to the next dated version is backward-compatible with it.
Pin a dated version with the Clerk-API-Version header and move up when ready.
Clerk API versions ↗Bollard AI sits between a team's AI agents and Clerk. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.