openapi.city
Sign in

Clerk Backend API

Authentication and user management for developers

clerk.com/docs ↗
Version
v1
OpenAPI
3.0.3
Endpoints
109
Schemas
112
81
Quality
Updated
3 days ago
Identity identity authentication user-management
Use this API in your AI agent

Query structured spec data via REST or MCP. Get exactly what your agent needs.

Get API Key

Server URLs

https://api.clerk.com/v1

Endpoints

Clear filters
GET POST PUT PATCH DELETE

Allowlist/blocklist 2 endpoints

GET /allowlist_identifiers

Get a list of all identifiers allowed to sign up to an instance

operationId: AllowlistBlocklist_listAllowedIdentifiers

Responses

200

Success
401

Authentication invalid
402

Payment required
GET /allowlist_identifiers
GET /blocklist_identifiers

Get a list of all identifiers which are not allowed to access an instance

operationId: AllowlistBlocklist_listBlockedIdentifiers

Responses

200

Success
401

Authentication invalid
402

Payment required
GET /blocklist_identifiers

Clients 1 endpoints

GET /clients/{client_id}

Returns the details of a client.

operationId: Clients_getDetails

Parameters

Name In Required Type Description
client_id path required string

Client ID.

Responses

200

Success
400

Request was not successful
401

Authentication invalid
404

Resource not found
GET /clients/{client_id}

Domains 1 endpoints

GET /domains

Use this endpoint to get a list of all domains for an instance.
The response will contain the primary domain for the instance and any satellite domains. Each domain in the response contains information about the URLs where Clerk operates and the required CNAME targets.

operationId: Domains_getAllDomains

Responses

200

A list of domains
GET /domains

Email&smstemplates 2 endpoints

GET /templates/{template_type}

Returns a list of all templates.
The templates are returned sorted by position.

operationId: EmailSmsTemplates_listSortedByPosition

Parameters

Name In Required Type Description
template_type path required string

The type of templates to list (email or SMS)

Responses

200

Success
400

Request was not successful
401

Authentication invalid
422

Invalid request parameters
GET /templates/{template_type}
GET /templates/{template_type}/{slug}

Returns the details of a template

operationId: EmailSmsTemplates_getTemplateDetails

Parameters

Name In Required Type Description
template_type path required string

The type of templates to retrieve (email or SMS)
slug path required string

The slug (i.e. machine-friendly name) of the template to retrieve

Responses

200

Success
400

Request was not successful
401

Authentication invalid
404

Resource not found
GET /templates/{template_type}/{slug}

Emailaddresses 1 endpoints

GET /email_addresses/{email_address_id}

Returns the details of an email address.

operationId: EmailAddresses_getDetails

Parameters

Name In Required Type Description
email_address_id path required string

The ID of the email address to retrieve

Responses

200

Success
400

Request was not successful
401

Authentication invalid
403

Authorization invalid
404

Resource not found
GET /email_addresses/{email_address_id}

Invitations 1 endpoints

GET /invitations

Returns all non-revoked invitations for your application, sorted by creation date

operationId: Invitations_listAllNonRevoked

Parameters

Name In Required Type Description
limit query optional number

Applies a limit to the number of results returned.
Can be used for paginating the results together with offset.
Must be an integer greater than zero and less than 500.
By default, if not supplied, a limit of 10 is used.
offset query optional number

Skip the first offset results when paginating.
Needs to be an integer greater or equal to zero.
To be used in conjunction with limit.
status query optional string

Filter invitations based on their status

Responses

200

List of invitations
GET /invitations

Jwks 1 endpoints

GET /jwks

Retrieve the JSON Web Key Set of the instance

operationId: Jwks_getJsonWebKeySet

Responses

200

The JSON Web Key Set
GET /jwks

Jwttemplates 2 endpoints

GET /jwt_templates
operationId: JwtTemplates_listAllTemplates

Responses

200

List of JWT templates
GET /jwt_templates
GET /jwt_templates/{template_id}

Retrieve the details of a given JWT template

operationId: JwtTemplates_getTemplateDetails

Parameters

Name In Required Type Description
template_id path required string

JWT Template ID

Responses

200

Success
404

Resource not found
GET /jwt_templates/{template_id}

Miscellaneous 1 endpoints

GET /public/interstitial

The Clerk interstitial endpoint serves an html page that loads clerk.js in order to check the user’s authentication state.
It is used by Clerk SDKs when the user’s authentication state cannot be immediately determined.

operationId: Miscellaneous_getInterstitialMarkup

Parameters

Name In Required Type Description
frontendApi query optional string

The Frontend API key of your instance
publishable_key query optional string

The publishable key of your instance

Responses

200

The interstitial page markup
400

A required query parameter is missing
500

An infinite redirect loop was detected
GET /public/interstitial

Oauthapplications 2 endpoints

GET /oauth_applications

This request returns the list of OAuth applications for an instance.
Results can be paginated using the optional limit and offset query parameters.
The OAuth applications are ordered by descending creation date.
Most recent OAuth applications will be returned first.

operationId: OAuthApplications_listSortedByDescendingCreationDate

Parameters

Name In Required Type Description
limit query optional number

Applies a limit to the number of results returned.
Can be used for paginating the results together with offset.
Must be an integer greater than zero and less than 500.
By default, if not supplied, a limit of 10 is used.
offset query optional number

Skip the first offset results when paginating.
Needs to be an integer greater or equal to zero.
To be used in conjunction with limit.

Responses

200

A list of OAuth applications
400

Request was not successful
403

Authorization invalid
422

Invalid request parameters
GET /oauth_applications
GET /oauth_applications/{oauth_application_id}

Fetches the OAuth application whose ID matches the provided id in the path.

operationId: OAuthApplications_getById

Parameters

Name In Required Type Description
oauth_application_id path required string

The ID of the OAuth application

Responses

200

An OAuth application
403

Authorization invalid
404

Resource not found
GET /oauth_applications/{oauth_application_id}

Organizationinvitations 2 endpoints

GET /organizations/{organization_id}/invitations

This request returns the list of organization invitations.
Results can be paginated using the optional limit and offset query parameters.
You can filter them by providing the ‘status’ query parameter, that accepts multiple values.
The organization invitations are ordered by descending creation date.
Most recent invitations will be returned first.
Any invitations created as a result of an Organization Domain are not included in the results.

operationId: OrganizationInvitations_list

Parameters

Name In Required Type Description
organization_id path required string

The organization ID.
limit query optional number

Applies a limit to the number of results returned.
Can be used for paginating the results together with offset.
Must be an integer greater than zero and less than 500.
By default, if not supplied, a limit of 10 is used.
offset query optional number

Skip the first offset results when paginating.
Needs to be an integer greater or equal to zero.
To be used in conjunction with limit.
status query optional string

Filter organization invitations based on their status

Responses

200

A list of organization invitations
400

Request was not successful
404

Resource not found
GET /organizations/{organization_id}/invitations
GET /organizations/{organization_id}/invitations/{invitation_id}

Use this request to get an existing organization invitation by ID.

operationId: OrganizationInvitations_getById

Parameters

Name In Required Type Description
organization_id path required string

The organization ID.
invitation_id path required string

The organization invitation ID.

Responses

200

An organization invitation
400

Request was not successful
403

Authorization invalid
404

Resource not found
GET /organizations/{organization_id}/invitations/{invitation_id}

Organizationmemberships 1 endpoints

GET /organizations/{organization_id}/memberships

Retrieves all user memberships for the given organization

operationId: OrganizationMemberships_getAllMembers

Parameters

Name In Required Type Description
organization_id path required string

The organization ID.
limit query optional number

Applies a limit to the number of results returned.
Can be used for paginating the results together with offset.
Must be an integer greater than zero and less than 500.
By default, if not supplied, a limit of 10 is used.
offset query optional number

Skip the first offset results when paginating.
Needs to be an integer greater or equal to zero.
To be used in conjunction with limit.
order_by query optional string

Sorts organizations memberships by phone_number, email_address, created_at, first_name, last_name or username.
By prepending one of those values with + or -,
we can choose to sort in ascending (ASC) or descending (DESC) order.”

Responses

200

A list of organization memberships
401

Authentication invalid
422

Invalid request parameters
GET /organizations/{organization_id}/memberships

Organizations 2 endpoints

GET /organizations

This request returns the list of organizations for an instance.
Results can be paginated using the optional limit and offset query parameters.
The organizations are ordered by descending creation date.
Most recent organizations will be returned first.

operationId: Organizations_listSortedByCreationDate

Parameters

Name In Required Type Description
limit query optional number

Applies a limit to the number of results returned.
Can be used for paginating the results together with offset.
Must be an integer greater than zero and less than 500.
By default, if not supplied, a limit of 10 is used.
offset query optional number

Skip the first offset results when paginating.
Needs to be an integer greater or equal to zero.
To be used in conjunction with limit.
include_members_count query optional boolean

Flag to denote whether the member counts of each organization should be included in the response or not.
query query optional string

Returns organizations with ID, name, or slug that match the given query.
Uses exact match for organization ID and partial match for name and slug.
order_by query optional string

Allows to return organizations in a particular order.
At the moment, you can order the returned organizations either by their name, created_at or members_count.
In order to specify the direction, you can use the +/- symbols prepended in the property to order by.
For example, if you want organizations to be returned in descending order according to their created_at property, you can use -created_at.
If you don’t use + or -, then + is implied.
Defaults to -created_at.

Responses

200

A list of organizations
400

Request was not successful
403

Authorization invalid
422

Invalid request parameters
GET /organizations
GET /organizations/{organization_id}

Fetches the organization whose ID or slug matches the provided id_or_slug URL query parameter.

operationId: Organizations_getByIdOrSlug

Parameters

Name In Required Type Description
organization_id path required string

The ID or slug of the organization

Responses

200

An organization
403

Authorization invalid
404

Resource not found
GET /organizations/{organization_id}

Phonenumbers 1 endpoints

GET /phone_numbers/{phone_number_id}

Returns the details of a phone number

operationId: PhoneNumbers_getDetails

Parameters

Name In Required Type Description
phone_number_id path required string

The ID of the phone number to retrieve

Responses

200

Success
400

Request was not successful
401

Authentication invalid
403

Authorization invalid
404

Resource not found
GET /phone_numbers/{phone_number_id}

Redirecturls 2 endpoints

GET /redirect_urls

Lists all whitelisted redirect_urls for the instance

operationId: RedirectUrLs_listAll

Responses

200

List of Redirect URLs
GET /redirect_urls
GET /redirect_urls/{id}

Retrieve the details of the redirect URL with the given ID

operationId: RedirectUrLs_getById

Parameters

Name In Required Type Description
id path required string

The ID of the redirect URL

Responses

200

Success
404

Resource not found
GET /redirect_urls/{id}

Samlconnections 2 endpoints

GET /saml_connections

Returns the list of SAML Connections for an instance.
Results can be paginated using the optional limit and offset query parameters.
The SAML Connections are ordered by descending creation date and the most recent will be returned first.

operationId: SamlConnectionsBeta_getList

Parameters

Name In Required Type Description
limit query optional number

Applies a limit to the number of results returned.
Can be used for paginating the results together with offset.
Must be an integer greater than zero and less than 500.
By default, if not supplied, a limit of 10 is used.
offset query optional number

Skip the first offset results when paginating.
Needs to be an integer greater or equal to zero.
To be used in conjunction with limit.

Responses

200

A list of SAML Connections
402

Payment required
403

Authorization invalid
422

Invalid request parameters
GET /saml_connections
GET /saml_connections/{saml_connection_id}

Fetches the SAML Connection whose ID matches the provided saml_connection_id in the path.

operationId: SamlConnectionsBeta_getById

Parameters

Name In Required Type Description
saml_connection_id path required string

The ID of the SAML Connection

Responses

200

A SAML Connection
402

Payment required
403

Authorization invalid
404

Resource not found
GET /saml_connections/{saml_connection_id}

Sessions 2 endpoints

GET /sessions

Returns a list of all sessions.
The sessions are returned sorted by creation date, with the newest sessions appearing first.
Deprecation Notice (2024-01-01): All parameters were initially considered optional, however
moving forward at least one of client_id or user_id parameters should be provided.

operationId: Sessions_listSortedByCreationDate

Parameters

Name In Required Type Description
client_id query optional string

List sessions for the given client
user_id query optional string

List sessions for the given user
status query optional string

Filter sessions by the provided status
limit query optional number

Applies a limit to the number of results returned.
Can be used for paginating the results together with offset.
Must be an integer greater than zero and less than 500.
By default, if not supplied, a limit of 10 is used.
offset query optional number

Skip the first offset results when paginating.
Needs to be an integer greater or equal to zero.
To be used in conjunction with limit.

Responses

200

Success
400

Request was not successful
401

Authentication invalid
422

Invalid request parameters
GET /sessions
GET /sessions/{session_id}

Retrieve the details of a session

operationId: Sessions_getDetails

Parameters

Name In Required Type Description
session_id path required string

The ID of the session

Responses

200

Success
400

Request was not successful
401

Authentication invalid
404

Resource not found
GET /sessions/{session_id}

Users 5 endpoints

GET /users

Returns a list of all users.
The users are returned sorted by creation date, with the newest users appearing first.

operationId: Users_listSortedByCreationDate

Parameters

Name In Required Type Description
email_address query optional array

Returns users with the specified email addresses.
Accepts up to 100 email addresses.
Any email addresses not found are ignored.
phone_number query optional array

Returns users with the specified phone numbers.
Accepts up to 100 phone numbers.
Any phone numbers not found are ignored.
external_id query optional array

Returns users with the specified external ids.
For each external id, the + and - can be
prepended to the id, which denote whether the
respective external id should be included or
excluded from the result set.
Accepts up to 100 external ids.
Any external ids not found are ignored.
username query optional array

Returns users with the specified usernames.
Accepts up to 100 usernames.
Any usernames not found are ignored.
web3_wallet query optional array

Returns users with the specified web3 wallet addresses.
Accepts up to 100 web3 wallet addresses.
Any web3 wallet addressed not found are ignored.
user_id query optional array

Returns users with the user ids specified.
For each user id, the + and - can be
prepended to the id, which denote whether the
respective user id should be included or
excluded from the result set.
Accepts up to 100 user ids.
Any user ids not found are ignored.
organization_id query optional array

Returns users that have memberships to the
given organizations.
For each organization id, the + and - can be
prepended to the id, which denote whether the
respective organization should be included or
excluded from the result set.
Accepts up to 100 organization ids.
query query optional string

Returns users that match the given query.
For possible matches, we check the email addresses, phone numbers, usernames, web3 wallets, user ids, first and last names.
The query value doesn’t need to match the exact value you are looking for, it is capable of partial matches as well.
last_active_at_since query optional integer

Returns users that had session activity since the given date, with day precision.
Providing a value with higher precision than day will result in an error.
Example: use 1700690400000 to retrieve users that had session activity from 2023-11-23 until the current day.
limit query optional number

Applies a limit to the number of results returned.
Can be used for paginating the results together with offset.
Must be an integer greater than zero and less than 500.
By default, if not supplied, a limit of 10 is used.
offset query optional number

Skip the first offset results when paginating.
Needs to be an integer greater or equal to zero.
To be used in conjunction with limit.
order_by query optional string

Allows to return users in a particular order.
At the moment, you can order the returned users by their created_at,updated_at,email_address,web3wallet,first_name,last_name,phone_number,username,last_active_at,last_sign_in_at.
In order to specify the direction, you can use the +/- symbols prepended in the property to order by.
For example, if you want users to be returned in descending order according to their created_at property, you can use -created_at.
If you don’t use + or -, then + is implied. We only support one order_by parameter, and if multiple order_by parameters are provided, we will only keep the first one. For example,
if you pass order_by=username&order_by=created_at, we will consider only the first order_by parameter, which is username. The created_at parameter will be ignored in this case.

Responses

200

Success
400

Request was not successful
401

Authentication invalid
422

Invalid request parameters
GET /users
GET /users/count

Returns a total count of all users that match the given filtering criteria.

operationId: Users_getTotalCount

Parameters

Name In Required Type Description
email_address query optional array

Counts users with the specified email addresses.
Accepts up to 100 email addresses.
Any email addresses not found are ignored.
phone_number query optional array

Counts users with the specified phone numbers.
Accepts up to 100 phone numbers.
Any phone numbers not found are ignored.
external_id query optional array

Counts users with the specified external ids.
Accepts up to 100 external ids.
Any external ids not found are ignored.
username query optional array

Counts users with the specified usernames.
Accepts up to 100 usernames.
Any usernames not found are ignored.
web3_wallet query optional array

Counts users with the specified web3 wallet addresses.
Accepts up to 100 web3 wallet addresses.
Any web3 wallet addressed not found are ignored.
user_id query optional array

Counts users with the user ids specified.
Accepts up to 100 user ids.
Any user ids not found are ignored.
query query optional string

Counts users that match the given query.
For possible matches, we check the email addresses, phone numbers, usernames, web3 wallets, user ids, first and last names.
The query value doesn’t need to match the exact value you are looking for, it is capable of partial matches as well.

Responses

200

Success
422

Invalid request parameters
GET /users/count
GET /users/{user_id}

Retrieve the details of a user

operationId: Users_getUserDetails

Parameters

Name In Required Type Description
user_id path required string

The ID of the user to retrieve

Responses

200

Success
400

Request was not successful
401

Authentication invalid
404

Resource not found
GET /users/{user_id}
GET /users/{user_id}/oauth_access_tokens/{provider}

Fetch the corresponding OAuth access token for a user that has previously authenticated with a particular OAuth provider.
For OAuth 2.0, if the access token has expired and we have a corresponding refresh token, the access token will be refreshed transparently the new one will be returned.

operationId: Users_getOAuthAccessToken

Parameters

Name In Required Type Description
user_id path required string

The ID of the user for which to retrieve the OAuth access token
provider path required string

The ID of the OAuth provider (e.g. oauth_google)

Responses

200

The OAuth access token of the user, if any.
422

Invalid request parameters
GET /users/{user_id}/oauth_access_tokens/{provider}
GET /users/{user_id}/organization_memberships

Retrieve a paginated list of the user’s organization memberships

operationId: Users_getOrganizationMemberships

Parameters

Name In Required Type Description
user_id path required string

The ID of the user whose organization memberships we want to retrieve
limit query optional number

Applies a limit to the number of results returned.
Can be used for paginating the results together with offset.
Must be an integer greater than zero and less than 500.
By default, if not supplied, a limit of 10 is used.
offset query optional number

Skip the first offset results when paginating.
Needs to be an integer greater or equal to zero.
To be used in conjunction with limit.

Responses

200

A list of organization memberships
403

Request was not successful
GET /users/{user_id}/organization_memberships
Load more endpoints

Schemas

object ActorToken 
{
  "type": "object",
  "required": [
    "object",
    "id",
    "user_id",
    "actor",
    "status",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "url": {
      "type": "string",
      "nullable": true
    },
    "actor": {
      "type": "object"
    },
    "token": {
      "type": "string",
      "nullable": true
    },
    "object": {
      "enum": [
        "actor_token"
      ],
      "type": "string"
    },
    "status": {
      "enum": [
        "pending",
        "accepted",
        "revoked"
      ],
      "type": "string"
    },
    "user_id": {
      "type": "string"
    },
    "created_at": {
      "type": "integer",
      "format": "int64",
      "description": "Unix timestamp of creation.\n"
    },
    "updated_at": {
      "type": "integer",
      "format": "int64",
      "description": "Unix timestamp of last update.\n"
    }
  }
}
object ActorTokensCreateTokenRequest 
{
  "type": "object",
  "required": [
    "user_id",
    "actor"
  ],
  "properties": {
    "actor": {
      "type": "object",
      "example": {
        "sub": "user_2OEpKhcCN1Lat9NQ0G6puh7q5Rb"
      },
      "description": "The actor payload. It needs to include a sub property which should contain the ID of the actor.\nThis whole payload will be also included in the JWT session token."
    },
    "user_id": {
      "type": "string",
      "description": "The ID of the user that can use the newly created sign in token."
    },
    "expires_in_seconds": {
      "type": "integer",
      "default": 3600,
      "description": "Optional parameter to specify the life duration of the actor token in seconds.\nBy default, the duration is 1 hour."
    },
    "session_max_duration_in_seconds": {
      "type": "integer",
      "default": 1800,
      "description": "The maximum duration that the session which will be created by the generated actor token should last.\nBy default, the duration of a session created via an actor token, lasts 30 minutes."
    }
  }
}
object Admin 
{
  "type": "object",
  "required": [
    "status",
    "strategy"
  ],
  "properties": {
    "status": {
      "enum": [
        "verified"
      ],
      "type": "string"
    },
    "attempts": {
      "type": "integer",
      "nullable": true
    },
    "strategy": {
      "enum": [
        "admin"
      ],
      "type": "string"
    },
    "expire_at": {
      "type": "integer",
      "nullable": true
    }
  }
}
object AllowlistBlocklistAddIdentifierRequest 
{
  "type": "object",
  "required": [
    "identifier"
  ],
  "properties": {
    "identifier": {
      "type": "string",
      "description": "The identifier to be added in the block-list.\nThis can be an email address, a phone number or a web3 wallet."
    }
  }
}
object AllowlistBlocklistAddIdentifierToAllowListRequest 
{
  "type": "object",
  "required": [
    "identifier"
  ],
  "properties": {
    "notify": {
      "type": "boolean",
      "default": false,
      "description": "This flag denotes whether the given identifier will receive an invitation to join the application.\nNote that this only works for email address and phone number identifiers."
    },
    "identifier": {
      "type": "string",
      "description": "The identifier to be added in the allow-list.\nThis can be an email address, a phone number or a web3 wallet."
    }
  }
}
array AllowlistBlocklistListAllowedIdentifiersResponse 
{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/AllowlistIdentifier"
  }
}
object AllowlistIdentifier 
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "object": {
      "enum": [
        "allowlist_identifier"
      ],
      "type": "string",
      "description": "String representing the object's type. Objects of the same type share the same value.\n"
    },
    "created_at": {
      "type": "integer",
      "format": "int64",
      "description": "Unix timestamp of creation\n"
    },
    "identifier": {
      "type": "string",
      "description": "An email address or a phone number.\n"
    },
    "updated_at": {
      "type": "integer",
      "format": "int64",
      "description": "Unix timestamp of last update.\n"
    },
    "instance_id": {
      "type": "string"
    },
    "invitation_id": {
      "type": "string"
    },
    "identifier_type": {
      "enum": [
        "email_address",
        "phone_number",
        "web3_wallet"
      ],
      "type": "string"
    }
  }
}
object BetaFeaturesUpdateInstanceDomainRequest 
{
  "type": "object",
  "properties": {
    "home_url": {
      "type": "string",
      "description": "The new home URL of the production instance e.g. https://www.example.com"
    }
  }
}
object BetaFeaturesUpdateInstanceSettingsRequest 
{
  "type": "object",
  "properties": {
    "test_mode": {
      "type": "boolean",
      "nullable": true,
      "description": "Toggles test mode for this instance, allowing the use of test email addresses and phone numbers.\nDefaults to true for development instances."
    },
    "from_email_address": {
      "type": "string",
      "nullable": true,
      "description": "The local part of the email address from which authentication-related emails (e.g. OTP code, magic links) will be sent.\nOnly alphanumeric values are allowed.\nNote that this value should contain only the local part of the address (e.g. `foo` for `foo@example.com`)."
    },
    "progressive_sign_up": {
      "type": "boolean",
      "nullable": true,
      "description": "Enable the Progressive Sign Up algorithm. Refer to the [docs](https://clerk.com/docs/upgrade-guides/progressive-sign-up) for more info."
    },
    "session_token_template": {
      "type": "string",
      "nullable": true,
      "description": "The name of the JWT Template used to augment your session tokens. To disable this, pass an empty string."
    },
    "restricted_to_allowlist": {
      "type": "boolean",
      "default": false,
      "nullable": true,
      "description": "Whether sign up is restricted to email addresses, phone numbers and usernames that are on the allowlist."
    },
    "enhanced_email_deliverability": {
      "type": "boolean",
      "nullable": true,
      "description": "The \"enhanced_email_deliverability\" feature will send emails from \"verifications@clerk.dev\" instead of your domain.\nThis can be helpful if you do not have a high domain reputation."
    }
  }
}
object BetaFeaturesUpdateInstanceSettingsResponse 
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "object": {
      "enum": [
        "instance_settings"
      ],
      "type": "string",
      "description": "String representing the object's type. Objects of the same type share the same value."
    },
    "from_email_address": {
      "type": "string"
    },
    "progressive_sign_up": {
      "type": "boolean"
    },
    "restricted_to_allowlist": {
      "type": "boolean"
    },
    "enhanced_email_deliverability": {
      "type": "boolean"
    }
  }
}
object BetaFeaturesUpdateProductionInstanceDomainRequest 
{
  "type": "object",
  "properties": {
    "home_url": {
      "type": "string",
      "description": "The new home URL of the production instance e.g. https://www.example.com"
    }
  }
}
object BlocklistIdentifier 
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "object": {
      "enum": [
        "blocklist_identifier"
      ],
      "type": "string",
      "description": "String representing the object's type. Objects of the same type share the same value.\n"
    },
    "created_at": {
      "type": "integer",
      "format": "int64",
      "description": "Unix timestamp of creation\n"
    },
    "identifier": {
      "type": "string",
      "description": "An email address, email domain, phone number or web3 wallet.\n"
    },
    "updated_at": {
      "type": "integer",
      "format": "int64",
      "description": "Unix timestamp of last update.\n"
    },
    "instance_id": {
      "type": "string"
    },
    "identifier_type": {
      "enum": [
        "email_address",
        "phone_number",
        "web3_wallet"
      ],
      "type": "string"
    }
  }
}
object BlocklistIdentifiers 
{
  "type": "object",
  "required": [
    "data",
    "total_count"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/BlocklistIdentifier"
      }
    },
    "total_count": {
      "type": "integer",
      "format": "int64",
      "description": "Total number of blocklist identifiers\n"
    }
  }
}
object CNameTarget 
{
  "type": "object",
  "required": [
    "host",
    "value",
    "required"
  ],
  "properties": {
    "host": {
      "type": "string"
    },
    "value": {
      "type": "string"
    },
    "required": {
      "type": "boolean",
      "description": "Denotes whether this CNAME target is required to be set in order for the domain to be considered deployed.\n"
    }
  }
}
object ClerkError 
{
  "type": "object",
  "required": [
    "message",
    "long_message",
    "code"
  ],
  "properties": {
    "code": {
      "type": "string"
    },
    "meta": {
      "type": "object"
    },
    "message": {
      "type": "string"
    },
    "long_message": {
      "type": "string"
    },
    "clerk_trace_id": {
      "type": "string"
    }
  }
}
object ClerkErrors 
{
  "type": "object",
  "required": [
    "errors"
  ],
  "properties": {
    "meta": {
      "type": "object"
    },
    "errors": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/ClerkError"
      }
    }
  }
}
object Client 
{
  "type": "object",
  "required": [
    "object",
    "id",
    "session_ids",
    "sessions",
    "sign_in_id",
    "sign_up_id",
    "last_active_session_id",
    "updated_at",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "String representing the identifier of the session.\n"
    },
    "object": {
      "enum": [
        "client"
      ],
      "type": "string",
      "description": "String representing the object's type. Objects of the same type share the same value.\n"
    },
    "sessions": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Session"
      }
    },
    "created_at": {
      "type": "integer",
      "format": "int64",
      "description": "Unix timestamp of creation.\n"
    },
    "sign_in_id": {
      "type": "string",
      "nullable": true
    },
    "sign_up_id": {
      "type": "string",
      "nullable": true
    },
    "updated_at": {
      "type": "integer",
      "format": "int64",
      "description": "Unix timestamp of last update.\n"
    },
    "session_ids": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "last_active_session_id": {
      "type": "string",
      "nullable": true,
      "description": "Last active session_id.\n"
    }
  }
}
array ClientsListSortedByCreationDateResponse 
{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/Client"
  }
}
object ClientsVerifyClientTokenRequest 
{
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "A JWT Token that represents the active client."
    }
  }
}
object DeletedObject 
{
  "type": "object",
  "required": [
    "object",
    "deleted"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "slug": {
      "type": "string"
    },
    "object": {
      "type": "string"
    },
    "deleted": {
      "type": "boolean"
    }
  }
}
object Domain 
{
  "type": "object",
  "required": [
    "object",
    "id",
    "name",
    "is_satellite",
    "frontend_api_url",
    "development_origin"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "object": {
      "enum": [
        "domain"
      ],
      "type": "string"
    },
    "proxy_url": {
      "type": "string",
      "nullable": true
    },
    "is_satellite": {
      "type": "boolean"
    },
    "cname_targets": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CNameTarget"
      },
      "nullable": true
    },
    "frontend_api_url": {
      "type": "string"
    },
    "development_origin": {
      "type": "string"
    },
    "accounts_portal_url": {
      "type": "string",
      "nullable": true,
      "description": "Null for satellite domains.\n"
    }
  }
}
object Domains 
{
  "type": "object",
  "required": [
    "data",
    "total_count"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Domain"
      }
    },
    "total_count": {
      "type": "integer",
      "format": "int64",
      "description": "Total number of domains\n"
    }
  }
}
object DomainsAddSatelliteDomainRequest 
{
  "type": "object",
  "required": [
    "name",
    "is_satellite"
  ],
  "properties": {
    "name": {
      "type": "string",
      "description": "The new domain name. Can contain the port for development instances."
    },
    "proxy_url": {
      "type": "string",
      "description": "The full URL of the proxy which will forward requests to the Clerk Frontend API for this domain. Applicable only to production instances."
    },
    "is_satellite": {
      "enum": [
        true
      ],
      "type": "boolean",
      "description": "Marks the new domain as satellite. Only `true` is accepted at the moment."
    }
  }
}
object DomainsUpdateDomainRequest 
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "nullable": true,
      "description": "The new domain name. For development instances, can contain the port,\ni.e `myhostname:3000`. For production instances, must be a valid FQDN,\ni.e `mysite.com`. Cannot contain protocol scheme."
    },
    "proxy_url": {
      "type": "string",
      "nullable": true,
      "description": "The full URL of the proxy that will forward requests to Clerk's Frontend API.\nCan only be updated for production instances."
    }
  }
}
object EmailAddress 
{
  "type": "object",
  "required": [
    "object",
    "email_address",
    "verification",
    "linked_to",
    "reserved",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "object": {
      "enum": [
        "email_address"
      ],
      "type": "string",
      "description": "String representing the object's type. Objects of the same type share the same value.\n"
    },
    "reserved": {
      "type": "boolean"
    },
    "linked_to": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/IdentificationLink"
      }
    },
    "created_at": {
      "type": "integer",
      "format": "int64",
      "description": "Unix timestamp of creation\n"
    },
    "updated_at": {
      "type": "integer",
      "format": "int64",
      "description": "Unix timestamp of creation\n"
    },
    "verification": {
      "type": "object",
      "oneOf": [
        {
          "$ref": "#/components/schemas/OTP"
        },
        {
          "$ref": "#/components/schemas/Admin"
        },
        {
          "$ref": "#/components/schemas/Oauth"
        }
      ],
      "nullable": true
    },
    "email_address": {
      "type": "string"
    }
  }
}
object EmailAddressesCreateNewAddressRequest 
{
  "type": "object",
  "properties": {
    "primary": {
      "type": "boolean",
      "nullable": true,
      "description": "Create this email address as the primary email address for the user.\nDefault: false, unless it is the first email address."
    },
    "user_id": {
      "type": "string",
      "description": "The ID representing the user"
    },
    "verified": {
      "type": "boolean",
      "nullable": true,
      "description": "When created, the email address will be marked as verified."
    },
    "email_address": {
      "type": "string",
      "description": "The new email address. Must adhere to the RFC 5322 specification for email address format."
    }
  }
}
object EmailAddressesUpdateAddressRequest 
{
  "type": "object",
  "properties": {
    "primary": {
      "type": "boolean",
      "nullable": true,
      "description": "Set this email address as the primary email address for the user."
    },
    "verified": {
      "type": "boolean",
      "nullable": true,
      "description": "The email address will be marked as verified."
    }
  }
}
array EmailSmsTemplatesListSortedByPositionResponse 
{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/Template"
  }
}
object EmailSmsTemplatesPreviewTemplateRequest 
{
  "type": "object",
  "properties": {
    "body": {
      "type": "string",
      "description": "The template body before variable interpolation"
    },
    "subject": {
      "type": "string",
      "nullable": true,
      "description": "The email subject.\nApplicable only to email templates."
    },
    "from_email_name": {
      "type": "string",
      "description": "The local part of the From email address that will be used for emails.\nFor example, in the address 'hello@example.com', the local part is 'hello'.\nApplicable only to email templates."
    }
  }
}
object EmailSmsTemplatesPreviewTemplateResponse 
{
  "type": "object",
  "example": {},
  "properties": {}
}
object EmailSmsTemplatesToggleDeliveryByTypeAndSlugRequest 
{
  "type": "object",
  "properties": {
    "delivered_by_clerk": {
      "type": "boolean",
      "nullable": true,
      "description": "Whether Clerk should deliver emails or SMS messages based on the current template"
    }
  }
}
object EmailSmsTemplatesUpdateTemplateByTypeAndSlugRequest 
{
  "type": "object",
  "properties": {
    "body": {
      "type": "string",
      "description": "The template body before variable interpolation"
    },
    "name": {
      "type": "string",
      "description": "The user-friendly name of the template"
    },
    "markup": {
      "type": "string",
      "nullable": true,
      "description": "The editor markup used to generate the body of the template"
    },
    "subject": {
      "type": "string",
      "nullable": true,
      "description": "The email subject.\nApplicable only to email templates."
    },
    "from_email_name": {
      "type": "string",
      "description": "The local part of the From email address that will be used for emails.\nFor example, in the address 'hello@example.com', the local part is 'hello'.\nApplicable only to email templates."
    },
    "delivered_by_clerk": {
      "type": "boolean",
      "nullable": true,
      "description": "Whether Clerk should deliver emails or SMS messages based on the current template"
    }
  }
}
object IdentificationLink 
{
  "type": "object",
  "required": [
    "type",
    "id"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "type": {
      "enum": [
        "oauth_google",
        "oauth_mock",
        "saml"
      ],
      "type": "string"
    }
  }
}
object InstanceRestrictions 
{
  "type": "object",
  "properties": {
    "object": {
      "enum": [
        "instance_restrictions"
      ],
      "type": "string",
      "description": "String representing the object's type. Objects of the same type share the same value."
    },
    "allowlist": {
      "type": "boolean"
    },
    "blocklist": {
      "type": "boolean"
    },
    "block_email_subaddresses": {
      "type": "boolean"
    }
  }
}
object InstanceSettingsUpdateInstanceSettingsRequest 
{
  "type": "object",
  "properties": {
    "hibp": {
      "type": "boolean",
      "nullable": true,
      "description": "Whether the instance should be using the HIBP service to check passwords for breaches"
    },
    "test_mode": {
      "type": "boolean",
      "nullable": true,
      "description": "Toggles test mode for this instance, allowing the use of test email addresses and phone numbers.\nDefaults to true for development instances."
    },
    "support_email": {
      "type": "string",
      "nullable": true
    },
    "cookieless_dev": {
      "type": "boolean",
      "deprecated": true,
      "description": "Whether the instance should operate in cookieless development mode (i.e. without third-party cookies).\nDeprecated: Please use `url_based_session_syncing` instead."
    },
    "allowed_origins": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "For browser-like stacks such as browser extensions, Electron, or Capacitor.js the instance allowed origins need to be updated with the request origin value.\nFor Chrome extensions popup, background, or service worker pages the origin is chrome-extension://extension_uiid. For Electron apps the default origin is http://localhost:3000. For Capacitor, the origin is capacitor://localhost."
    },
    "clerk_js_version": {
      "type": "string",
      "nullable": true
    },
    "development_origin": {
      "type": "string",
      "nullable": true
    },
    "url_based_session_syncing": {
      "type": "boolean",
      "description": "Whether the instance should use URL-based session syncing in development mode (i.e. without third-party cookies)."
    },
    "enhanced_email_deliverability": {
      "type": "boolean",
      "nullable": true,
      "description": "The \"enhanced_email_deliverability\" feature will send emails from \"verifications@clerk.dev\" instead of your domain.\nThis can be helpful if you do not have a high domain reputation."
    }
  }
}
object InstanceSettingsUpdateOrganizationSettingsRequest 
{
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean",
      "nullable": true
    },
    "creator_role_id": {
      "type": "string",
      "description": "Specify what the default organization role is for an organization creator."
    },
    "domains_enabled": {
      "type": "boolean",
      "nullable": true
    },
    "admin_delete_enabled": {
      "type": "boolean",
      "nullable": true
    },
    "domains_default_role_id": {
      "type": "string",
      "description": "Specify what the default organization role is for the organization domains."
    },
    "max_allowed_memberships": {
      "type": "integer",
      "nullable": true
    },
    "domains_enrollment_modes": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Specify which enrollment modes to enable for your Organization Domains.\nSupported modes are 'automatic_invitation' & 'automatic_suggestion'."
    }
  }
}
object InstanceSettingsUpdateRestrictionsRequest 
{
  "type": "object",
  "properties": {
    "allowlist": {
      "type": "boolean",
      "nullable": true
    },
    "blocklist": {
      "type": "boolean",
      "nullable": true
    },
    "block_email_subaddresses": {
      "type": "boolean",
      "nullable": true
    },
    "block_disposable_email_domains": {
      "type": "boolean",
      "nullable": true
    }
  }
}
object Invitation 
{
  "type": "object",
  "required": [
    "object",
    "id",
    "email_address",
    "status",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "url": {
      "type": "string",
      "nullable": true
    },
    "object": {
      "enum": [
        "invitation"
      ],
      "type": "string"
    },
    "status": {
      "enum": [
        "pending",
        "accepted",
        "revoked"
      ],
      "type": "string",
      "example": "pending"
    },
    "revoked": {
      "type": "boolean",
      "example": false
    },
    "created_at": {
      "type": "integer",
      "format": "int64",
      "description": "Unix timestamp of creation.\n"
    },
    "updated_at": {
      "type": "integer",
      "format": "int64",
      "description": "Unix timestamp of last update.\n"
    },
    "email_address": {
      "type": "string",
      "format": "email"
    },
    "public_metadata": {
      "type": "object"
    }
  }
}
object InvitationsCreateNewInvitationRequest 
{
  "type": "object",
  "required": [
    "email_address"
  ],
  "properties": {
    "notify": {
      "type": "boolean",
      "default": true,
      "nullable": true,
      "description": "Optional flag which denotes whether an email invitation should be sent to the given email address.\nDefaults to true."
    },
    "redirect_url": {
      "type": "string",
      "description": "Optional URL which specifies where to redirect the user once they click the invitation link.\nThis is only required if you have implemented a [custom flow](https://clerk.com/docs/authentication/invitations#custom-flow) and you're not using Clerk Hosted Pages or Clerk Components."
    },
    "email_address": {
      "type": "string",
      "description": "The email address the invitation will be sent to"
    },
    "ignore_existing": {
      "type": "boolean",
      "default": false,
      "nullable": true,
      "description": "Whether an invitation should be created if there is already an existing invitation for this email address, or it's claimed by another user."
    },
    "public_metadata": {
      "type": "object",
      "description": "Metadata that will be attached to the newly created invitation.\nThe value of this property should be a well-formed JSON object.\nOnce the user accepts the invitation and signs up, these metadata will end up in the user's public metadata."
    }
  }
}
array InvitationsListAllNonRevokedResponse 
{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/Invitation"
  }
}
object InvitationsRevokeInvitationResponse 
{
  "allOf": [
    {
      "$ref": "#/components/schemas/Invitation"
    },
    {
      "type": "object",
      "properties": {
        "status": {
          "enum": [
            "revoked"
          ],
          "type": "string",
          "example": "revoked"
        },
        "revoked": {
          "enum": [
            true
          ],
          "type": "boolean",
          "example": true
        }
      }
    }
  ]
}
object JWTTemplate 
{
  "type": "object",
  "required": [
    "object",
    "id",
    "name",
    "claims",
    "lifetime",
    "allowed_clock_skew",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "claims": {
      "type": "object"
    },
    "object": {
      "enum": [
        "jwt_template"
      ],
      "type": "string"
    },
    "lifetime": {
      "type": "integer"
    },
    "created_at": {
      "type": "integer",
      "format": "int64",
      "description": "Unix timestamp of creation.\n"
    },
    "updated_at": {
      "type": "integer",
      "format": "int64",
      "description": "Unix timestamp of last update.\n"
    },
    "signing_algorithm": {
      "type": "string"
    },
    "allowed_clock_skew": {
      "type": "integer"
    },
    "custom_signing_key": {
      "type": "boolean"
    }
  }
}
object JwtTemplatesCreateTemplateRequest 
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "nullable": false,
      "description": "JWT template name"
    },
    "claims": {
      "type": "object",
      "nullable": false,
      "description": "JWT template claims in JSON format"
    },
    "lifetime": {
      "type": "number",
      "maximum": 315360000,
      "minimum": 30,
      "nullable": true,
      "description": "JWT token lifetime"
    },
    "signing_key": {
      "type": "string",
      "nullable": true,
      "description": "The custom signing private key to use when minting JWTs"
    },
    "signing_algorithm": {
      "type": "string",
      "nullable": true,
      "description": "The custom signing algorithm to use when minting JWTs"
    },
    "allowed_clock_skew": {
      "type": "number",
      "maximum": 300,
      "minimum": 0,
      "nullable": true,
      "description": "JWT token allowed clock skew"
    },
    "custom_signing_key": {
      "type": "boolean",
      "nullable": false,
      "description": "Whether a custom signing key/algorithm is also provided for this template"
    }
  }
}
array JwtTemplatesListAllTemplatesResponse 
{
  "type": "array",
  "items": {
    "$ref": "#/components/schemas/JWTTemplate"
  }
}
object JwtTemplatesUpdateTemplateByIdRequest 
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "nullable": false,
      "description": "JWT template name"
    },
    "claims": {
      "type": "object",
      "nullable": false,
      "description": "JWT template claims in JSON format"
    },
    "lifetime": {
      "type": "number",
      "maximum": 315360000,
      "minimum": 30,
      "nullable": true,
      "description": "JWT token lifetime"
    },
    "signing_key": {
      "type": "string",
      "nullable": true,
      "description": "The custom signing private key to use when minting JWTs"
    },
    "signing_algorithm": {
      "type": "string",
      "nullable": true,
      "description": "The custom signing algorithm to use when minting JWTs"
    },
    "allowed_clock_skew": {
      "type": "number",
      "maximum": 300,
      "minimum": 0,
      "nullable": true,
      "description": "JWT token allowed clock skew"
    },
    "custom_signing_key": {
      "type": "boolean",
      "nullable": false,
      "description": "Whether a custom signing key/algorithm is also provided for this template"
    }
  }
}
object OAuthApplication 
{
  "type": "object",
  "required": [
    "object",
    "id",
    "instance_id",
    "name",
    "public",
    "client_id",
    "scopes",
    "callback_url",
    "authorize_url",
    "token_fetch_url",
    "user_info_url",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "object": {
      "enum": [
        "oauth_application"
      ],
      "type": "string"
    },
    "public": {
      "type": "boolean"
    },
    "scopes": {
      "type": "string"
    },
    "client_id": {
      "type": "string"
    },
    "created_at": {
      "type": "integer",
      "format": "int64",
      "description": "Unix timestamp of creation.\n"
    },
    "updated_at": {
      "type": "integer",
      "format": "int64",
      "description": "Unix timestamp of last update.\n"
    },
    "instance_id": {
      "type": "string"
    },
    "callback_url": {
      "type": "string"
    },
    "authorize_url": {
      "type": "string"
    },
    "user_info_url": {
      "type": "string"
    },
    "token_fetch_url": {
      "type": "string"
    }
  }
}
object OAuthApplicationWithSecret 
{
  "allOf": [
    {
      "$ref": "#/components/schemas/OAuthApplication"
    },
    {
      "type": "object",
      "properties": {
        "client_secret": {
          "type": "string",
          "description": "Empty if public client.\n"
        }
      }
    }
  ]
}
object OAuthApplications 
{
  "type": "object",
  "required": [
    "data",
    "total_count"
  ],
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/OAuthApplication"
      }
    },
    "total_count": {
      "type": "integer",
      "format": "int64",
      "description": "Total number of OAuth applications\n"
    }
  }
}
object OAuthApplicationsCreateNewApplicationRequest 
{
  "type": "object",
  "required": [
    "name",
    "callback_url"
  ],
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the new OAuth application"
    },
    "public": {
      "type": "boolean",
      "description": "If true, this client is public and cannot securely store a client secret.\nOnly the authorization code flow with proof key for code exchange (PKCE) may be used.\nPublic clients cannot be updated to be confidential clients, and vice versa."
    },
    "scopes": {
      "type": "string",
      "default": "profile email",
      "example": "profile email public_metadata",
      "description": "Define the allowed scopes for the new OAuth applications that dictate the user payload of the OAuth user info endpoint. Available scopes are `profile`, `email`, `public_metadata`, `private_metadata`. Provide the requested scopes as a string, separated by spaces."
    },
    "callback_url": {
      "type": "string",
      "description": "The callback URL of the new OAuth application"
    }
  }
}
object OAuthApplicationsUpdateApplicationRequest 
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The new name of the OAuth application"
    },
    "scopes": {
      "type": "string",
      "default": "profile email",
      "example": "profile email public_metadata private_metadata",
      "description": "Define the allowed scopes for the new OAuth applications that dictate the user payload of the OAuth user info endpoint. Available scopes are `profile`, `email`, `public_metadata`, `private_metadata`. Provide the requested scopes as a string, separated by spaces."
    },
    "callback_url": {
      "type": "string",
      "description": "The new callback URL of the OAuth application"
    }
  }
}
Load more schemas

Versions

Version Endpoints Schemas Ingested Status
v1 109 112 2026-05-11 current
v1 109 112 2026-04-16