Query structured spec data via REST or MCP. Get exactly what your agent needs.
https://api.clerk.com/v1
/beta_features/instance_settings
Updates the settings of an instance
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BetaFeaturesUpdateInstanceSettingsRequest"
}
}
}
}
PATCH /beta_features/instance_settings
/domains/{domain_id}
The `proxy_url` can be updated only for production instances. Update one of the instance's domains. Both primary and satellite domains can be updated. If you choose to use Clerk via proxy, use this endpoint to specify the `proxy_url`. Whenever you decide you'd rather switch to DNS setup for Clerk, simply set `proxy_url` to `null` for the domain. When you update a production instance's primary domain name, you have to make sure that you've completed all the necessary setup steps for DNS and emails to work. Expect downtime otherwise. Updating a primary domain's name will also update the instance's home origin, affecting the default application paths.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| domain_id | path | required | string | The ID of the domain that will be updated. |
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DomainsUpdateDomainRequest"
}
}
},
"required": true
}
PATCH /domains/{domain_id}
/email_addresses/{email_address_id}
Updates an email address.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| email_address_id | path | required | string | The ID of the email address to update |
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EmailAddressesUpdateAddressRequest"
}
}
}
}
PATCH /email_addresses/{email_address_id}
/instance
Updates the settings of an instance
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InstanceSettingsUpdateInstanceSettingsRequest"
}
}
}
}
PATCH /instance
/instance/organization_settings
Updates the organization settings of the instance
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InstanceSettingsUpdateOrganizationSettingsRequest"
}
}
}
}
PATCH /instance/organization_settings
/instance/restrictions
Updates the restriction settings of an instance
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/InstanceSettingsUpdateRestrictionsRequest"
}
}
}
}
PATCH /instance/restrictions
/jwt_templates/{template_id}
Updates an existing JWT template
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| template_id | path | required | string | The ID of the JWT template to update |
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/JwtTemplatesUpdateTemplateByIdRequest"
}
}
}
}
PATCH /jwt_templates/{template_id}
/oauth_applications/{oauth_application_id}
Updates an existing OAuth application
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| oauth_application_id | path | required | string | The ID of the OAuth application to update |
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OAuthApplicationsUpdateApplicationRequest"
}
}
},
"required": true
}
PATCH /oauth_applications/{oauth_application_id}
/organizations/{organization_id}/memberships/{user_id}
Updates the properties of an existing organization membership
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| organization_id | path | required | string | The ID of the organization the membership belongs to |
| user_id | path | required | string | The ID of the user that this membership belongs to |
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationMembershipsUpdateMembershipPropertiesRequest"
}
}
},
"required": true
}
PATCH /organizations/{organization_id}/memberships/{user_id}
/organizations/{organization_id}/memberships/{user_id}/metadata
Update an organization membership's metadata attributes by merging existing values with the provided parameters. Metadata values will be updated via a deep merge. Deep means that any nested JSON objects will be merged as well. You can remove metadata keys at any level by setting their value to `null`.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| organization_id | path | required | string | The ID of the organization the membership belongs to |
| user_id | path | required | string | The ID of the user that this membership belongs to |
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationMembershipsUpdateMembershipMetadataRequest"
}
}
},
"required": true
}
PATCH /organizations/{organization_id}/memberships/{user_id}/metadata
/organizations/{organization_id}
Updates an existing organization
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| organization_id | path | required | string | The ID of the organization to update |
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationsUpdateOrganizationRequest"
}
}
},
"required": true
}
PATCH /organizations/{organization_id}
/organizations/{organization_id}/metadata
Update organization metadata attributes by merging existing values with the provided parameters. Metadata values will be updated via a deep merge. Deep meaning that any nested JSON objects will be merged as well. You can remove metadata keys at any level by setting their value to `null`.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| organization_id | path | required | string | The ID of the organization for which metadata will be merged or updated |
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrganizationsMergeOrganizationMetadataRequest"
}
}
},
"required": true
}
PATCH /organizations/{organization_id}/metadata
/phone_numbers/{phone_number_id}
Updates a phone number
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| phone_number_id | path | required | string | The ID of the phone number to update |
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PhoneNumbersUpdateDetailsRequest"
}
}
}
}
PATCH /phone_numbers/{phone_number_id}
/saml_connections/{saml_connection_id}
Updates the SAML Connection whose ID matches the provided `id` in the path.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| saml_connection_id | path | required | string | The ID of the SAML Connection to update |
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SamlConnectionsBetaUpdateConnectionByIdRequest"
}
}
},
"required": true
}
PATCH /saml_connections/{saml_connection_id}
/sign_ups/{id}
Update the sign-up with the given ID
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| id | path | required | string | The ID of the sign-up to update |
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SignupsUpdateSignUpByIdRequest"
}
}
}
}
PATCH /sign_ups/{id}
/users/{user_id}
Update a user's attributes. You can set the user's primary contact identifiers (email address and phone numbers) by updating the `primary_email_address_id` and `primary_phone_number_id` attributes respectively. Both IDs should correspond to verified identifications that belong to the user. You can remove a user's username by setting the username attribute to null or the blank string "". This is a destructive action; the identification will be deleted forever. Usernames can be removed only if they are optional in your instance settings and there's at least one other identifier which can be used for authentication. This endpoint allows changing a user's password. When passing the `password` parameter directly you have two further options. You can ignore the password policy checks for your instance by setting the `skip_password_checks` parameter to `true`. You can also choose to sign the user out of all their active sessions on any device once the password is updated. Just set `sign_out_of_other_sessions` to `true`.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| user_id | path | required | string | The ID of the user to update |
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UsersUpdateUserAttributesRequest"
}
}
},
"required": true
}
PATCH /users/{user_id}
/users/{user_id}/metadata
Update a user's metadata attributes by merging existing values with the provided parameters. This endpoint behaves differently than the *Update a user* endpoint. Metadata values will not be replaced entirely. Instead, a deep merge will be performed. Deep means that any nested JSON objects will be merged as well. You can remove metadata keys at any level by setting their value to `null`.
| Name | In | Required | Type | Description |
|---|---|---|---|---|
| user_id | path | required | string | The ID of the user whose metadata will be updated and merged |
{
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UsersMergeUserMetadataAttributesRequest"
}
}
}
}
PATCH /users/{user_id}/metadata
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"
}
}
}
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."
}
}
}
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
}
}
}
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."
}
}
}
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."
}
}
}
AllowlistBlocklistListAllowedIdentifiersResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/AllowlistIdentifier"
}
}
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"
}
}
}
BetaFeaturesUpdateInstanceDomainRequest
{
"type": "object",
"properties": {
"home_url": {
"type": "string",
"description": "The new home URL of the production instance e.g. https://www.example.com"
}
}
}
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."
}
}
}
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"
}
}
}
BetaFeaturesUpdateProductionInstanceDomainRequest
{
"type": "object",
"properties": {
"home_url": {
"type": "string",
"description": "The new home URL of the production instance e.g. https://www.example.com"
}
}
}
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"
}
}
}
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"
}
}
}
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"
}
}
}
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"
}
}
}
ClerkErrors
{
"type": "object",
"required": [
"errors"
],
"properties": {
"meta": {
"type": "object"
},
"errors": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ClerkError"
}
}
}
}
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"
}
}
}
ClientsListSortedByCreationDateResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Client"
}
}
ClientsVerifyClientTokenRequest
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "A JWT Token that represents the active client."
}
}
}
DeletedObject
{
"type": "object",
"required": [
"object",
"deleted"
],
"properties": {
"id": {
"type": "string"
},
"slug": {
"type": "string"
},
"object": {
"type": "string"
},
"deleted": {
"type": "boolean"
}
}
}
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"
}
}
}
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"
}
}
}
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."
}
}
}
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."
}
}
}
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"
}
}
}
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."
}
}
}
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."
}
}
}
EmailSmsTemplatesListSortedByPositionResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Template"
}
}
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."
}
}
}
EmailSmsTemplatesPreviewTemplateResponse
{
"type": "object",
"example": {},
"properties": {}
}
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"
}
}
}
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"
}
}
}
IdentificationLink
{
"type": "object",
"required": [
"type",
"id"
],
"properties": {
"id": {
"type": "string"
},
"type": {
"enum": [
"oauth_google",
"oauth_mock",
"saml"
],
"type": "string"
}
}
}
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"
}
}
}
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."
}
}
}
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'."
}
}
}
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
}
}
}
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"
}
}
}
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."
}
}
}
InvitationsListAllNonRevokedResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Invitation"
}
}
InvitationsRevokeInvitationResponse
{
"allOf": [
{
"$ref": "#/components/schemas/Invitation"
},
{
"type": "object",
"properties": {
"status": {
"enum": [
"revoked"
],
"type": "string",
"example": "revoked"
},
"revoked": {
"enum": [
true
],
"type": "boolean",
"example": true
}
}
}
]
}
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"
}
}
}
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"
}
}
}
JwtTemplatesListAllTemplatesResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/JWTTemplate"
}
}
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"
}
}
}
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"
}
}
}
OAuthApplicationWithSecret
{
"allOf": [
{
"$ref": "#/components/schemas/OAuthApplication"
},
{
"type": "object",
"properties": {
"client_secret": {
"type": "string",
"description": "Empty if public client.\n"
}
}
}
]
}
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"
}
}
}
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"
}
}
}
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"
}
}
}
OTP
{
"type": "object",
"required": [
"status",
"attempts",
"strategy",
"expire_at"
],
"properties": {
"status": {
"enum": [
"unverified",
"verified",
"failed",
"expired"
],
"type": "string"
},
"attempts": {
"type": "integer"
},
"strategy": {
"enum": [
"phone_code",
"email_code",
"reset_password_email_code"
],
"type": "string"
},
"expire_at": {
"type": "integer"
}
}
}
Oauth
{
"type": "object",
"required": [
"status",
"strategy",
"expire_at"
],
"properties": {
"error": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/ClerkError"
}
],
"nullable": true
},
"status": {
"enum": [
"unverified",
"verified",
"failed",
"expired",
"transferable"
],
"type": "string"
},
"attempts": {
"type": "integer",
"nullable": true
},
"strategy": {
"enum": [
"oauth_google",
"oauth_mock"
],
"type": "string"
},
"expire_at": {
"type": "integer"
},
"external_verification_redirect_url": {
"type": "string"
}
}
}
Organization
{
"type": "object",
"required": [
"object",
"id",
"name",
"slug",
"max_allowed_memberships",
"public_metadata",
"private_metadata",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"slug": {
"type": "string"
},
"object": {
"enum": [
"organization"
],
"type": "string"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation.\n"
},
"created_by": {
"type": "string"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update.\n"
},
"members_count": {
"type": "integer",
"nullable": true
},
"public_metadata": {
"type": "object"
},
"private_metadata": {
"type": "object"
},
"admin_delete_enabled": {
"type": "boolean"
},
"max_allowed_memberships": {
"type": "integer"
}
}
}
OrganizationInvitation
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"role": {
"type": "string"
},
"object": {
"enum": [
"organization_invitation"
],
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.\n"
},
"status": {
"type": "string"
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation."
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update."
},
"email_address": {
"type": "string"
},
"organization_id": {
"type": "string"
},
"public_metadata": {
"type": "object"
},
"private_metadata": {
"type": "object"
}
},
"description": "An organization invitation"
}
OrganizationInvitations
{
"type": "object",
"required": [
"data",
"total_count"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OrganizationInvitation"
}
},
"total_count": {
"type": "integer",
"format": "int64",
"description": "Total number of organization invitations\n"
}
}
}
OrganizationInvitationsBulkCreateAndSendRequest
{
"type": "array",
"items": {
"type": "object",
"required": [
"email_address",
"inviter_user_id",
"role"
],
"properties": {
"role": {
"type": "string",
"description": "The role of the new member in the organization."
},
"redirect_url": {
"type": "string",
"description": "Optional URL that the invitee will be redirected to once they accept the invitation by clicking the join link in the invitation email."
},
"email_address": {
"type": "string",
"description": "The email address of the new member that is going to be invited to the organization"
},
"inviter_user_id": {
"type": "string",
"description": "The ID of the user that invites the new member to the organization.\nMust be an administrator in the organization."
},
"public_metadata": {
"type": "object",
"description": "Metadata saved on the organization invitation, read-only from the Frontend API and fully accessible (read/write) from the Backend API."
},
"private_metadata": {
"type": "object",
"description": "Metadata saved on the organization invitation, fully accessible (read/write) from the Backend API but not visible from the Frontend API."
}
}
}
}
OrganizationInvitationsCreateAndSendRequest
{
"type": "object",
"required": [
"email_address",
"inviter_user_id",
"role"
],
"properties": {
"role": {
"type": "string",
"description": "The role of the new member in the organization"
},
"redirect_url": {
"type": "string",
"description": "Optional URL that the invitee will be redirected to once they accept the invitation by clicking the join link in the invitation email."
},
"email_address": {
"type": "string",
"description": "The email address of the new member that is going to be invited to the organization"
},
"inviter_user_id": {
"type": "string",
"description": "The ID of the user that invites the new member to the organization.\nMust be an administrator in the organization."
},
"public_metadata": {
"type": "object",
"description": "Metadata saved on the organization invitation, read-only from the Frontend API and fully accessible (read/write) from the Backend API."
},
"private_metadata": {
"type": "object",
"description": "Metadata saved on the organization invitation, fully accessible (read/write) from the Backend API but not visible from the Frontend API."
}
}
}
OrganizationInvitationsRevokeInvitationRequest
{
"type": "object",
"required": [
"requesting_user_id"
],
"properties": {
"requesting_user_id": {
"type": "string",
"description": "The ID of the user that revokes the invitation.\nMust be an administrator in the organization."
}
}
}
OrganizationMembership
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"role": {
"type": "string"
},
"object": {
"enum": [
"organization_membership"
],
"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."
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update."
},
"permissions": {
"type": "array",
"items": {
"type": "string"
}
},
"organization": {
"$ref": "#/components/schemas/Organization"
},
"public_metadata": {
"type": "object",
"description": "Metadata saved on the organization membership, accessible from both Frontend and Backend APIs"
},
"private_metadata": {
"type": "object",
"description": "Metadata saved on the organization membership, accessible only from the Backend API"
},
"public_user_data": {
"type": "object",
"properties": {
"user_id": {
"type": "string",
"nullable": false
},
"has_image": {
"type": "boolean"
},
"image_url": {
"type": "string"
},
"last_name": {
"type": "string",
"nullable": true
},
"first_name": {
"type": "string",
"nullable": true
},
"identifier": {
"type": "string",
"nullable": true
},
"profile_image_url": {
"type": "string",
"nullable": true,
"deprecated": true
}
}
}
},
"description": "Hello world",
"x-konfig-properties": {
"organization": {
"type": "object",
"nullable": false
}
}
}
OrganizationMemberships
{
"type": "object",
"required": [
"data",
"total_count"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OrganizationMembership"
}
},
"total_count": {
"type": "integer",
"format": "int64",
"description": "Total number of organization memberships\n"
}
}
}
OrganizationMembershipsAddUserToOrganizationRequest
{
"type": "object",
"required": [
"user_id",
"role"
],
"properties": {
"role": {
"type": "string",
"description": "The role that the new member will have in the organization."
},
"user_id": {
"type": "string",
"description": "The ID of the user that will be added as a member in the organization.\nThe user needs to exist in the same instance as the organization and must not be a member of the given organization already."
}
}
}
OrganizationMembershipsUpdateMembershipMetadataRequest
{
"type": "object",
"properties": {
"public_metadata": {
"type": "object",
"description": "Metadata saved on the organization membership, that is visible to both your frontend and backend.\nThe new object will be merged with the existing value."
},
"private_metadata": {
"type": "object",
"description": "Metadata saved on the organization membership that is only visible to your backend.\nThe new object will be merged with the existing value."
}
}
}
OrganizationMembershipsUpdateMembershipPropertiesRequest
{
"type": "object",
"required": [
"role"
],
"properties": {
"role": {
"type": "string",
"description": "The new role of the given membership."
}
}
}
OrganizationSettings
{
"type": "object",
"required": [
"object",
"enabled",
"max_allowed_memberships",
"creator_role",
"admin_delete_enabled",
"domains_enabled",
"domains_enrollment_modes",
"domains_default_role"
],
"properties": {
"object": {
"enum": [
"organization_settings"
],
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value."
},
"enabled": {
"type": "boolean"
},
"creator_role": {
"type": "string",
"description": "The role key that a user will be assigned after creating an organization."
},
"domains_enabled": {
"type": "boolean"
},
"max_allowed_roles": {
"type": "integer"
},
"admin_delete_enabled": {
"type": "boolean",
"description": "The default for whether an admin can delete an organization with the Frontend API."
},
"domains_default_role": {
"type": "string",
"description": "The role key that it will be used in order to create an organization invitation or suggestion."
},
"max_allowed_memberships": {
"type": "integer"
},
"max_allowed_permissions": {
"type": "integer"
},
"domains_enrollment_modes": {
"type": "array",
"items": {
"enum": [
"manual_invitation",
"automatic_invitation",
"automatic_suggestion"
],
"type": "string"
}
}
}
}
OrganizationWithLogo
{
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/Organization"
},
{
"type": "object",
"required": [
"image_url"
],
"properties": {
"logo_url": {
"type": "string",
"deprecated": true
},
"has_image": {
"type": "boolean"
},
"image_url": {
"type": "string"
}
}
}
]
}
Organizations
{
"type": "object",
"required": [
"data",
"total_count"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Organization"
}
},
"total_count": {
"type": "integer",
"format": "int64",
"description": "Total number of organizations\n"
}
}
}
OrganizationsCreateNewOrganizationRequest
{
"type": "object",
"required": [
"name",
"created_by"
],
"properties": {
"name": {
"type": "string",
"description": "The name of the new organization"
},
"slug": {
"type": "string",
"description": "A slug for the new organization.\nCan contain only lowercase alphanumeric characters and the dash \"-\".\nMust be unique for the instance."
},
"created_by": {
"type": "string",
"description": "The ID of the User who will become the administrator for the new organization"
},
"public_metadata": {
"type": "object",
"description": "Metadata saved on the organization, read-only from the Frontend API and fully accessible (read/write) from the Backend API"
},
"private_metadata": {
"type": "object",
"description": "Metadata saved on the organization, accessible only from the Backend API"
},
"max_allowed_memberships": {
"type": "integer",
"description": "The maximum number of memberships allowed for this organization"
}
}
}
OrganizationsMergeOrganizationMetadataRequest
{
"type": "object",
"properties": {
"public_metadata": {
"type": "object",
"description": "Metadata saved on the organization, that is visible to both your frontend and backend.\nThe new object will be merged with the existing value."
},
"private_metadata": {
"type": "object",
"description": "Metadata saved on the organization that is only visible to your backend.\nThe new object will be merged with the existing value."
}
}
}
OrganizationsUpdateOrganizationLogoRequest
{
"type": "object",
"required": [
"uploader_user_id",
"file"
],
"properties": {
"file": {
"type": "string",
"format": "binary"
},
"uploader_user_id": {
"type": "string",
"description": "The ID of the user that will be credited with the image upload."
}
}
}
OrganizationsUpdateOrganizationRequest
{
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true,
"description": "The new name of the organization"
},
"slug": {
"type": "string",
"nullable": true,
"description": "The new slug of the organization, which needs to be unique in the instance"
},
"public_metadata": {
"type": "object",
"description": "Metadata saved on the organization, that is visible to both your frontend and backend."
},
"private_metadata": {
"type": "object",
"description": "Metadata saved on the organization that is only visible to your backend."
},
"admin_delete_enabled": {
"type": "boolean",
"nullable": true,
"description": "If true, an admin can delete this organization with the Frontend API."
},
"max_allowed_memberships": {
"type": "integer",
"nullable": true,
"description": "The maximum number of memberships allowed for this organization"
}
}
}
Passkey
{
"type": "object",
"required": [
"status",
"strategy"
],
"properties": {
"nonce": {
"enum": [
"nonce"
],
"type": "string"
},
"status": {
"enum": [
"verified"
],
"type": "string"
},
"attempts": {
"type": "integer",
"nullable": true
},
"strategy": {
"enum": [
"passkey"
],
"type": "string"
},
"expire_at": {
"type": "integer",
"nullable": true
}
}
}
PhoneNumber
{
"type": "object",
"required": [
"object",
"phone_number",
"verification",
"linked_to",
"reserved",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string"
},
"object": {
"enum": [
"phone_number"
],
"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"
},
"backup_codes": {
"type": "array",
"items": {
"type": "string"
},
"nullable": true
},
"phone_number": {
"type": "string"
},
"verification": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/OTP"
},
{
"$ref": "#/components/schemas/Admin"
}
],
"nullable": true
},
"default_second_factor": {
"type": "boolean"
},
"reserved_for_second_factor": {
"type": "boolean"
}
}
}
PhoneNumbersCreateNewPhoneNumberRequest
{
"type": "object",
"properties": {
"primary": {
"type": "boolean",
"nullable": true,
"description": "Create this phone number as the primary phone number for the user.\nDefault: false, unless it is the first phone number."
},
"user_id": {
"type": "string",
"description": "The ID representing the user"
},
"verified": {
"type": "boolean",
"nullable": true,
"description": "When created, the phone number will be marked as verified."
},
"phone_number": {
"type": "string",
"description": "The new phone number. Must adhere to the E.164 standard for phone number format."
},
"reserved_for_second_factor": {
"type": "boolean",
"nullable": true,
"description": "Create this phone number as reserved for multi-factor authentication.\nThe phone number must also be verified.\nIf there are no other reserved second factors, the phone number will be set as the default second factor."
}
}
}
PhoneNumbersUpdateDetailsRequest
{
"type": "object",
"properties": {
"primary": {
"type": "boolean",
"nullable": true,
"description": "Set this phone number as the primary phone number for the user."
},
"verified": {
"type": "boolean",
"nullable": true,
"description": "The phone number will be marked as verified."
},
"reserved_for_second_factor": {
"type": "boolean",
"nullable": true,
"description": "Set this phone number as reserved for multi-factor authentication.\nThe phone number must also be verified.\nIf there are no other reserved second factors, the phone number will be set as the default second factor."
}
}
}
ProxyCheck
{
"type": "object",
"required": [
"object",
"id",
"domain_id",
"last_run_at",
"proxy_url",
"successful",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string"
},
"object": {
"enum": [
"proxy_check"
],
"type": "string"
},
"domain_id": {
"type": "string"
},
"proxy_url": {
"type": "string"
},
"created_at": {
"type": "integer"
},
"successful": {
"type": "boolean"
},
"updated_at": {
"type": "integer"
},
"last_run_at": {
"type": "integer"
}
}
}
ProxyChecksVerifyProxyConfigurationRequest
{
"type": "object",
"properties": {
"domain_id": {
"type": "string",
"description": "The ID of the domain that will be updated."
},
"proxy_url": {
"type": "string",
"description": "The full URL of the proxy which will forward requests to the Clerk Frontend API for this domain. e.g. https://example.com/__clerk"
}
}
}
RedirectURL
{
"type": "object",
"required": [
"object",
"id",
"url",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string"
},
"object": {
"enum": [
"redirect_url"
],
"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"
}
}
}
RedirectUrLsCreateNewUrlRequest
{
"type": "object",
"properties": {
"url": {
"type": "string",
"nullable": false,
"description": "The full url value prefixed with `https://` or a custom scheme e.g. `\"https://my-app.com/oauth-callback\"` or `\"my-app://oauth-callback\"`"
}
}
}
RedirectUrLsListAllResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/RedirectURL"
}
}
SAML
{
"type": "object",
"required": [
"status",
"strategy",
"external_verification_redirect_url",
"expire_at"
],
"properties": {
"error": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/ClerkError"
}
],
"nullable": true
},
"status": {
"enum": [
"unverified",
"verified",
"failed",
"expired",
"transferable"
],
"type": "string"
},
"attempts": {
"type": "integer",
"nullable": true
},
"strategy": {
"enum": [
"saml"
],
"type": "string"
},
"expire_at": {
"type": "integer"
},
"external_verification_redirect_url": {
"type": "string",
"nullable": true
}
}
}
SAMLAccount
{
"type": "object",
"required": [
"id",
"object",
"provider",
"active",
"email_address",
"verification"
],
"properties": {
"id": {
"type": "string"
},
"active": {
"type": "boolean"
},
"object": {
"enum": [
"saml_account"
],
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.\n"
},
"provider": {
"type": "string"
},
"last_name": {
"type": "string",
"nullable": true
},
"first_name": {
"type": "string",
"nullable": true
},
"verification": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/SAML"
},
{
"$ref": "#/components/schemas/Ticket"
}
],
"nullable": true
},
"email_address": {
"type": "string"
},
"public_metadata": {
"type": "object"
},
"provider_user_id": {
"type": "string",
"nullable": true
}
}
}
SAMLConnection
{
"type": "object",
"required": [
"object",
"id",
"name",
"domain",
"idp_entity_id",
"idp_sso_url",
"idp_certificate",
"acs_url",
"sp_entity_id",
"sp_metadata_url",
"active",
"provider",
"user_count",
"sync_user_attributes",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"active": {
"type": "boolean"
},
"domain": {
"type": "string"
},
"object": {
"enum": [
"saml_connection"
],
"type": "string"
},
"acs_url": {
"type": "string"
},
"provider": {
"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"
},
"user_count": {
"type": "integer"
},
"idp_sso_url": {
"type": "string",
"nullable": true
},
"idp_metadata": {
"type": "string",
"nullable": true
},
"sp_entity_id": {
"type": "string"
},
"idp_entity_id": {
"type": "string",
"nullable": true
},
"idp_certificate": {
"type": "string",
"nullable": true
},
"sp_metadata_url": {
"type": "string"
},
"allow_subdomains": {
"type": "boolean"
},
"idp_metadata_url": {
"type": "string",
"nullable": true
},
"attribute_mapping": {
"type": "object",
"properties": {
"user_id": {
"type": "string"
},
"last_name": {
"type": "string"
},
"first_name": {
"type": "string"
},
"email_address": {
"type": "string"
}
}
},
"allow_idp_initiated": {
"type": "boolean"
},
"sync_user_attributes": {
"type": "boolean"
}
}
}
SAMLConnections
{
"type": "object",
"required": [
"data",
"total_count"
],
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SAMLConnection"
}
},
"total_count": {
"type": "integer",
"format": "int64",
"description": "Total number of SAML Connections\n"
}
}
}
SamlConnectionsBetaCreateNewConnectionRequest
{
"type": "object",
"required": [
"name",
"domain",
"provider"
],
"properties": {
"name": {
"type": "string",
"description": "The name to use as a label for this SAML Connection"
},
"domain": {
"type": "string",
"description": "The domain of your organization. Sign in flows using an email with this domain, will use this SAML Connection."
},
"provider": {
"enum": [
"saml_custom",
"saml_okta",
"saml_google",
"saml_microsoft"
],
"type": "string",
"description": "The IdP provider of the connection."
},
"idp_sso_url": {
"type": "string",
"nullable": true,
"description": "The Single-Sign On URL as provided by the IdP"
},
"idp_metadata": {
"type": "string",
"nullable": true,
"description": "The XML content of the IdP metadata file. If present, it takes priority over the corresponding individual properties"
},
"idp_entity_id": {
"type": "string",
"nullable": true,
"description": "The Entity ID as provided by the IdP"
},
"idp_certificate": {
"type": "string",
"nullable": true,
"description": "The X.509 certificate as provided by the IdP"
},
"idp_metadata_url": {
"type": "string",
"nullable": true,
"description": "The URL which serves the IdP metadata. If present, it takes priority over the corresponding individual properties"
},
"attribute_mapping": {
"type": "object",
"nullable": true,
"properties": {
"user_id": {
"type": "string"
},
"last_name": {
"type": "string"
},
"first_name": {
"type": "string"
},
"email_address": {
"type": "string"
}
},
"description": "Define the attribute name mapping between Identity Provider and Clerk's user properties"
}
}
}
SamlConnectionsBetaUpdateConnectionByIdRequest
{
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true,
"description": "The name of the new SAML Connection"
},
"active": {
"type": "boolean",
"nullable": true,
"description": "Activate or de-activate the SAML Connection"
},
"domain": {
"type": "string",
"nullable": true,
"description": "The domain to use for the new SAML Connection"
},
"idp_sso_url": {
"type": "string",
"nullable": true,
"description": "The SSO url as provided by the IdP"
},
"idp_metadata": {
"type": "string",
"nullable": true,
"description": "The XML content of the IdP metadata file. If present, it takes priority over the corresponding individual properties"
},
"idp_entity_id": {
"type": "string",
"nullable": true,
"description": "The entity id as provided by the IdP"
},
"idp_certificate": {
"type": "string",
"nullable": true,
"description": "The x509 certificated as provided by the IdP"
},
"allow_subdomains": {
"type": "boolean",
"nullable": true,
"description": "Allow users with an email address subdomain to use this connection in order to authenticate"
},
"idp_metadata_url": {
"type": "string",
"nullable": true,
"description": "The URL which serves the IdP metadata. If present, it takes priority over the corresponding individual properties and replaces them"
},
"attribute_mapping": {
"type": "object",
"nullable": true,
"properties": {
"user_id": {
"type": "string"
},
"last_name": {
"type": "string"
},
"first_name": {
"type": "string"
},
"email_address": {
"type": "string"
}
},
"description": "Define the atrtibute name mapping between Identity Provider and Clerk's user properties"
},
"allow_idp_initiated": {
"type": "boolean",
"nullable": true,
"description": "Enable or deactivate IdP-initiated flows"
},
"sync_user_attributes": {
"type": "boolean",
"nullable": true,
"description": "Controls whether to update the user's attributes in each sign-in"
}
}
}
Session
{
"type": "object",
"required": [
"object",
"id",
"user_id",
"client_id",
"status",
"last_active_at",
"expire_at",
"abandon_at",
"updated_at",
"created_at"
],
"properties": {
"id": {
"type": "string"
},
"actor": {
"type": "object",
"nullable": true
},
"object": {
"enum": [
"session"
],
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.\n"
},
"status": {
"enum": [
"active",
"revoked",
"ended",
"expired",
"removed",
"abandoned",
"replaced"
],
"type": "string"
},
"user_id": {
"type": "string"
},
"client_id": {
"type": "string"
},
"expire_at": {
"type": "integer"
},
"abandon_at": {
"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"
},
"last_active_at": {
"type": "integer"
},
"last_active_organization_id": {
"type": "string",
"nullable": true
}
}
}
SessionsCreateSessionTokenFromTemplateResponse
{
"type": "object",
"properties": {
"jwt": {
"type": "string"
},
"object": {
"enum": [
"token"
],
"type": "string"
}
}
}
SessionsListSortedByCreationDateResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/Session"
}
}
SessionsVerifySessionRequest
{
"type": "object",
"properties": {
"token": {
"type": "string",
"description": "The JWT that is sent via the `__session` cookie from your frontend.\nNote: this JWT must be associated with the supplied session ID."
}
}
}
SignInToken
{
"type": "object",
"required": [
"object",
"id",
"user_id",
"status",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string",
"nullable": true
},
"token": {
"type": "string"
},
"object": {
"enum": [
"sign_in_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"
}
}
}
SignUp
{
"type": "object",
"required": [
"object",
"id",
"status",
"password_enabled",
"custom_action",
"abandon_at"
],
"properties": {
"id": {
"type": "string"
},
"object": {
"enum": [
"sign_up_attempt"
],
"type": "string"
},
"status": {
"enum": [
"missing_requirements",
"complete",
"abandoned"
],
"type": "string"
},
"username": {
"type": "string",
"nullable": true
},
"last_name": {
"type": "string",
"nullable": true
},
"abandon_at": {
"type": "integer"
},
"first_name": {
"type": "string",
"nullable": true
},
"external_id": {
"type": "string",
"nullable": true
},
"web3_wallet": {
"type": "string",
"nullable": true
},
"phone_number": {
"type": "string",
"nullable": true
},
"custom_action": {
"type": "boolean"
},
"email_address": {
"type": "string",
"nullable": true
},
"verifications": {
"type": "object"
},
"missing_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"created_user_id": {
"type": "string",
"nullable": true
},
"optional_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"public_metadata": {
"type": "object"
},
"required_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"unsafe_metadata": {
"type": "object"
},
"external_account": {
"type": "object"
},
"password_enabled": {
"type": "boolean"
},
"unverified_fields": {
"type": "array",
"items": {
"type": "string"
}
},
"created_session_id": {
"type": "string",
"nullable": true
}
}
}
SigninTokensCreateTokenRequest
{
"type": "object",
"properties": {
"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": 2592000,
"description": "Optional parameter to specify the life duration of the sign in token in seconds.\nBy default, the duration is 30 days."
}
}
}
SignupsUpdateSignUpByIdRequest
{
"type": "object",
"properties": {
"external_id": {
"type": "string",
"nullable": true,
"description": "The ID of the guest attempting to sign up as used in your external systems or your previous authentication solution.\nThis will be copied to the resulting user when the sign-up is completed."
},
"custom_action": {
"type": "boolean",
"description": "Specifies whether a custom action has run for this sign-up attempt.\nThis is important when your instance has been configured to require a custom action to run before converting a sign-up into a user.\nAfter executing any external business logic you deem necessary, you can mark the sign-up as ready-to-convert by setting `custom_action` to `true`."
}
}
}
SvixURL
{
"type": "object",
"required": [
"svix_url"
],
"properties": {
"svix_url": {
"type": "string"
}
}
}
Template
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"body": {
"type": "string",
"description": "the template body before variable interpolation"
},
"name": {
"type": "string",
"description": "user-friendly name of the template"
},
"slug": {
"type": "string",
"description": "machine-friendly name of the template"
},
"markup": {
"type": "string",
"description": "the editor markup used to generate the body of the template"
},
"object": {
"enum": [
"template"
],
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.\n"
},
"subject": {
"type": "string",
"nullable": true,
"description": "email subject"
},
"position": {
"type": "integer",
"description": "position with the listing of templates"
},
"can_delete": {
"type": "boolean",
"description": "whether this template can be deleted"
},
"can_revert": {
"type": "boolean",
"description": "whether this template can be reverted to the corresponding system default"
},
"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",
"nullable": true,
"description": "the id of the instance the template belongs to"
},
"resource_type": {
"type": "string",
"description": "whether this is a system (default) or user overridden) template"
},
"template_type": {
"type": "string",
"description": "whether this is an email or SMS template"
},
"from_email_name": {
"type": "string"
},
"delivered_by_clerk": {
"type": "boolean"
},
"required_variables": {
"type": "array",
"items": {
"type": "string"
},
"description": "list of variables that must be contained in the template body"
},
"available_variables": {
"type": "array",
"items": {
"type": "string"
},
"description": "list of variables that are available for use in the template body"
}
}
}
Ticket
{
"type": "object",
"required": [
"status",
"strategy"
],
"properties": {
"status": {
"enum": [
"unverified",
"verified",
"expired"
],
"type": "string"
},
"attempts": {
"type": "integer",
"nullable": true
},
"strategy": {
"enum": [
"ticket"
],
"type": "string"
},
"expire_at": {
"type": "integer",
"nullable": true
}
}
}
TotalCount
{
"type": "object",
"required": [
"object",
"total_count"
],
"properties": {
"object": {
"enum": [
"total_count"
],
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.\n"
},
"total_count": {
"type": "integer",
"format": "int64"
}
}
}
User
{
"type": "object",
"properties": {
"id": {
"type": "string"
},
"banned": {
"type": "boolean",
"description": "Flag to denote whether user is banned or not.\n"
},
"locked": {
"type": "boolean",
"description": "Flag to denote whether user is currently locked, i.e. restricted from signing in or not.\n"
},
"object": {
"enum": [
"user"
],
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.\n"
},
"passkeys": {
"type": "array",
"items": {
"$ref": "#/components/schemas/schemas-Passkey"
}
},
"username": {
"type": "string",
"nullable": true
},
"has_image": {
"type": "boolean"
},
"image_url": {
"type": "string"
},
"last_name": {
"type": "string",
"nullable": true
},
"created_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation.\n"
},
"first_name": {
"type": "string",
"nullable": true
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of last update.\n"
},
"external_id": {
"type": "string",
"nullable": true
},
"totp_enabled": {
"type": "boolean"
},
"web3_wallets": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Web3Wallet"
}
},
"phone_numbers": {
"type": "array",
"items": {
"$ref": "#/components/schemas/PhoneNumber"
}
},
"saml_accounts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SAMLAccount"
}
},
"last_active_at": {
"type": "integer",
"format": "int64",
"example": 1700690400000,
"nullable": true,
"description": "Unix timestamp of the latest session activity, with day precision.\n"
},
"email_addresses": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EmailAddress"
}
},
"last_sign_in_at": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "Unix timestamp of last sign-in.\n"
},
"public_metadata": {
"type": "object"
},
"unsafe_metadata": {
"type": "object"
},
"password_enabled": {
"type": "boolean"
},
"private_metadata": {
"type": "object",
"nullable": true
},
"external_accounts": {
"type": "array",
"items": {
"type": "object"
}
},
"profile_image_url": {
"type": "string",
"deprecated": true
},
"two_factor_enabled": {
"type": "boolean"
},
"backup_code_enabled": {
"type": "boolean"
},
"delete_self_enabled": {
"type": "boolean",
"description": "If enabled, user can delete themselves via FAPI.\n"
},
"primary_web3_wallet_id": {
"type": "string",
"nullable": true
},
"primary_phone_number_id": {
"type": "string",
"nullable": true
},
"primary_email_address_id": {
"type": "string",
"nullable": true
},
"lockout_expires_in_seconds": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "The number of seconds remaining until the lockout period expires for a locked user. A null value for a locked user indicates that lockout never expires.\n"
},
"create_organization_enabled": {
"type": "boolean",
"description": "If enabled, user can create organizations via FAPI.\n"
},
"verification_attempts_remaining": {
"type": "integer",
"format": "int64",
"nullable": true,
"description": "The number of verification attempts remaining until the user is locked. Null if account lockout is not enabled. Note: if a user is locked explicitly via the Backend API, they may still have verification attempts remaining.\n"
}
}
}
UsersCreateNewUserRequest
{
"type": "object",
"properties": {
"password": {
"type": "string",
"nullable": true,
"description": "The plaintext password to give the user.\nMust be at least 8 characters long, and can not be in any list of hacked passwords."
},
"username": {
"type": "string",
"nullable": true,
"description": "The username to give to the user.\nIt must be unique across your instance."
},
"last_name": {
"type": "string",
"nullable": true,
"description": "The last name to assign to the user"
},
"created_at": {
"type": "string",
"description": "A custom date/time denoting _when_ the user signed up to the application, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`)."
},
"first_name": {
"type": "string",
"nullable": true,
"description": "The first name to assign to the user"
},
"external_id": {
"type": "string",
"nullable": true,
"description": "The ID of the user as used in your external systems or your previous authentication solution.\nMust be unique across your instance."
},
"totp_secret": {
"type": "string",
"description": "In case TOTP is configured on the instance, you can provide the secret to enable it on the newly created user without the need to reset it.\nPlease note that currently the supported options are:\n* Period: 30 seconds\n* Code length: 6 digits\n* Algorithm: SHA1"
},
"web3_wallet": {
"type": "array",
"items": {
"type": "string"
},
"description": "Web3 wallets to add to the user.\nMust be unique across your instance.\nThe first wallet will be set as the user's primary wallet."
},
"backup_codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "If Backup Codes are configured on the instance, you can provide them to enable it on the newly created user without the need to reset them.\nYou must provide the backup codes in plain format or the corresponding bcrypt digest."
},
"phone_number": {
"type": "array",
"items": {
"type": "string"
},
"description": "Phone numbers to add to the user.\nMust be unique across your instance.\nThe first phone number will be set as the user's primary phone number."
},
"email_address": {
"type": "array",
"items": {
"type": "string"
},
"description": "Email addresses to add to the user.\nMust be unique across your instance.\nThe first email address will be set as the user's primary email address."
},
"password_digest": {
"type": "string",
"description": "In case you already have the password digests and not the passwords, you can use them for the newly created user via this property.\nThe digests should be generated with one of the supported algorithms.\nThe hashing algorithm can be specified using the `password_hasher` property."
},
"password_hasher": {
"enum": [
"argon2i",
"argon2id",
"bcrypt",
"bcrypt_sha256_django",
"md5",
"pbkdf2_sha256",
"pbkdf2_sha256_django",
"pbkdf2_sha1",
"phpass",
"scrypt_firebase",
"scrypt_werkzeug",
"sha256"
],
"type": "string",
"description": "The hashing algorithm that was used to generate the password digest.\nThe algorithms we support at the moment are [bcrypt](https://en.wikipedia.org/wiki/Bcrypt), [bcrypt_sha256_django](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/),\n[md5](https://en.wikipedia.org/wiki/MD5), pbkdf2_sha256, [pbkdf2_sha256_django](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/),\n[phpass](https://www.openwall.com/phpass/), [scrypt_firebase](https://firebaseopensource.com/projects/firebase/scrypt/),\n[scrypt_werkzeug](https://werkzeug.palletsprojects.com/en/3.0.x/utils/#werkzeug.security.generate_password_hash), [sha256](https://en.wikipedia.org/wiki/SHA-2)\nand the [argon2](https://argon2.online/) variants argon2i and argon2id.\n\nIf you need support for any particular hashing algorithm, [please let us know](https://clerk.com/support).\n\nNote: for password hashers considered insecure (at this moment MD5 and SHA256), the corresponding user password hashes will be transparently migrated to Bcrypt (a secure hasher) upon the user's first successful password sign in.\nInsecure schemes are marked with `(insecure)` in the list below.\n\nEach of the supported hashers expects the incoming digest to be in a particular format. Specifically:\n\n**bcrypt:** The digest should be of the following form:\n\n`$<algorithm version>$<cost>$<salt & hash>`\n\n**bcrypt_sha256_django:** This is the Django-specific variant of Bcrypt, using SHA256 hashing function. The format should be as follows (as exported from Django):\n\n`bcrypt_sha256$$<algorithm version>$<cost>$<salt & hash>`\n\n**md5** (insecure): The digest should follow the regular form e.g.:\n\n`5f4dcc3b5aa765d61d8327deb882cf99`\n\n**pbkdf2_sha256:** This is the PBKDF2 algorithm using the SHA256 hashing function. The format should be as follows:\n\n`pbkdf2_sha256$<iterations>$<salt>$<hash>`\n\nNote: Both the salt and the hash are expected to be base64-encoded.\n\n**pbkdf2_sha256_django:** This is the Django-specific variant of PBKDF2 and the digest should have the following format (as exported from Django):\n\n`pbkdf2_sha256$<iterations>$<salt>$<hash>`\n\nNote: The salt is expected to be un-encoded, the hash is expected base64-encoded.\n\n**pbkdf2_sha1:** This is similar to pkbdf2_sha256_django, but with two differences:\n1. uses sha1 instead of sha256\n2. accepts the hash as a hex-encoded string\n\nThe format is the following:\n\n`pbkdf2_sha1$<iterations>$<salt>$<hash-as-hex-string>`\n\n**phpass:** Portable public domain password hashing framework for use in PHP applications. Digests hashed with phpass have the following sections:\n\nThe format is the following:\n\n`$P$<rounds><salt><encoded-checksum>`\n\n- $P$ is the prefix used to identify phpass hashes.\n- rounds is a single character encoding a 6-bit integer representing the number of rounds used.\n- salt is eight characters drawn from [./0-9A-Za-z], providing a 48-bit salt.\n- checksum is 22 characters drawn from the same set, encoding the 128-bit checksum with MD5.\n\n**scrypt_firebase:** The Firebase-specific variant of scrypt.\nThe value is expected to have 6 segments separated by the $ character and include the following information:\n\n_hash:_ The actual Base64 hash. This can be retrieved when exporting the user from Firebase.\n_salt:_ The salt used to generate the above hash. Again, this is given when exporting the user.\n_signer key:_ The base64 encoded signer key.\n_salt separator:_ The base64 encoded salt separator.\n_rounds:_ The number of rounds the algorithm needs to run.\n_memory cost:_ The cost of the algorithm run\n\nThe first 2 (hash and salt) are per user and can be retrieved when exporting the user from Firebase.\nThe other 4 values (signer key, salt separator, rounds and memory cost) are project-wide settings and can be retrieved from the project's password hash parameters.\n\nOnce you have all these, you can combine it in the following format and send this as the digest in order for Clerk to accept it:\n\n`<hash>$<salt>$<signer key>$<salt separator>$<rounds>$<memory cost>`\n\n**scrypt_werkzeug:** The Werkzeug-specific variant of scrypt.\n\n The value is expected to have 3 segments separated by the $ character and include the following information:\n\n _algorithm args:_ The algorithm used to generate the hash.\n _salt:_ The salt used to generate the above hash.\n _hash:_ The actual Base64 hash.\n\n The algorithm args are the parameters used to generate the hash and are included in the digest.\n\n**argon2i:** Algorithms in the argon2 family generate digests that encode the following information:\n\n_version (v):_ The argon version, version 19 is assumed\n_memory (m):_ The memory used by the algorithm (in kibibytes)\n_iterations (t):_ The number of iterations to perform\n_parallelism (p):_ The number of threads to use\n\nParts are demarcated by the `$` character, with the first part identifying the algorithm variant.\nThe middle part is a comma-separated list of the encoding options (memory, iterations, parallelism).\nThe final part is the actual digest.\n\n`$argon2i$v=19$m=4096,t=3,p=1$4t6CL3P7YiHBtwESXawI8Hm20zJj4cs7/4/G3c187e0$m7RQFczcKr5bIR0IIxbpO2P0tyrLjf3eUW3M3QSwnLc`\n\n**argon2id:** See the previous algorithm for an explanation of the formatting.\n\nFor the argon2id case, the value of the algorithm in the first part of the digest is `argon2id`:\n\n`$argon2id$v=19$m=64,t=4,p=8$Z2liZXJyaXNo$iGXEpMBTDYQ8G/71tF0qGjxRHEmR3gpGULcE93zUJVU`\n\n**sha256** (insecure): The digest should be a 64-length hex string, e.g.:\n\n`9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08`"
},
"public_metadata": {
"type": "object",
"description": "Metadata saved on the user, that is visible to both your Frontend and Backend APIs"
},
"unsafe_metadata": {
"type": "object",
"description": "Metadata saved on the user, that can be updated from both the Frontend and Backend APIs.\nNote: Since this data can be modified from the frontend, it is not guaranteed to be safe."
},
"private_metadata": {
"type": "object",
"description": "Metadata saved on the user, that is only visible to your Backend API"
},
"skip_password_checks": {
"type": "boolean",
"description": "When set to `true` all password checks are skipped.\nIt is recommended to use this method only when migrating plaintext passwords to Clerk.\nUpon migration the user base should be prompted to pick stronger password."
},
"skip_password_requirement": {
"type": "boolean",
"description": "When set to `true`, `password` is not required anymore when creating the user and can be omitted.\nThis is useful when you are trying to create a user that doesn't have a password, in an instance that is using passwords.\nPlease note that you cannot use this flag if password is the only way for a user to sign into your instance."
}
}
}
UsersDisableMfaResponse
{
"type": "object",
"properties": {
"user_id": {
"type": "string",
"nullable": false
}
}
}
UsersGetOAuthAccessTokenResponse
{
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"nullable": true
},
"token": {
"type": "string",
"description": "The access token"
},
"object": {
"type": "string"
},
"scopes": {
"type": "array",
"items": {
"type": "string"
},
"description": "The list of scopes that the token is valid for.\nOnly present for OAuth 2.0 tokens."
},
"provider": {
"type": "string",
"description": "The ID of the provider"
},
"token_secret": {
"type": "string",
"description": "The token secret. Only present for OAuth 1.0 tokens."
},
"public_metadata": {
"type": "object"
},
"external_account_id": {
"type": "string",
"description": "External account ID"
}
}
}
}
UsersListSortedByCreationDateResponse
{
"type": "array",
"items": {
"$ref": "#/components/schemas/User"
}
}
UsersMergeUserMetadataAttributesRequest
{
"type": "object",
"properties": {
"public_metadata": {
"type": "object",
"description": "Metadata saved on the user, that is visible to both your frontend and backend.\nThe new object will be merged with the existing value."
},
"unsafe_metadata": {
"type": "object",
"description": "Metadata saved on the user, that can be updated from both the Frontend and Backend APIs.\nThe new object will be merged with the existing value.\n\nNote: Since this data can be modified from the frontend, it is not guaranteed to be safe."
},
"private_metadata": {
"type": "object",
"description": "Metadata saved on the user that is only visible to your backend.\nThe new object will be merged with the existing value."
}
}
}
UsersSetProfileImageRequest
{
"type": "object",
"properties": {
"file": {
"type": "string",
"format": "binary"
}
}
}
UsersUpdateUserAttributesRequest
{
"type": "object",
"properties": {
"password": {
"type": "string",
"nullable": true,
"description": "The plaintext password to give the user.\nMust be at least 8 characters long, and can not be in any list of hacked passwords."
},
"username": {
"type": "string",
"nullable": true,
"description": "The username to give to the user.\nIt must be unique across your instance."
},
"last_name": {
"type": "string",
"nullable": true,
"description": "The last name to assign to the user"
},
"created_at": {
"type": "string",
"description": "A custom date/time denoting _when_ the user signed up to the application, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`)."
},
"first_name": {
"type": "string",
"nullable": true,
"description": "The first name to assign to the user"
},
"external_id": {
"type": "string",
"nullable": true,
"description": "The ID of the user as used in your external systems or your previous authentication solution.\nMust be unique across your instance."
},
"totp_secret": {
"type": "string",
"description": "In case TOTP is configured on the instance, you can provide the secret to enable it on the specific user without the need to reset it.\nPlease note that currently the supported options are:\n* Period: 30 seconds\n* Code length: 6 digits\n* Algorithm: SHA1"
},
"backup_codes": {
"type": "array",
"items": {
"type": "string"
},
"description": "If Backup Codes are configured on the instance, you can provide them to enable it on the specific user without the need to reset them.\nYou must provide the backup codes in plain format or the corresponding bcrypt digest."
},
"password_digest": {
"type": "string",
"description": "In case you already have the password digests and not the passwords, you can use them for the newly created user via this property.\nThe digests should be generated with one of the supported algorithms.\nThe hashing algorithm can be specified using the `password_hasher` property."
},
"password_hasher": {
"enum": [
"argon2i",
"argon2id",
"bcrypt",
"bcrypt_sha256_django",
"md5",
"pbkdf2_sha256",
"pbkdf2_sha256_django",
"pbkdf2_sha1",
"phpass",
"scrypt_firebase",
"scrypt_werkzeug",
"sha256"
],
"type": "string",
"description": "The hashing algorithm that was used to generate the password digest.\nThe algorithms we support at the moment are [bcrypt](https://en.wikipedia.org/wiki/Bcrypt), [bcrypt_sha256_django](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/),\n[md5](https://en.wikipedia.org/wiki/MD5), pbkdf2_sha256, [pbkdf2_sha256_django](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/),\n[phpass](https://www.openwall.com/phpass/), [scrypt_firebase](https://firebaseopensource.com/projects/firebase/scrypt/),\n[sha256](https://en.wikipedia.org/wiki/SHA-2), [scrypt_werkzeug](https://werkzeug.palletsprojects.com/en/3.0.x/utils/#werkzeug.security.generate_password_hash)\nand the [argon2](https://argon2.online/) variants argon2i and argon2id.\n\nIf you need support for any particular hashing algorithm, [please let us know](https://clerk.com/support).\n\nNote: for password hashers considered insecure (at this moment MD5 and SHA256), the corresponding user password hashes will be transparently migrated to Bcrypt (a secure hasher) upon the user's first successful password sign in.\nInsecure schemes are marked with `(insecure)` in the list below.\n\nEach of the supported hashers expects the incoming digest to be in a particular format. Specifically:\n\n**bcrypt:** The digest should be of the following form:\n\n`$<algorithm version>$<cost>$<salt & hash>`\n\n**bcrypt_sha256_django:** This is the Django-specific variant of Bcrypt, using SHA256 hashing function. The format should be as follows (as exported from Django):\n\n`bcrypt_sha256$$<algorithm version>$<cost>$<salt & hash>`\n\n**md5** (insecure): The digest should follow the regular form e.g.:\n\n`5f4dcc3b5aa765d61d8327deb882cf99`\n\n**pbkdf2_sha256:** This is the PBKDF2 algorithm using the SHA256 hashing function. The format should be as follows:\n\n`pbkdf2_sha256$<iterations>$<salt>$<hash>`\n\nNote: Both the salt and the hash are expected to be base64-encoded.\n\n**pbkdf2_sha256_django:** This is the Django-specific variant of PBKDF2 and the digest should have the following format (as exported from Django):\n\n`pbkdf2_sha256$<iterations>$<salt>$<hash>`\n\nNote: The salt is expected to be un-encoded, the hash is expected base64-encoded.\n\n**pbkdf2_sha1:** This is similar to pkbdf2_sha256_django, but with two differences:\n1. uses sha1 instead of sha256\n2. accepts the hash as a hex-encoded string\n\nThe format is the following:\n\n`pbkdf2_sha1$<iterations>$<salt>$<hash-as-hex-string>`\n\n**phpass:** Portable public domain password hashing framework for use in PHP applications. Digests hashed with phpass have the following sections:\n\nThe format is the following:\n\n`$P$<rounds><salt><encoded-checksum>`\n\n- $P$ is the prefix used to identify phpass hashes.\n- rounds is a single character encoding a 6-bit integer representing the number of rounds used.\n- salt is eight characters drawn from [./0-9A-Za-z], providing a 48-bit salt.\n- checksum is 22 characters drawn from the same set, encoding the 128-bit checksum with MD5.\n\n**scrypt_firebase:** The Firebase-specific variant of scrypt.\nThe value is expected to have 6 segments separated by the $ character and include the following information:\n\n_hash:_ The actual Base64 hash. This can be retrieved when exporting the user from Firebase.\n_salt:_ The salt used to generate the above hash. Again, this is given when exporting the user.\n_signer key:_ The base64 encoded signer key.\n_salt separator:_ The base64 encoded salt separator.\n_rounds:_ The number of rounds the algorithm needs to run.\n_memory cost:_ The cost of the algorithm run\n\nThe first 2 (hash and salt) are per user and can be retrieved when exporting the user from Firebase.\nThe other 4 values (signer key, salt separator, rounds and memory cost) are project-wide settings and can be retrieved from the project's password hash parameters.\n\nOnce you have all these, you can combine it in the following format and send this as the digest in order for Clerk to accept it:\n\n`<hash>$<salt>$<signer key>$<salt separator>$<rounds>$<memory cost>`\n\n**scrypt_werkzeug:** The Werkzeug-specific variant of scrypt.\n\nThe value is expected to have 3 segments separated by the $ character and include the following information:\n\n_algorithm args:_ The algorithm used to generate the hash.\n_salt:_ The salt used to generate the above hash.\n_hash:_ The actual Base64 hash.\n\nThe algorithm args are the parameters used to generate the hash and are included in the digest.\n\n**argon2i:** Algorithms in the argon2 family generate digests that encode the following information:\n\n_version (v):_ The argon version, version 19 is assumed\n_memory (m):_ The memory used by the algorithm (in kibibytes)\n_iterations (t):_ The number of iterations to perform\n_parallelism (p):_ The number of threads to use\n\nParts are demarcated by the `$` character, with the first part identifying the algorithm variant.\nThe middle part is a comma-separated list of the encoding options (memory, iterations, parallelism).\nThe final part is the actual digest.\n\n`$argon2i$v=19$m=4096,t=3,p=1$4t6CL3P7YiHBtwESXawI8Hm20zJj4cs7/4/G3c187e0$m7RQFczcKr5bIR0IIxbpO2P0tyrLjf3eUW3M3QSwnLc`\n\n**argon2id:** See the previous algorithm for an explanation of the formatting.\n\nFor the argon2id case, the value of the algorithm in the first part of the digest is `argon2id`:\n\n`$argon2id$v=19$m=64,t=4,p=8$Z2liZXJyaXNo$iGXEpMBTDYQ8G/71tF0qGjxRHEmR3gpGULcE93zUJVU`\n\n**sha256** (insecure): The digest should be a 64-length hex string, e.g.:\n\n`9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08`"
},
"public_metadata": {
"type": "object",
"description": "Metadata saved on the user, that is visible to both your Frontend and Backend APIs"
},
"unsafe_metadata": {
"type": "object",
"description": "Metadata saved on the user, that can be updated from both the Frontend and Backend APIs.\nNote: Since this data can be modified from the frontend, it is not guaranteed to be safe."
},
"private_metadata": {
"type": "object",
"description": "Metadata saved on the user, that is only visible to your Backend API"
},
"profile_image_id": {
"type": "string",
"nullable": true,
"description": "The ID of the image to set as the user's profile image"
},
"delete_self_enabled": {
"type": "boolean",
"nullable": true,
"description": "If true, the user can delete themselves with the Frontend API."
},
"skip_password_checks": {
"type": "boolean",
"nullable": true,
"description": "Set it to `true` if you're updating the user's password and want to skip any password policy settings check. This parameter can only be used when providing a `password`."
},
"primary_web3_wallet_id": {
"type": "string",
"description": "The ID of the web3 wallets to set as primary.\nIt must be verified, and present on the current user."
},
"primary_phone_number_id": {
"type": "string",
"description": "The ID of the phone number to set as primary.\nIt must be verified, and present on the current user."
},
"primary_email_address_id": {
"type": "string",
"description": "The ID of the email address to set as primary.\nIt must be verified, and present on the current user."
},
"sign_out_of_other_sessions": {
"type": "boolean",
"nullable": true,
"description": "Set to `true` to sign out the user from all their active sessions once their password is updated. This parameter can only be used when providing a `password`."
},
"create_organization_enabled": {
"type": "boolean",
"nullable": true,
"description": "If true, the user can create organizations with the Frontend API."
},
"notify_primary_email_address_changed": {
"type": "boolean",
"default": false,
"description": "If set to `true`, the user will be notified that their primary email address has changed.\nBy default, no notification is sent."
}
}
}
UsersVerifyPasswordRequest
{
"type": "object",
"required": [
"password"
],
"properties": {
"password": {
"type": "string",
"description": "The user password to verify"
}
}
}
UsersVerifyPasswordResponse
{
"type": "object",
"properties": {
"verified": {
"type": "boolean",
"nullable": false
}
}
}
UsersVerifyTotpRequest
{
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "string",
"description": "The TOTP or backup code to verify"
}
}
}
UsersVerifyTotpResponse
{
"type": "object",
"properties": {
"verified": {
"type": "boolean",
"nullable": false
},
"code_type": {
"enum": [
"totp",
"backup_code"
],
"type": "string",
"nullable": false
}
}
}
Web3Signature
{
"type": "object",
"required": [
"status",
"strategy",
"nonce"
],
"properties": {
"nonce": {
"enum": [
"nonce"
],
"type": "string"
},
"status": {
"enum": [
"verified"
],
"type": "string"
},
"attempts": {
"type": "integer",
"nullable": true
},
"strategy": {
"enum": [
"web3_metamask_signature"
],
"type": "string"
},
"expire_at": {
"type": "integer",
"nullable": true
}
}
}
Web3Wallet
{
"type": "object",
"required": [
"object",
"web3_wallet",
"verification",
"created_at",
"updated_at"
],
"properties": {
"id": {
"type": "string"
},
"object": {
"enum": [
"web3_wallet"
],
"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"
},
"updated_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of creation\n"
},
"web3_wallet": {
"type": "string"
},
"verification": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/Web3Signature"
},
{
"$ref": "#/components/schemas/Admin"
}
],
"nullable": true
}
}
}
schemas-Passkey
{
"type": "object",
"required": [
"object",
"name",
"last_used_at",
"verification"
],
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"object": {
"enum": [
"web3_wallet"
],
"type": "string",
"description": "String representing the object's type. Objects of the same type share the same value.\n"
},
"last_used_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp of when the passkey was last used.\n"
},
"verification": {
"type": "object",
"oneOf": [
{
"$ref": "#/components/schemas/Passkey"
}
],
"nullable": true
}
}
}