--- openapi: 3.0.3 info: title: Clerk Backend API x-logo: url: https://clerk.com/_next/image?url=%2Fimages%2Fclerk-logo.svg&w=96&q=75 altText: Clerk docs href: https://clerk.com/docs contact: email: support@clerk.com name: Clerk Platform Team url: https://clerk.com/support description: The Clerk REST Backend API, meant to be accessed by backend servers. Please see https://clerk.com/docs for more information. version: v1 termsOfService: https://clerk.com/terms license: name: MIT url: https://github.com/clerkinc/clerk-sdk-go/blob/main/LICENSE externalDocs: url: https://clerk.com/docs servers: - url: https://api.clerk.dev/v1 - url: https://api.clerk.com/v1 security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer parameters: LimitParameter: name: limit in: query description: |- Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`. Must be an integer greater than zero and less than 500. By default, if not supplied, a limit of 10 is used. required: false schema: type: number default: 10 minimum: 1 maximum: 500 OffsetParameter: name: offset in: query description: |- Skip the first `offset` results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with `limit`. required: false schema: type: number default: 0 minimum: 0 schemas: Session: type: object additionalProperties: false properties: object: type: string description: "String representing the object's type. Objects of the same type share the same value. " enum: - session id: type: string user_id: type: string client_id: type: string actor: type: object nullable: true status: type: string enum: - active - revoked - ended - expired - removed - abandoned last_active_organization_id: type: string nullable: true last_active_at: type: integer expire_at: type: integer abandon_at: type: integer updated_at: type: integer format: int64 description: "Unix timestamp of last update. " created_at: type: integer format: int64 description: "Unix timestamp of creation. " required: - object - id - user_id - client_id - status - last_active_at - expire_at - abandon_at - updated_at - created_at Client: type: object additionalProperties: false properties: object: type: string description: "String representing the object's type. Objects of the same type share the same value. " enum: - client id: type: string description: "String representing the identifier of the session. " session_ids: type: array items: type: string sessions: type: array items: "$ref": "#/components/schemas/Session" sign_in_attempt_id: type: string nullable: true deprecated: true sign_up_attempt_id: type: string nullable: true deprecated: true sign_in_id: type: string nullable: true sign_up_id: type: string nullable: true last_active_session_id: nullable: true type: string description: "Last active session_id. " updated_at: type: integer format: int64 description: "Unix timestamp of last update. " created_at: type: integer format: int64 description: "Unix timestamp of creation. " required: - object - id - session_ids - sessions - sign_in_attempt_id - sign_up_attempt_id - sign_in_id - sign_up_id - last_active_session_id - updated_at - created_at ClerkError: type: object properties: message: type: string long_message: type: string code: type: string meta: type: object required: - message - long_message - code ClerkErrors: type: object properties: errors: type: array items: "$ref": "#/components/schemas/ClerkError" meta: type: object required: - errors OTP: type: object additionalProperties: false properties: status: type: string enum: - unverified - verified - failed - expired strategy: type: string enum: - phone_code - email_code attempts: type: integer expire_at: type: integer required: - status - attempts - strategy - expire_at Admin: type: object additionalProperties: false properties: status: type: string enum: - verified strategy: type: string enum: - admin attempts: type: integer nullable: true expire_at: type: integer nullable: true required: - status - strategy IdentificationLink: type: object additionalProperties: false properties: type: type: string enum: - oauth_google - oauth_mock id: type: string required: - type - id EmailAddress: type: object additionalProperties: false properties: id: type: string object: type: string description: "String representing the object's type. Objects of the same type share the same value. " enum: - email_address email_address: type: string reserved: type: boolean verification: type: object nullable: true oneOf: - "$ref": "#/components/schemas/OTP" - "$ref": "#/components/schemas/Admin" linked_to: type: array items: "$ref": "#/components/schemas/IdentificationLink" required: - object - email_address - verification - linked_to - reserved DeletedObject: type: object additionalProperties: false properties: object: type: string id: type: string slug: type: string deleted: type: boolean required: - object - deleted PhoneNumber: type: object additionalProperties: false properties: id: type: string object: type: string description: "String representing the object's type. Objects of the same type share the same value. " enum: - phone_number phone_number: type: string reserved_for_second_factor: type: boolean default_second_factor: type: boolean reserved: type: boolean verification: type: object nullable: true oneOf: - "$ref": "#/components/schemas/OTP" - "$ref": "#/components/schemas/Admin" linked_to: type: array items: "$ref": "#/components/schemas/IdentificationLink" backup_codes: type: array items: type: string nullable: true required: - object - phone_number - verification - linked_to - reserved Template: type: object additionalProperties: false properties: id: type: string object: type: string description: "String representing the object's type. Objects of the same type share the same value. " enum: - template instance_id: nullable: true type: string 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 name: type: string description: user-friendly name of the template slug: type: string description: machine-friendly name of the template position: type: integer description: position with the listing of templates can_revert: type: boolean description: whether this template can be reverted to the corresponding system default can_delete: type: boolean description: whether this template can be deleted subject: type: string description: email subject nullable: true markup: type: string description: the editor markup used to generate the body of the template body: type: string description: the template body before variable interpolation available_variables: type: array description: list of variables that are available for use in the template body items: type: string required_variables: type: array description: list of variables that must be contained in the template body items: type: string from_email_name: type: string delivered_by_clerk: type: boolean updated_at: type: integer format: int64 description: "Unix timestamp of last update. " created_at: type: integer format: int64 description: "Unix timestamp of creation. " Web3Signature: type: object additionalProperties: false properties: status: type: string enum: - verified strategy: type: string enum: - web3_metamask_signature nonce: type: string enum: - nonce attempts: type: integer nullable: true expire_at: type: integer nullable: true required: - status - strategy - nonce Web3Wallet: type: object additionalProperties: false properties: id: type: string object: type: string description: "String representing the object's type. Objects of the same type share the same value. " enum: - web3_wallet web3_wallet: type: string verification: type: object nullable: true oneOf: - "$ref": "#/components/schemas/Web3Signature" - "$ref": "#/components/schemas/Admin" required: - object - web3_wallet - verification User: type: object additionalProperties: false properties: id: type: string object: type: string description: "String representing the object's type. Objects of the same type share the same value. " enum: - user external_id: nullable: true type: string primary_email_address_id: nullable: true type: string primary_phone_number_id: nullable: true type: string primary_web3_wallet_id: nullable: true type: string username: nullable: true type: string first_name: nullable: true type: string last_name: nullable: true type: string profile_image_url: type: string deprecated: true image_url: type: string public_metadata: type: object private_metadata: nullable: true type: object unsafe_metadata: type: object gender: nullable: true type: string birthday: nullable: true type: string email_addresses: type: array items: "$ref": "#/components/schemas/EmailAddress" phone_numbers: type: array items: "$ref": "#/components/schemas/PhoneNumber" web3_wallets: type: array items: "$ref": "#/components/schemas/Web3Wallet" password_enabled: type: boolean two_factor_enabled: type: boolean totp_enabled: type: boolean backup_code_enabled: type: boolean external_accounts: type: array items: type: object last_sign_in_at: type: integer format: int64 nullable: true description: "Unix timestamp of last sign-in. " banned: type: boolean description: "Flag to denote whether user is banned or not. " updated_at: type: integer format: int64 description: "Unix timestamp of last update. " created_at: type: integer format: int64 description: "Unix timestamp of creation. " TotalCount: type: object additionalProperties: false properties: object: type: string description: "String representing the object's type. Objects of the same type share the same value. " enum: - total_count total_count: type: integer format: int64 required: - object - total_count Organization: type: object properties: object: type: string enum: - organization id: type: string name: type: string slug: type: string members_count: type: integer nullable: true max_allowed_memberships: type: integer public_metadata: type: object private_metadata: type: object created_by: 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. " required: - object - id - name - slug - max_allowed_memberships - public_metadata - private_metadata - created_at - updated_at OrganizationMembership: description: Hello world type: object properties: id: type: string object: type: string description: "String representing the object's type. Objects of the same type share the same value. " enum: - organization_membership role: type: string enum: - admin - basic_member created_at: type: integer format: int64 description: Unix timestamp of creation. updated_at: type: integer format: int64 description: Unix timestamp of last update. organization: type: object nullable: false allOf: - "$ref": "#/components/schemas/Organization" public_user_data: type: object additionalProperties: false properties: user_id: type: string nullable: false first_name: type: string nullable: true last_name: type: string nullable: true profile_image_url: type: string nullable: true deprecated: true image_url: type: string nullable: true identifier: type: string nullable: true OrganizationMemberships: type: object additionalProperties: false properties: data: type: array items: "$ref": "#/components/schemas/OrganizationMembership" total_count: type: integer format: int64 description: "Total number of organization memberships " required: - data - total_count Email: type: object additionalProperties: false properties: object: type: string enum: - email id: type: string slug: type: string nullable: true from_email_name: type: string email_address_id: type: string nullable: true to_email_address: type: string user_id: type: string nullable: true subject: type: string body: type: string body_plain: type: string nullable: true status: type: string data: type: object nullable: true delivered_by_clerk: type: boolean required: - object - id - from_email_name - email_address_id - to_email_address - subject - body - status - delivered_by_clerk SMSMessage: type: object additionalProperties: false properties: object: type: string enum: - sms_message id: type: string slug: type: string nullable: true from_phone_number: type: string to_phone_number: type: string phone_number_id: type: string nullable: true user_id: type: string nullable: true message: type: string status: type: string data: type: object nullable: true delivered_by_clerk: type: boolean required: - object - id - from_phone_number - to_phone_number - phone_number_id - message - status - delivered_by_clerk Invitation: type: object additionalProperties: false properties: object: type: string enum: - invitation id: type: string email_address: type: string format: email public_metadata: type: object revoked: type: boolean example: true status: type: string enum: - pending - accepted - revoked example: revoked created_at: type: integer format: int64 description: "Unix timestamp of creation. " updated_at: type: integer format: int64 description: "Unix timestamp of last update. " required: - object - id - email_address - status - created_at - updated_at AllowlistIdentifier: type: object additionalProperties: false properties: object: type: string description: "String representing the object's type. Objects of the same type share the same value. " enum: - allowlist_identifier id: type: string invitation_id: type: string identifier: type: string description: "An email address or a phone number. " identifier_type: type: string enum: - email_address - phone_number - web3_wallet instance_id: 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. " BlocklistIdentifier: type: object additionalProperties: false properties: object: type: string description: "String representing the object's type. Objects of the same type share the same value. " enum: - blocklist_identifier id: type: string identifier: type: string description: "An email address, email domain, phone number or web3 wallet. " identifier_type: type: string enum: - email_address - phone_number - web3_wallet instance_id: 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. " BlocklistIdentifiers: type: object additionalProperties: false properties: data: type: array items: "$ref": "#/components/schemas/BlocklistIdentifier" total_count: type: integer format: int64 description: "Total number of blocklist identifiers " required: - data - total_count ActorToken: type: object additionalProperties: false properties: object: type: string enum: - actor_token id: type: string status: type: string enum: - pending - accepted - revoked user_id: type: string actor: type: object token: type: string nullable: true url: type: string nullable: true created_at: type: integer format: int64 description: "Unix timestamp of creation. " updated_at: type: integer format: int64 description: "Unix timestamp of last update. " required: - object - id - user_id - actor - status - created_at - updated_at InstanceRestrictions: type: object properties: object: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - instance_restrictions allowlist: type: boolean blocklist: type: boolean OrganizationSettings: type: object properties: object: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - organization_settings enabled: type: boolean max_allowed_memberships: type: integer required: - object - enabled - max_allowed_memberships SvixURL: type: object additionalProperties: false properties: svix_url: type: string required: - svix_url JWTTemplate: type: object additionalProperties: false properties: object: type: string enum: - jwt_template id: type: string name: type: string claims: type: object lifetime: type: integer allowed_clock_skew: type: integer custom_signing_key: type: boolean signing_algorithm: 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. " required: - object - id - name - claims - lifetime - allowed_clock_skew - created_at - updated_at Organizations: type: object additionalProperties: false properties: data: type: array items: "$ref": "#/components/schemas/Organization" total_count: type: integer format: int64 description: "Total number of organizations " required: - data - total_count OrganizationWithLogo: type: object allOf: - "$ref": "#/components/schemas/Organization" - type: object properties: logo_url: type: string deprecated: true image_url: type: string required: - logo_url - image_url OrganizationInvitation: description: An organization invitation type: object properties: id: type: string object: type: string description: "String representing the object's type. Objects of the same type share the same value. " enum: - organization_invitation email_address: type: string role: type: string enum: - admin - basic_member organization_id: type: string 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. OrganizationInvitations: type: object additionalProperties: false properties: data: type: array items: "$ref": "#/components/schemas/OrganizationInvitation" total_count: type: integer format: int64 description: "Total number of organization invitations " required: - data - total_count RedirectURL: type: object additionalProperties: false properties: object: type: string enum: - redirect_url id: type: string url: 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. " required: - object - id - url - created_at - updated_at SignInToken: type: object additionalProperties: false properties: object: type: string enum: - sign_in_token id: type: string status: type: string enum: - pending - accepted - revoked user_id: type: string token: type: string url: type: string nullable: true created_at: type: integer format: int64 description: "Unix timestamp of creation. " updated_at: type: integer format: int64 description: "Unix timestamp of last update. " required: - object - id - user_id - status - created_at - updated_at SignUp: type: object additionalProperties: false properties: object: type: string enum: - sign_up_attempt id: type: string status: type: string enum: - missing_requirements - complete - abandoned required_fields: type: array items: type: string optional_fields: type: array items: type: string missing_fields: type: array items: type: string unverified_fields: type: array items: type: string verifications: type: object username: type: string nullable: true email_address: type: string nullable: true phone_number: type: string nullable: true web3_wallet: type: string nullable: true password_enabled: type: boolean first_name: type: string nullable: true last_name: type: string nullable: true unsafe_metadata: type: object public_metadata: type: object custom_action: type: boolean external_id: type: string nullable: true created_session_id: type: string nullable: true created_user_id: type: string nullable: true abandon_at: type: integer identification_requirements: type: array items: type: array items: type: string missing_requirements: type: array items: type: string email_address_verification: type: object nullable: true deprecated: true phone_number_verification: type: object nullable: true deprecated: true external_account_strategy: type: string nullable: true external_account_verification: type: object nullable: true deprecated: true external_account: type: object required: - object - id - status - password_enabled - custom_action - abandon_at OAuthApplication: type: object properties: object: type: string enum: - oauth_application id: type: string instance_id: type: string name: type: string client_id: type: string scopes: type: string callback_url: type: string authorize_url: type: string token_fetch_url: type: string user_info_url: 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. " required: - object - id - instance_id - name - client_id - scopes - callback_url - authorize_url - token_fetch_url - user_info_url - created_at - updated_at OAuthApplications: type: object additionalProperties: false properties: data: type: array items: "$ref": "#/components/schemas/OAuthApplication" total_count: type: integer format: int64 description: "Total number of OAuth applications " required: - data - total_count OAuthApplicationWithSecret: allOf: - "$ref": "#/components/schemas/OAuthApplication" - type: object properties: client_secret: type: string required: - client_secret responses: Client.List: description: Success content: application/json: schema: type: array items: "$ref": "#/components/schemas/Client" ClerkErrors: description: Request was not successful content: application/json: schema: "$ref": "#/components/schemas/ClerkErrors" AuthenticationInvalid: description: Authentication invalid content: application/json: schema: "$ref": "#/components/schemas/ClerkErrors" UnprocessableEntity: description: Invalid request parameters content: application/json: schema: "$ref": "#/components/schemas/ClerkErrors" Client: description: Success content: application/json: schema: "$ref": "#/components/schemas/Client" ResourceNotFound: description: Resource not found content: application/json: schema: "$ref": "#/components/schemas/ClerkErrors" Session: description: Success content: application/json: schema: "$ref": "#/components/schemas/Session" EmailAddress: description: Success content: application/json: schema: "$ref": "#/components/schemas/EmailAddress" AuthorizationInvalid: description: Authorization invalid content: application/json: schema: "$ref": "#/components/schemas/ClerkErrors" DeletedObject: description: Deleted Object content: application/json: schema: "$ref": "#/components/schemas/DeletedObject" PhoneNumber: description: Success content: application/json: schema: "$ref": "#/components/schemas/PhoneNumber" Session.List: description: Success content: application/json: schema: type: array items: "$ref": "#/components/schemas/Session" Template.List: description: Success content: application/json: schema: type: array items: "$ref": "#/components/schemas/Template" Template: description: Success content: application/json: schema: "$ref": "#/components/schemas/Template" PaymentRequired: description: Payment required content: application/json: schema: "$ref": "#/components/schemas/ClerkErrors" User.List: description: Success content: application/json: schema: type: array items: "$ref": "#/components/schemas/User" User: description: Success content: application/json: schema: "$ref": "#/components/schemas/User" User.Count: description: Success content: application/json: schema: "$ref": "#/components/schemas/TotalCount" OrganizationMemberships: description: A list of organization memberships content: application/json: schema: "$ref": "#/components/schemas/OrganizationMemberships" Email: description: Success content: application/json: schema: "$ref": "#/components/schemas/Email" SMSMessage: description: Success content: application/json: schema: "$ref": "#/components/schemas/SMSMessage" Invitation.List: description: List of invitations content: application/json: schema: type: array items: "$ref": "#/components/schemas/Invitation" Invitation: description: Success content: application/json: schema: "$ref": "#/components/schemas/Invitation" AllowlistIdentifier.List: description: Success content: application/json: schema: type: array items: "$ref": "#/components/schemas/AllowlistIdentifier" AllowlistIdentifier: description: Success content: application/json: schema: "$ref": "#/components/schemas/AllowlistIdentifier" BlocklistIdentifier.List: description: Success content: application/json: schema: "$ref": "#/components/schemas/BlocklistIdentifiers" BlocklistIdentifier: description: Success content: application/json: schema: "$ref": "#/components/schemas/BlocklistIdentifier" InstanceSettings: description: InstanceSettings Server API content: application/json: schema: type: object properties: object: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - instance_settings id: type: string restricted_to_allowlist: type: boolean from_email_address: type: string progressive_sign_up: type: boolean enhanced_email_deliverability: type: boolean ActorToken: description: Success content: application/json: schema: "$ref": "#/components/schemas/ActorToken" InstanceRestrictions: description: Success content: application/json: schema: "$ref": "#/components/schemas/InstanceRestrictions" OrganizationSettings: description: Success content: application/json: schema: "$ref": "#/components/schemas/OrganizationSettings" SvixURL: description: Response that contains a temporary Svix URL to access management dashboard content: application/json: schema: "$ref": "#/components/schemas/SvixURL" JWTTemplate.List: description: List of JWT templates content: application/json: schema: type: array items: "$ref": "#/components/schemas/JWTTemplate" JWTTemplate: description: Success content: application/json: schema: "$ref": "#/components/schemas/JWTTemplate" Organizations: description: A list of organizations content: application/json: schema: "$ref": "#/components/schemas/Organizations" Organization: description: An organization content: application/json: schema: "$ref": "#/components/schemas/Organization" OrganizationWithLogo: description: An organization with a logo URL. content: application/json: schema: "$ref": "#/components/schemas/OrganizationWithLogo" OrganizationInvitation: description: An organization invitation content: application/json: schema: "$ref": "#/components/schemas/OrganizationInvitation" OrganizationInvitations: description: A list of organization invitations content: application/json: schema: "$ref": "#/components/schemas/OrganizationInvitations" OrganizationMembership: description: Success content: application/json: schema: "$ref": "#/components/schemas/OrganizationMembership" RedirectURL.List: description: List of Redirect URLs content: application/json: schema: type: array items: "$ref": "#/components/schemas/RedirectURL" RedirectURL: description: Success content: application/json: schema: "$ref": "#/components/schemas/RedirectURL" SignInToken: description: Success content: application/json: schema: "$ref": "#/components/schemas/SignInToken" SignUp: description: Success content: application/json: schema: "$ref": "#/components/schemas/SignUp" OAuthApplications: description: A list of OAuth applications content: application/json: schema: "$ref": "#/components/schemas/OAuthApplications" OAuthApplicationWithSecret: description: An OAuth application with client secret content: application/json: schema: "$ref": "#/components/schemas/OAuthApplicationWithSecret" OAuthApplication: description: An OAuth application content: application/json: schema: "$ref": "#/components/schemas/OAuthApplication" tags: - name: Actor Tokens description: Allow your users to sign in on behalf of other users. externalDocs: url: https://clerk.com/docs/authentication/user-impersonation#actor-tokens - name: Allow-list / Block-list description: |- Allow-lists and Block-lists allow you to control who can sign up or sign in to your application, by restricting access based on the user's email address or phone number. externalDocs: url: https://clerk.com/docs/authentication/allowlist - name: Clients description: The Client object tracks sessions, as well as the state of any sign in and sign up attempts, for a given device. externalDocs: url: https://clerk.com/docs/reference/clerkjs/client - name: Email Addresses description: A user can be associated with one or more email addresses and allows them to be contacted via email. externalDocs: url: https://clerk.com/docs/reference/clerkjs/emailaddress - name: Emails description: |- The email object represents an email that has been sent to an email address. You can only send an email to email addresses that have been verified by a user. Only recommended for transactional emails. - name: Email & SMS Templates description: Email & SMS templates allow you to customize the theming and wording of emails & SMS messages that are sent by your instance. externalDocs: url: https://clerk.com/docs/authentication/email-sms-templates - name: Instance Settings description: Modify the settings of your instance. - name: Invitations description: Invitations allow you to invite someone to sign up to your application, via email. externalDocs: url: https://clerk.com/docs/authentication/invitations - name: JWKS description: Retrieve the JSON Web Key Set which can be used to verify the token signatures of the instance. - name: JWT Templates description: |- JWT Templates allow you to generate custom authentication tokens tied to authenticated sessions, enabling you to integrate with third-party services. externalDocs: url: https://clerk.com/docs/request-authentication/jwt-templates - name: OAuth Applications description: OAuth applications contain data for clients using Clerk as an OAuth2 identity provider. - name: Organizations description: Organizations are used to group members under a common entity and provide shared access to resources. externalDocs: url: https://clerk.com/docs/organizations/overview - name: Organization Invitations description: Invite users to an organization. externalDocs: url: https://clerk.com/docs/organizations/invite-users - name: Organization Memberships description: Manage member roles in an organization. externalDocs: url: https://clerk.com/docs/organizations/manage-member-roles - name: Phone Numbers description: A user can be associated with one or more email addresses and allows them to be contacted via SMS. externalDocs: url: https://clerk.com/docs/reference/clerkjs/phonenumber - name: Redirect URLs description: |- Redirect URLs are whitelisted URLs that facilitate secure authentication flows in native applications (e.g. React Native, Expo). In these contexts, Clerk ensures that security-critical nonces are passed only to the whitelisted URLs. - name: Sessions description: |- The Session object is an abstraction over an HTTP session. It models the period of information exchange between a user and the server. Sessions are created when a user successfully goes through the sign in or sign up flows. externalDocs: url: https://clerk.com/docs/reference/clerkjs/session - name: Sign-in Tokens description: |- Sign-in tokens are JWTs that can be used to sign in to an application without specifying any credentials. A sign-in token can be used at most once and they can be consumed from the Frontend API using the `ticket` strategy. - name: SMS Messages description: |- SMS messages can be sent to verified phone numbers that belong to users. This functionality is only recommended for transactional SMS messages. - name: Users description: The user object represents a user that has successfully signed up to your application. externalDocs: url: https://clerk.com/docs/reference/clerkjs/user - name: Webhooks description: You can configure webhooks to be notified about various events that happen on your instance. externalDocs: url: https://clerk.com/docs/integration/webhooks - name: Miscellaneous description: Various endpoints that do not belong in any particular category. - name: Beta Features description: Modify instance settings that are currently in beta. paths: "/public/demo_instance": post: security: [] operationId: CreateDemoInstance summary: Create a demo development instance description: Creates a demo development instance and returns the corresponding Frontend/Backend API keys. tags: - Miscellaneous responses: "200": description: The API keys of the created instance. content: application/json: schema: type: object additionalProperties: false properties: object: type: string enum: - demo_dev_instance frontend_api_key: type: string backend_api_key: type: string jwt_verification_key: type: string description: The public key that can be used to verify the session tokens of the created instance. accounts_url: type: string description: The URL of the hosted Accounts Portal of the created instance. format: uri "/public/interstitial": get: security: [] summary: Returns the markup for the interstitial page description: |- The Clerk interstitial endpoint serves an html page that loads clerk.js in order to check the user's authentication state. It is used by Clerk SDKs when the user's authentication state cannot be immediately determined. operationId: GetPublicInterstitial tags: - Miscellaneous parameters: - name: frontendApi in: query required: false description: The Frontend API key of your instance schema: type: string - name: publishable_key in: query required: false description: The publishable key of your instance schema: type: string responses: "200": description: The interstitial page markup "400": description: A required query parameter is missing "/jwks": get: operationId: GetJWKS summary: Retrieve the JSON Web Key Set of the instance description: Retrieve the JSON Web Key Set of the instance tags: - JWKS responses: "200": description: The JSON Web Key Set "/clients": get: operationId: GetClientList tags: - Clients summary: List all clients description: |- Returns a list of all clients. The clients are returned sorted by creation date, with the newest clients appearing first. parameters: - "$ref": "#/components/parameters/LimitParameter" - "$ref": "#/components/parameters/OffsetParameter" responses: "200": "$ref": "#/components/responses/Client.List" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "422": "$ref": "#/components/responses/UnprocessableEntity" "/clients/verify": post: operationId: VerifyClient tags: - Clients summary: Verify a client description: Verifies the client in the provided token requestBody: description: Parameters. content: application/json: schema: type: object additionalProperties: false properties: token: type: string description: A JWT Token that represents the active client. responses: "200": "$ref": "#/components/responses/Client" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "/clients/{client_id}": get: operationId: GetClient tags: - Clients summary: Get a client description: Returns the details of a client. parameters: - name: client_id in: path description: Client ID. required: true schema: type: string responses: "200": "$ref": "#/components/responses/Client" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "/clients/{client_id}/last_active_session": get: operationId: GetClientLastActiveSession tags: - Clients summary: Get the last active session of a client description: Returns the details of the last active session of a client. parameters: - name: client_id in: path description: Client ID. required: true schema: type: string responses: "200": "$ref": "#/components/responses/Session" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "/email_addresses": post: operationId: CreateEmailAddress tags: - Email Addresses summary: Create an email address description: Create a new email address requestBody: content: application/json: schema: type: object properties: user_id: type: string description: The ID representing the user email_address: type: string description: The new email address. Must adhere to the RFC 5322 specification for email address format. verified: type: boolean description: When created, the email address will be marked as verified. nullable: true primary: type: boolean description: |- Create this email address as the primary email address for the user. Default: false, unless it is the first email address. nullable: true responses: "200": "$ref": "#/components/responses/EmailAddress" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "403": "$ref": "#/components/responses/AuthorizationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" "/email_addresses/{email_address_id}": get: operationId: GetEmailAddress tags: - Email Addresses summary: Retrieve an email address description: Returns the details of an email address. parameters: - name: email_address_id in: path description: The ID of the email address to retrieve required: true schema: type: string responses: "200": "$ref": "#/components/responses/EmailAddress" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "403": "$ref": "#/components/responses/AuthorizationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" delete: operationId: DeleteEmailAddress tags: - Email Addresses summary: Delete an email address description: Delete the email address with the given ID parameters: - name: email_address_id in: path description: The ID of the email address to delete required: true schema: type: string responses: "200": "$ref": "#/components/responses/DeletedObject" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "403": "$ref": "#/components/responses/AuthorizationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" patch: operationId: UpdateEmailAddress tags: - Email Addresses summary: Update an email address description: Updates an email address. parameters: - name: email_address_id in: path description: The ID of the email address to update required: true schema: type: string requestBody: content: application/json: schema: type: object properties: verified: type: boolean description: The email address will be marked as verified. nullable: true primary: type: boolean description: Set this email address as the primary email address for the user. nullable: true responses: "200": "$ref": "#/components/responses/EmailAddress" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "403": "$ref": "#/components/responses/AuthorizationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "/phone_numbers": post: operationId: CreatePhoneNumber tags: - Phone Numbers summary: Create a phone number description: Create a new phone number requestBody: content: application/json: schema: type: object properties: user_id: type: string description: The ID representing the user phone_number: type: string description: The new phone number. Must adhere to the E.164 standard for phone number format. verified: type: boolean description: When created, the phone number will be marked as verified. nullable: true primary: type: boolean description: |- Create this phone number as the primary phone number for the user. Default: false, unless it is the first phone number. nullable: true responses: "200": "$ref": "#/components/responses/PhoneNumber" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "403": "$ref": "#/components/responses/AuthorizationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" "/phone_numbers/{phone_number_id}": get: operationId: GetPhoneNumber tags: - Phone Numbers summary: Retrieve a phone number description: Returns the details of a phone number parameters: - name: phone_number_id in: path description: The ID of the phone number to retrieve required: true schema: type: string responses: "200": "$ref": "#/components/responses/PhoneNumber" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "403": "$ref": "#/components/responses/AuthorizationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" delete: operationId: DeletePhoneNumber tags: - Phone Numbers summary: Delete a phone number description: Delete the phone number with the given ID parameters: - name: phone_number_id in: path description: The ID of the phone number to delete required: true schema: type: string responses: "200": "$ref": "#/components/responses/DeletedObject" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "403": "$ref": "#/components/responses/AuthorizationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" patch: operationId: UpdatePhoneNumber tags: - Phone Numbers summary: Update a phone number description: Updates a phone number parameters: - name: phone_number_id in: path description: The ID of the phone number to update required: true schema: type: string requestBody: content: application/json: schema: type: object properties: verified: type: boolean description: The phone number will be marked as verified. nullable: true primary: type: boolean description: Set this phone number as the primary phone number for the user. nullable: true responses: "200": "$ref": "#/components/responses/PhoneNumber" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "403": "$ref": "#/components/responses/AuthorizationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "/sessions": get: operationId: GetSessionList tags: - Sessions summary: List all sessions description: |- Returns a list of all sessions. The sessions are returned sorted by creation date, with the newest sessions appearing first. parameters: - name: client_id in: query required: false description: List sessions for the given client schema: type: string - name: user_id in: query required: false description: List sessions for the given user schema: type: string - name: status in: query required: false description: Filter sessions by the provided status schema: type: string enum: - abandoned - active - ended - expired - removed - replaced - revoked - "$ref": "#/components/parameters/LimitParameter" - "$ref": "#/components/parameters/OffsetParameter" responses: "200": "$ref": "#/components/responses/Session.List" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "422": "$ref": "#/components/responses/UnprocessableEntity" "/sessions/{session_id}": get: operationId: GetSession tags: - Sessions summary: Retrieve a session description: Retrieve the details of a session parameters: - name: session_id in: path description: The ID of the session required: true schema: type: string responses: "200": "$ref": "#/components/responses/Session" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "/sessions/{session_id}/revoke": post: operationId: RevokeSession tags: - Sessions summary: Revoke a session description: |- Sets the status of a session as "revoked", which is an unauthenticated state. In multi-session mode, a revoked session will still be returned along with its client object, however the user will need to sign in again. parameters: - name: session_id in: path description: The ID of the session required: true schema: type: string responses: "200": "$ref": "#/components/responses/Session" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "/sessions/{session_id}/verify": post: operationId: VerifySession tags: - Sessions summary: Verify a session description: Returns the session if it is authenticated, otherwise returns an error. parameters: - name: session_id in: path description: The ID of the session required: true schema: type: string requestBody: description: Parameters. content: application/json: schema: type: object additionalProperties: false properties: token: type: string description: |- The JWT that is sent via the `__session` cookie from your frontend. Note: this JWT must be associated with the supplied session ID. responses: "200": "$ref": "#/components/responses/Session" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "/sessions/{session_id}/tokens/{template_name}": post: operationId: CreateSessionTokenFromTemplate tags: - Sessions summary: Create a session token from a jwt template description: Creates a JSON Web Token(JWT) based on a session and a JWT Template name defined for your instance parameters: - name: session_id in: path description: The ID of the session required: true schema: type: string - name: template_name in: path description: The name of the JWT Template defined in your instance (e.g. `custom_hasura`). required: true schema: type: string responses: "200": description: OK content: application/json: schema: type: object properties: object: type: string enum: - token jwt: type: string "401": "$ref": "#/components/responses/AuthenticationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "/templates/{template_type}": get: operationId: GetTemplateList summary: List all templates description: |- Returns a list of all templates. The templates are returned sorted by position. tags: - Email & SMS Templates parameters: - name: template_type in: path description: The type of templates to list (email or SMS) required: true schema: type: string enum: - email - sms responses: "200": "$ref": "#/components/responses/Template.List" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "422": "$ref": "#/components/responses/UnprocessableEntity" "/templates/{template_type}/{slug}": get: operationId: GetTemplate summary: Retrieve a template description: Returns the details of a template tags: - Email & SMS Templates parameters: - name: template_type in: path description: The type of templates to retrieve (email or SMS) required: true schema: type: string enum: - email - sms - name: slug in: path description: The slug (i.e. machine-friendly name) of the template to retrieve required: true schema: type: string responses: "200": "$ref": "#/components/responses/Template" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" put: operationId: UpsertTemplate summary: Update a template for a given type and slug description: Updates the existing template of the given type and slug tags: - Email & SMS Templates parameters: - name: template_type in: path description: The type of template to update required: true schema: type: string enum: - email - sms - name: slug in: path description: The slug of the template to update required: true schema: type: string requestBody: content: application/json: schema: type: object additionalProperties: false properties: name: type: string description: The user-friendly name of the template subject: type: string description: |- The email subject. Applicable only to email templates. nullable: true markup: type: string description: The editor markup used to generate the body of the template nullable: true body: type: string description: The template body before variable interpolation delivered_by_clerk: type: boolean description: Whether Clerk should deliver emails or SMS messages based on the current template nullable: true from_email_name: type: string description: |- The local part of the From email address that will be used for emails. For example, in the address 'hello@example.com', the local part is 'hello'. Applicable only to email templates. responses: "200": "$ref": "#/components/responses/Template" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "402": "$ref": "#/components/responses/PaymentRequired" "404": "$ref": "#/components/responses/ResourceNotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" "/templates/{template_type}/{slug}/revert": post: operationId: RevertTemplate summary: Revert a template description: Reverts an updated template to its default state tags: - Email & SMS Templates parameters: - name: template_type in: path description: The type of template to revert required: true schema: type: string enum: - email - sms - name: slug in: path description: The slug of the template to revert required: true schema: type: string responses: "200": "$ref": "#/components/responses/Template" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "402": "$ref": "#/components/responses/PaymentRequired" "404": "$ref": "#/components/responses/ResourceNotFound" "/templates/{template_type}/{slug}/preview": post: operationId: PreviewTemplate summary: Preview changes to a template description: Returns a preview of a template for a given template_type, slug and body tags: - Email & SMS Templates parameters: - name: template_type in: path description: The type of template to preview required: true schema: type: string - name: slug in: path description: The slug of the template to preview required: true schema: type: string requestBody: description: Required parameters content: application/json: schema: type: object additionalProperties: false properties: subject: type: string description: |- The email subject. Applicable only to email templates. nullable: true body: type: string description: The template body before variable interpolation from_email_name: type: string description: |- The local part of the From email address that will be used for emails. For example, in the address 'hello@example.com', the local part is 'hello'. Applicable only to email templates. responses: "200": description: OK content: application/json: schema: type: object "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" "/users": get: operationId: GetUserList summary: List all users description: |- Returns a list of all users. The users are returned sorted by creation date, with the newest users appearing first. tags: - Users parameters: - name: email_address in: query schema: type: array items: type: string description: |- Returns users with the specified email addresses. Accepts up to 100 email addresses. Any email addresses not found are ignored. required: false - name: phone_number in: query schema: type: array items: type: string description: |- Returns users with the specified phone numbers. Accepts up to 100 phone numbers. Any phone numbers not found are ignored. required: false - name: external_id in: query schema: type: array items: type: string description: |- Returns users with the specified external ids. For each external id, the `+` and `-` can be prepended to the id, which denote whether the respective external id should be included or excluded from the result set. Accepts up to 100 external ids. Any external ids not found are ignored. required: false - name: username in: query schema: type: array items: type: string description: |- Returns users with the specified usernames. Accepts up to 100 usernames. Any usernames not found are ignored. required: false - name: web3_wallet in: query schema: type: array items: type: string description: |- Returns users with the specified web3 wallet addresses. Accepts up to 100 web3 wallet addresses. Any web3 wallet addressed not found are ignored. required: false - name: user_id in: query schema: type: array items: type: string description: |- Returns users with the user ids specified. For each user id, the `+` and `-` can be prepended to the id, which denote whether the respective user id should be included or excluded from the result set. Accepts up to 100 user ids. Any user ids not found are ignored. required: false - name: organization_id in: query schema: type: array items: type: string description: |- Returns users that have memberships to the given organizations. For each organization id, the `+` and `-` can be prepended to the id, which denote whether the respective organization should be included or excluded from the result set. Accepts up to 100 organization ids. required: false - name: query in: query description: |- Returns users that match the given query. For possible matches, we check the email addresses, phone numbers, usernames, web3 wallets, user ids, first and last names. The query value doesn't need to match the exact value you are looking for, it is capable of partial matches as well. schema: type: string required: false - "$ref": "#/components/parameters/LimitParameter" - "$ref": "#/components/parameters/OffsetParameter" - name: order_by in: query description: |- Allows to return users in a particular order. At the moment, you can order the returned users either by their `created_at` or `updated_at` timestamp. In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. For example, if you want users to be returned in descending order according to their `created_at` property, you can use `-created_at`. If you don't use `+` or `-`, then `+` is implied. Defaults to `-created_at`. schema: type: string default: "-created_at" required: false responses: "200": "$ref": "#/components/responses/User.List" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "422": "$ref": "#/components/responses/UnprocessableEntity" post: operationId: CreateUser summary: Create a new user description: |- Creates a new user. Your user management settings determine how you should setup your user model. Any email address and phone number created using this method will be marked as verified. Note: If you are performing a migration, check out our guide on [zero downtime migrations](https://clerk.com/docs/deployments/import-users). A rate limit rule of 20 requests per 10 seconds is applied to this endpoint. tags: - Users requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: external_id: type: string description: |- The ID of the user as used in your external systems or your previous authentication solution. Must be unique across your instance. nullable: true first_name: type: string description: The first name to assign to the user nullable: true last_name: type: string description: The last name to assign to the user nullable: true email_address: type: array items: type: string description: |- Email addresses to add to the user. Must be unique across your instance. The first email address will be set as the user's primary email address. phone_number: type: array items: type: string description: |- Phone numbers to add to the user. Must be unique across your instance. The first phone number will be set as the user's primary phone number. web3_wallet: type: array items: type: string description: |- Web3 wallets to add to the user. Must be unique across your instance. The first wallet will be set as the user's primary wallet. username: type: string description: |- The username to give to the user. It must be unique across your instance. nullable: true password: type: string description: |- The plaintext password to give the user. Must be at least 8 characters long, and can not be in any list of hacked passwords. nullable: true 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. The digests should be generated with one of the supported algorithms. The hashing algorithm can be specified using the `password_hasher` property. password_hasher: type: string description: |- The hashing algorithm that was used to generate the password digest. The algorithms we support at the moment are [bcrypt](https://en.wikipedia.org/wiki/Bcrypt), md5, pbkdf2_sha256, [pbkdf2_sha256_django](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/), [scrypt_firebase](https://firebaseopensource.com/projects/firebase/scrypt/) and 2 [argon2](https://argon2.online/) variants, argon2i and argon2id. Each of the above expects the incoming digest to be of a particular format. More specifically: **bcrypt:** The digest should be of the following form: `$$$` **md5:** The digest should follow the regular form e.g.: `5f4dcc3b5aa765d61d8327deb882cf99` **pbkdf2_sha256:** This is the PBKDF2 algorithm using the SHA256 hashing function. The format should be as follows: `pbkdf2_sha256$$$` Note: Both the salt and the hash are expected to be base64-encoded. **pbkdf2_sha256_django:** This is the Django-specific variant of PBKDF2 and the digest should have the following format (as exported from Django): `pbkdf2_sha256$$$` Note: The salt is expected to be un-encoded, the hash is expected base64-encoded. **pbkdf2_sha1:** This is similar to pkbdf2_sha256_django, but with two differences: 1. uses sha1 instead of sha256 2. accepts the hash as a hex-encoded string The format is the following: `pbkdf2_sha1$$$` **scrypt_firebase:** The Firebase-specific variant of scrypt. The value is expected to have 6 segments separated by the $ character and include the following information: _hash:_ The actual Base64 hash. This can be retrieved when exporting the user from Firebase. _salt:_ The salt used to generate the above hash. Again, this is given when exporting the user. _signer key:_ The base64 encoded signer key. _salt separator:_ The base64 encoded salt separator. _rounds:_ The number of rounds the algorithm needs to run. _memory cost:_ The cost of the algorithm run The first 2 (hash and salt) are per user and can be retrieved when exporting the user from Firebase. The 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. Once 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: `$$$$$` **argon2i:** Algorithms in the argon2 family generate digests that encode the following information: _version (v):_ The argon version, version 19 is assumed _memory (m):_ The memory used by the algorithm (in kibibytes) _iterations (t):_ The number of iterations to perform _parallelism (p):_ The number of threads to use Parts are demarcated by the `$` character, with the first part identifying the algorithm variant. The middle part is a comma-separated list of the encoding options (memory, iterations, parallelism). The final part is the actual digest. `$argon2i$v=19$m=4096,t=3,p=1$4t6CL3P7YiHBtwESXawI8Hm20zJj4cs7/4/G3c187e0$m7RQFczcKr5bIR0IIxbpO2P0tyrLjf3eUW3M3QSwnLc` **argon2id:** See the previous algorithm for an explanation of the formatting. For the argon2id case, the value of the algorithm in the first part of the digest is `argon2id`: `$argon2id$v=19$m=64,t=4,p=8$Z2liZXJyaXNo$iGXEpMBTDYQ8G/71tF0qGjxRHEmR3gpGULcE93zUJVU` If you need support for any particular hashing algorithm, [please let us know](https://clerk.com/support). enum: - bcrypt - md5 - pbkdf2_sha256 - pbkdf2_sha256_django - pbkdf2_sha1 - scrypt_firebase - argon2i - argon2id skip_password_checks: type: boolean description: |- When set to `true` all password checks are skipped. It is recommended to use this method only when migrating plaintext passwords to Clerk. Upon 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. This is useful when you are trying to create a user that doesn't have a password, in an instance that is using passwords. Please note that you cannot use this flag if password is the only way for a user to sign into 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. Please note that currently the supported options are: * Period: 30 seconds * Code length: 6 digits * 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 newly created user without the need to reset them. You must provide the backup codes in plain format or the corresponding bcrypt digest. public_metadata: type: object description: Metadata saved on the user, that is visible to both your Frontend and Backend APIs private_metadata: type: object description: Metadata saved on the user, that is only visible to your Backend API unsafe_metadata: type: object description: |- Metadata saved on the user, that can be updated from both the Frontend and Backend APIs. Note: Since this data can be modified from the frontend, it is not guaranteed to be safe. 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`). responses: "200": "$ref": "#/components/responses/User" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "422": "$ref": "#/components/responses/UnprocessableEntity" "/users/count": get: operationId: GetUsersCount summary: Count users description: Returns a total count of all users that match the given filtering criteria. tags: - Users parameters: - name: email_address in: query schema: type: array items: type: string description: |- Counts users with the specified email addresses. Accepts up to 100 email addresses. Any email addresses not found are ignored. required: false - name: phone_number in: query schema: type: array items: type: string description: |- Counts users with the specified phone numbers. Accepts up to 100 phone numbers. Any phone numbers not found are ignored. required: false - name: external_id in: query schema: type: array items: type: string description: |- Counts users with the specified external ids. Accepts up to 100 external ids. Any external ids not found are ignored. required: false - name: username in: query schema: type: array items: type: string description: |- Counts users with the specified usernames. Accepts up to 100 usernames. Any usernames not found are ignored. required: false - name: web3_wallet in: query schema: type: array items: type: string description: |- Counts users with the specified web3 wallet addresses. Accepts up to 100 web3 wallet addresses. Any web3 wallet addressed not found are ignored. required: false - name: user_id in: query schema: type: array items: type: string description: |- Counts users with the user ids specified. Accepts up to 100 user ids. Any user ids not found are ignored. required: false - name: query in: query description: |- Counts users that match the given query. For possible matches, we check the email addresses, phone numbers, usernames, web3 wallets, user ids, first and last names. The query value doesn't need to match the exact value you are looking for, it is capable of partial matches as well. schema: type: string required: false responses: "200": "$ref": "#/components/responses/User.Count" "422": "$ref": "#/components/responses/UnprocessableEntity" "/users/{user_id}": get: operationId: GetUser summary: Retrieve a user description: Retrieve the details of a user tags: - Users parameters: - name: user_id in: path description: The ID of the user to retrieve required: true schema: type: string responses: "200": "$ref": "#/components/responses/User" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" patch: operationId: UpdateUser summary: Update a user description: |- 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. tags: - Users parameters: - name: user_id in: path description: The ID of the user to update required: true schema: type: string requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: external_id: type: string description: |- The ID of the user as used in your external systems or your previous authentication solution. Must be unique across your instance. nullable: true first_name: type: string description: The first name to assign to the user nullable: true last_name: type: string description: The last name to assign to the user nullable: true primary_email_address_id: type: string description: |- The ID of the email address to set as primary. It 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. It must be verified, and present on the current user. primary_web3_wallet_id: type: string description: |- The ID of the web3 wallets to set as primary. It must be verified, and present on the current user. username: type: string description: |- The username to give to the user. It must be unique across your instance. nullable: true profile_image_id: type: string description: The ID of the image to set as the user's profile image nullable: true password: type: string description: |- The plaintext password to give the user. Must be at least 8 characters long, and can not be in any list of hacked passwords. nullable: true 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. Please note that currently the supported options are: * Period: 30 seconds * Code length: 6 digits * 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. You must provide the backup codes in plain format or the corresponding bcrypt digest. public_metadata: type: object description: Metadata saved on the user, that is visible to both your Frontend and Backend APIs private_metadata: type: object description: Metadata saved on the user, that is only visible to your Backend API unsafe_metadata: type: object description: |- Metadata saved on the user, that can be updated from both the Frontend and Backend APIs. Note: Since this data can be modified from the frontend, it is not guaranteed to be safe. 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`). responses: "200": "$ref": "#/components/responses/User" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" delete: operationId: DeleteUser summary: Delete a user description: Delete the specified user tags: - Users parameters: - name: user_id in: path description: The ID of the user to delete required: true schema: type: string responses: "200": "$ref": "#/components/responses/DeletedObject" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "/users/{user_id}/ban": post: operationId: BanUser summary: Ban a user description: Marks the given user as banned, which means that all their sessions are revoked and they are not allowed to sign in again. tags: - Users parameters: - name: user_id in: path description: The ID of the user to ban required: true schema: type: string responses: "200": "$ref": "#/components/responses/User" "402": "$ref": "#/components/responses/PaymentRequired" "/users/{user_id}/unban": post: operationId: UnbanUser summary: Unban a user description: Removes the ban mark from the given user. tags: - Users parameters: - name: user_id in: path description: The ID of the user to unban required: true schema: type: string responses: "200": "$ref": "#/components/responses/User" "402": "$ref": "#/components/responses/PaymentRequired" "/users/{user_id}/metadata": patch: operationId: UpdateUserMetadata summary: Merge and update a user's metadata description: |- 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`. tags: - Users parameters: - name: user_id in: path description: The ID of the user whose metadata will be updated and merged required: true schema: type: string requestBody: content: application/json: schema: type: object additionalProperties: false properties: public_metadata: type: object description: |- Metadata saved on the user, that is visible to both your frontend and backend. The new object will be merged with the existing value. private_metadata: type: object description: |- Metadata saved on the user that is only visible to your backend. The 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. The new object will be merged with the existing value. Note: Since this data can be modified from the frontend, it is not guaranteed to be safe. responses: "200": "$ref": "#/components/responses/User" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" "/users/{user_id}/oauth_access_tokens/{provider}": get: operationId: GetOAuthAccessToken summary: Retrieve the OAuth access token of a user description: |- Fetch the corresponding OAuth access token for a user that has previously authenticated with a particular OAuth provider. For OAuth 2.0, if the access token has expired and we have a corresponding refresh token, the access token will be refreshed transparently the new one will be returned. tags: - Users parameters: - name: user_id in: path description: The ID of the user for which to retrieve the OAuth access token required: true schema: type: string - name: provider in: path description: The ID of the OAuth provider (e.g. `oauth_google`) required: true schema: type: string responses: "200": description: The OAuth access token of the user, if any. content: application/json: schema: type: array items: type: object additionalProperties: false properties: object: type: string token: type: string description: The access token provider: type: string description: The ID of the provider public_metadata: type: object label: type: string nullable: true scopes: type: array items: type: string description: |- The list of scopes that the token is valid for. Only present for OAuth 2.0 tokens. token_secret: type: string description: The token secret. Only present for OAuth 1.0 tokens. "422": "$ref": "#/components/responses/UnprocessableEntity" "/users/{user_id}/organization_memberships": get: operationId: UsersGetOrganizationMemberships summary: Retrieve all memberships for a user description: Retrieve a paginated list of the user's organization memberships tags: - Users parameters: - name: user_id in: path description: The ID of the user whose organization memberships we want to retrieve required: true schema: type: string - "$ref": "#/components/parameters/LimitParameter" - "$ref": "#/components/parameters/OffsetParameter" responses: "200": "$ref": "#/components/responses/OrganizationMemberships" "403": "$ref": "#/components/responses/ClerkErrors" "/users/{user_id}/verify_password": post: operationId: VerifyPassword summary: Verify the password of a user description: |- Check that the user's password matches the supplied input. Useful for custom auth flows and re-verification. tags: - Users parameters: - name: user_id in: path description: The ID of the user for whom to verify the password required: true schema: type: string requestBody: content: application/json: schema: type: object additionalProperties: false properties: password: type: string description: The user password to verify required: - password responses: "200": description: The provided password was correct. content: application/json: schema: type: object additionalProperties: false properties: verified: type: boolean nullable: false "400": description: The user does not have a password set. "404": description: The user does not exist. "422": description: The provided password was incorrect. "500": "$ref": "#/components/responses/ClerkErrors" "/users/{user_id}/verify_totp": post: operationId: VerifyTOTP summary: Verify a TOTP or backup code for a user description: |- Verify that the provided TOTP or backup code is valid for the user. Verifying a backup code will result it in being consumed (i.e. it will become invalid). Useful for custom auth flows and re-verification. tags: - Users parameters: - name: user_id in: path description: The ID of the user for whom to verify the TOTP required: true schema: type: string requestBody: content: application/json: schema: type: object additionalProperties: false properties: code: type: string description: The TOTP or backup code to verify required: - code responses: "200": description: The provided TOTP or backup code was correct. content: application/json: schema: type: object additionalProperties: false properties: verified: type: boolean nullable: false code_type: type: string nullable: false enum: - totp - backup_code "400": description: The user does not have TOTP configured for their account. "404": description: The user does not exist. "422": description: The provided TOTP or backup code was incorrect. "500": "$ref": "#/components/responses/ClerkErrors" "/users/{user_id}/mfa": delete: operationId: DisableMFA summary: Disable a user's MFA methods description: Disable all of a user's MFA methods (e.g. OTP sent via SMS, TOTP on their authenticator app) at once. tags: - Users parameters: - name: user_id in: path description: The ID of the user whose MFA methods are to be disabled required: true schema: type: string responses: "200": description: Successful operation. content: application/json: schema: type: object additionalProperties: false properties: user_id: type: string nullable: false "404": "$ref": "#/components/responses/ResourceNotFound" "500": "$ref": "#/components/responses/ClerkErrors" "/emails": post: operationId: CreateEmail summary: Create an email description: Create and send an email to the supplied email address ID. tags: - Emails requestBody: description: Required parameters content: application/json: schema: type: object additionalProperties: false properties: from_email_name: type: string description: |- The email name portion of the sending email address.
e.g.: `from_email_name=info` will send from info@example.com subject: type: string description: The subject of the email. nullable: true body: type: string description: The body of the email. nullable: true email_address_id: type: string nullable: true description: The ID of the email address to send to. template_slug: type: string nullable: true description: The slug of the template to use for sending this email responses: "200": "$ref": "#/components/responses/Email" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "403": "$ref": "#/components/responses/AuthorizationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" "/sms_messages": post: operationId: CreateSMSMessage summary: Create an SMS message description: Create and send an SMS message to the supplied phone number ID tags: - SMS Messages requestBody: description: Required parameters content: application/json: schema: type: object additionalProperties: false properties: message: type: string description: The message you would like to send nullable: true phone_number_id: type: string description: The ID of a verified phone number the SMS message should be sent to responses: "200": "$ref": "#/components/responses/SMSMessage" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "403": "$ref": "#/components/responses/AuthorizationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "/invitations": post: operationId: CreateInvitation summary: Create an invitation description: |- Creates a new invitation for the given email address and sends the invitation email. Keep in mind that you cannot create an invitation if there is already one for the given email address. Also, trying to create an invitation for an email address that already exists in your application will result to an error. tags: - Invitations requestBody: description: Required parameters content: application/json: schema: type: object additionalProperties: false properties: email_address: type: string description: The email address the invitation will be sent to public_metadata: type: object description: |- Metadata that will be attached to the newly created invitation. The value of this property should be a well-formed JSON object. Once the user accepts the invitation and signs up, these metadata will end up in the user's public metadata. redirect_url: type: string description: |- Optional URL which specifies where to redirect the user once they click the invitation link. This 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. required: - email_address responses: "200": "$ref": "#/components/responses/Invitation" "400": "$ref": "#/components/responses/ClerkErrors" "422": "$ref": "#/components/responses/UnprocessableEntity" get: summary: List all invitations description: Returns all non-revoked invitations for your application, sorted by creation date operationId: ListInvitations parameters: - in: query name: status description: Filter invitations based on their status required: false schema: type: string enum: - pending - accepted - revoked tags: - Invitations responses: "200": "$ref": "#/components/responses/Invitation.List" "/invitations/{invitation_id}/revoke": post: operationId: RevokeInvitation summary: Revokes an invitation description: |- Revokes the given invitation. Revoking an invitation will prevent the user from using the invitation link that was sent to them. However, it doesn't prevent the user from signing up if they follow the sign up flow. Only active (i.e. non-revoked) invitations can be revoked. tags: - Invitations parameters: - name: invitation_id in: path description: The ID of the invitation to be revoked required: true schema: type: string responses: "200": "$ref": "#/components/responses/Invitation" "400": "$ref": "#/components/responses/ClerkErrors" "404": "$ref": "#/components/responses/ResourceNotFound" "/allowlist_identifiers": get: operationId: ListAllowlistIdentifiers summary: List all identifiers on the allow-list description: Get a list of all identifiers allowed to sign up to an instance tags: - Allow-list / Block-list responses: "200": "$ref": "#/components/responses/AllowlistIdentifier.List" "401": "$ref": "#/components/responses/AuthenticationInvalid" "402": "$ref": "#/components/responses/PaymentRequired" post: operationId: CreateAllowlistIdentifier summary: Add identifier to the allow-list description: Create an identifier allowed to sign up to an instance tags: - Allow-list / Block-list responses: "200": "$ref": "#/components/responses/AllowlistIdentifier" "400": "$ref": "#/components/responses/ClerkErrors" "402": "$ref": "#/components/responses/PaymentRequired" "422": "$ref": "#/components/responses/UnprocessableEntity" "/allowlist_identifiers/{identifier_id}": delete: operationId: DeleteAllowlistIdentifier summary: Delete identifier from allow-list description: Delete an identifier from the instance allow-list tags: - Allow-list / Block-list parameters: - name: identifier_id in: path description: The ID of the identifier to delete from the allow-list required: true schema: type: string responses: "200": "$ref": "#/components/responses/DeletedObject" "402": "$ref": "#/components/responses/PaymentRequired" "404": "$ref": "#/components/responses/ResourceNotFound" "/blocklist_identifiers": get: operationId: ListBlocklistIdentifiers summary: List all identifiers on the block-list description: Get a list of all identifiers which are not allowed to access an instance tags: - Allow-list / Block-list responses: "200": "$ref": "#/components/responses/BlocklistIdentifier.List" "401": "$ref": "#/components/responses/AuthenticationInvalid" "402": "$ref": "#/components/responses/PaymentRequired" post: operationId: CreateBlocklistIdentifier summary: Add identifier to the block-list description: Create an identifier that is blocked from accessing an instance tags: - Allow-list / Block-list responses: "200": "$ref": "#/components/responses/BlocklistIdentifier" "400": "$ref": "#/components/responses/ClerkErrors" "402": "$ref": "#/components/responses/PaymentRequired" "422": "$ref": "#/components/responses/UnprocessableEntity" "/blocklist_identifiers/{identifier_id}": delete: operationId: DeleteBlocklistIdentifier summary: Delete identifier from block-list description: Delete an identifier from the instance block-list tags: - Allow-list / Block-list parameters: - name: identifier_id in: path description: The ID of the identifier to delete from the block-list required: true schema: type: string responses: "200": "$ref": "#/components/responses/DeletedObject" "402": "$ref": "#/components/responses/PaymentRequired" "404": "$ref": "#/components/responses/ResourceNotFound" "/beta_features/instance_settings": patch: operationId: UpdateInstanceAuthConfig summary: Update instance settings description: Updates the settings of an instance tags: - Beta Features requestBody: content: application/json: schema: type: object additionalProperties: false properties: restricted_to_allowlist: type: boolean description: Whether sign up is restricted to email addresses, phone numbers and usernames that are on the allowlist. nullable: true default: false from_email_address: type: string description: |- The local part of the email address from which authentication-related emails (e.g. OTP code, magic links) will be sent. Only alphanumeric values are allowed. Note that this value should contain only the local part of the address (e.g. `foo` for `foo@example.com`). nullable: true progressive_sign_up: type: boolean description: Enable the Progressive Sign Up algorithm. Refer to the [docs](https://clerk.com/docs/upgrade-guides/progressive-sign-up) for more info. nullable: true session_token_template: type: string description: The name of the JWT Template used to augment your session tokens. To disable this, pass an empty string. nullable: true enhanced_email_deliverability: type: boolean description: |- The "enhanced_email_deliverability" feature will send emails from "verifications@clerk.dev" instead of your domain. This can be helpful if you do not have a high domain reputation. nullable: true test_mode: type: boolean description: |- Toggles test mode for this instance, allowing the use of test email addresses and phone numbers. Defaults to true for development instances. nullable: true responses: "200": "$ref": "#/components/responses/InstanceSettings" "402": "$ref": "#/components/responses/PaymentRequired" "422": "$ref": "#/components/responses/UnprocessableEntity" "/beta_features/domain": put: operationId: UpdateProductionInstanceDomain summary: Update production instance domain description: |- Change the domain of a production instance. Changing the domain requires updating the [DNS records](https://clerk.com/docs/deployments/overview#dns-records) accordingly, deploying new [SSL certificates](https://clerk.com/docs/deployments/overview#deploy), updating your Social Connection's redirect URLs and setting the new keys in your code. WARNING: Changing your domain will invalidate all current user sessions (i.e. users will be logged out). Also, while your application is being deployed, a small downtime is expected to occur. tags: - Beta Features requestBody: content: application/json: schema: type: object additionalProperties: false properties: home_url: type: string description: The new home URL of the production instance e.g. https://www.example.com responses: "202": description: Accepted "400": "$ref": "#/components/responses/ClerkErrors" "422": "$ref": "#/components/responses/ClerkErrors" "/actor_tokens": post: summary: Create actor token description: Create an actor token that can be used to impersonate the given user. operationId: CreateActorToken tags: - Actor Tokens requestBody: content: application/json: schema: type: object additionalProperties: false properties: user_id: type: string description: The ID of the user that can use the newly created sign in token. actor: type: object description: |- The actor payload. It needs to include a sub property which should contain the ID of the actor. This whole payload will be also included in the JWT session token. expires_in_seconds: type: integer description: |- Optional parameter to specify the life duration of the actor token in seconds. By default, the duration is 1 hour. default: 3600 session_max_duration_in_seconds: type: integer description: |- The maximum duration that the session which will be created by the generated actor token should last. By default, the duration of a session created via an actor token, lasts 30 minutes. default: 1800 required: - user_id - actor responses: "200": "$ref": "#/components/responses/ActorToken" "400": "$ref": "#/components/responses/ClerkErrors" "402": "$ref": "#/components/responses/PaymentRequired" "422": "$ref": "#/components/responses/UnprocessableEntity" "/actor_tokens/{actor_token_id}/revoke": post: summary: Revoke actor token description: Revokes a pending actor token. operationId: RevokeActorToken tags: - Actor Tokens parameters: - name: actor_token_id in: path description: The ID of the actor token to be revoked. required: true schema: type: string responses: "200": "$ref": "#/components/responses/ActorToken" "400": "$ref": "#/components/responses/ClerkErrors" "404": "$ref": "#/components/responses/ResourceNotFound" "/instance": patch: operationId: UpdateInstance summary: Update instance settings description: Updates the settings of an instance tags: - Instance Settings requestBody: content: application/json: schema: type: object additionalProperties: false properties: test_mode: type: boolean description: |- Toggles test mode for this instance, allowing the use of test email addresses and phone numbers. Defaults to true for development instances. nullable: true hibp: type: boolean description: Whether the instance should be using the HIBP service to check passwords for breaches nullable: true enhanced_email_deliverability: type: boolean description: |- The "enhanced_email_deliverability" feature will send emails from "verifications@clerk.dev" instead of your domain. This can be helpful if you do not have a high domain reputation. nullable: true support_email: type: string nullable: true clerk_js_version: type: string nullable: true development_origin: type: string nullable: true experimental_allowed_origins: type: array items: type: string deprecated: true allowed_origins: type: array items: type: string cookieless_dev: type: boolean description: |- Whether the instance should operate in cookieless development mode (i.e. without third-party cookies). Deprecated: Please use `url_based_session_syncing` instead. deprecated: 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). responses: "204": description: Accepted "422": "$ref": "#/components/responses/UnprocessableEntity" "/instance/restrictions": patch: operationId: UpdateInstanceRestrictions summary: Update instance restrictions description: Updates the restriction settings of an instance tags: - Instance Settings requestBody: content: application/json: schema: type: object additionalProperties: false properties: allowlist: type: boolean nullable: true blocklist: type: boolean nullable: true responses: "200": "$ref": "#/components/responses/InstanceRestrictions" "402": "$ref": "#/components/responses/PaymentRequired" "/instance/organization_settings": patch: operationId: UpdateInstanceOrganizationSettings summary: Update instance organization settings description: Updates the organization settings of the instance tags: - Instance Settings requestBody: content: application/json: schema: type: object additionalProperties: false properties: enabled: type: boolean nullable: true max_allowed_memberships: type: integer nullable: true responses: "200": "$ref": "#/components/responses/OrganizationSettings" "422": "$ref": "#/components/responses/UnprocessableEntity" "/webhooks/svix": post: operationId: CreateSvixApp summary: Create a Svix app description: Create a Svix app and associate it with the current instance tags: - Webhooks responses: "200": "$ref": "#/components/responses/SvixURL" "400": "$ref": "#/components/responses/ClerkErrors" delete: operationId: DeleteSvixApp summary: Delete a Svix app description: Delete a Svix app and disassociate it from the current instance tags: - Webhooks responses: "204": description: Svix app was successfully deleted "400": "$ref": "#/components/responses/ClerkErrors" "/webhooks/svix_url": post: operationId: GenerateSvixAuthURL summary: Create a Svix Dashboard URL description: Generate a new url for accessing the Svix's management dashboard for that particular instance tags: - Webhooks responses: "200": "$ref": "#/components/responses/SvixURL" "400": "$ref": "#/components/responses/ClerkErrors" "/jwt_templates": get: summary: List all templates operationId: ListJWTTemplates tags: - JWT Templates responses: "200": "$ref": "#/components/responses/JWTTemplate.List" post: operationId: CreateJWTTemplate summary: Create a JWT template description: Create a new JWT template tags: - JWT Templates requestBody: content: application/json: schema: type: object properties: name: type: string description: JWT template name nullable: false claims: type: object description: JWT template claims in JSON format nullable: false lifetime: type: number minimum: 30 maximum: 315360000 description: JWT token lifetime nullable: true allowed_clock_skew: type: number minimum: 0 maximum: 300 description: JWT token allowed clock skew nullable: true custom_signing_key: type: boolean description: Whether a custom signing key/algorithm is also provided for this template nullable: false signing_algorithm: type: string description: The custom signing algorithm to use when minting JWTs nullable: true signing_key: type: string description: The custom signing private key to use when minting JWTs nullable: true responses: "200": "$ref": "#/components/responses/JWTTemplate" "400": "$ref": "#/components/responses/ClerkErrors" "402": "$ref": "#/components/responses/PaymentRequired" "422": "$ref": "#/components/responses/UnprocessableEntity" "/jwt_templates/{template_id}": get: operationId: GetJWTTemplate summary: Retrieve a template description: Retrieve the details of a given JWT template tags: - JWT Templates parameters: - name: template_id in: path description: JWT Template ID required: true schema: type: string responses: "200": "$ref": "#/components/responses/JWTTemplate" "404": "$ref": "#/components/responses/ResourceNotFound" patch: operationId: UpdateJWTTemplate summary: Update a JWT template description: Updates an existing JWT template tags: - JWT Templates parameters: - name: template_id in: path description: The ID of the JWT template to update required: true schema: type: string requestBody: content: application/json: schema: type: object properties: name: type: string description: JWT template name nullable: false claims: type: object description: JWT template claims in JSON format nullable: false lifetime: type: number minimum: 30 maximum: 315360000 description: JWT token lifetime nullable: true allowed_clock_skew: type: number minimum: 0 maximum: 300 description: JWT token allowed clock skew nullable: true custom_signing_key: type: boolean description: Whether a custom signing key/algorithm is also provided for this template nullable: false signing_algorithm: type: string description: The custom signing algorithm to use when minting JWTs nullable: true signing_key: type: string description: The custom signing private key to use when minting JWTs nullable: true responses: "200": "$ref": "#/components/responses/JWTTemplate" "400": "$ref": "#/components/responses/ClerkErrors" "402": "$ref": "#/components/responses/PaymentRequired" "422": "$ref": "#/components/responses/UnprocessableEntity" delete: operationId: DeleteJWTTemplate summary: Delete a Template description: "" tags: - JWT Templates parameters: - name: template_id in: path description: JWT Template ID required: true schema: type: string responses: "200": "$ref": "#/components/responses/DeletedObject" "403": "$ref": "#/components/responses/AuthorizationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "/organizations": get: operationId: ListOrganizations summary: Get a list of organizations for an instance description: |- This request returns the list of organizations for an instance. Results can be paginated using the optional `limit` and `offset` query parameters. The organizations are ordered by descending creation date. Most recent organizations will be returned first. tags: - Organizations parameters: - "$ref": "#/components/parameters/LimitParameter" - "$ref": "#/components/parameters/OffsetParameter" - in: query required: false name: include_members_count description: Flag to denote whether the member counts of each organization should be included in the response or not. schema: type: boolean - in: query required: false name: query description: |- Returns organizations with ID, name, or slug that match the given query. Uses exact match for organization ID and partial match for name and slug. schema: type: string responses: "200": "$ref": "#/components/responses/Organizations" "400": "$ref": "#/components/responses/ClerkErrors" "403": "$ref": "#/components/responses/AuthorizationInvalid" "422": "$ref": "#/components/responses/UnprocessableEntity" post: operationId: CreateOrganization summary: Create an organization description: |- Creates a new organization with the given name for an instance. In order to successfully create an organization you need to provide the ID of the User who will become the organization administrator. You can specify an optional slug for the new organization. If provided, the organization slug can contain only lowercase alphanumeric characters (letters and digits) and the dash "-". Organization slugs must be unique for the instance. You can provide additional metadata for the organization and set any custom attribute you want. Organizations support private and public metadata. Private metadata can only be accessed from the Backend API. Public metadata can be accessed from the Backend API, and are read-only from the Frontend API. tags: - Organizations requestBody: content: application/json: schema: type: object properties: name: type: string description: The name of the new organization created_by: type: string description: The ID of the User who will become the administrator for the new organization private_metadata: type: object description: Metadata saved on the organization, accessible only from the Backend API 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 slug: type: string description: |- A slug for the new organization. Can contain only lowercase alphanumeric characters and the dash "-". Must be unique for the instance. max_allowed_memberships: type: integer description: The maximum number of memberships allowed for this organization required: - name - created_by responses: "200": "$ref": "#/components/responses/Organization" "400": "$ref": "#/components/responses/ClerkErrors" "403": "$ref": "#/components/responses/AuthorizationInvalid" "422": "$ref": "#/components/responses/UnprocessableEntity" "/organizations/{organization_id}": get: operationId: GetOrganization summary: Retrieve an organization by ID or slug description: Fetches the organization whose ID or slug matches the provided `id_or_slug` URL query parameter. tags: - Organizations parameters: - in: path name: organization_id required: true schema: type: string description: The ID or slug of the organization responses: "200": "$ref": "#/components/responses/Organization" "403": "$ref": "#/components/responses/AuthorizationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" patch: operationId: UpdateOrganization summary: Update an organization description: Updates an existing organization tags: - Organizations parameters: - in: path name: organization_id required: true schema: type: string description: The ID of the organization to update requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: 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. name: type: string description: The new name of the organization nullable: true slug: type: string description: The new slug of the organization, which needs to be unique in the instance nullable: true max_allowed_memberships: type: integer description: The maximum number of memberships allowed for this organization nullable: true responses: "200": "$ref": "#/components/responses/Organization" "404": "$ref": "#/components/responses/ResourceNotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" delete: operationId: DeleteOrganization summary: Delete an organization description: |- Deletes the given organization. Please note that deleting an organization will also delete all memberships and invitations. This is not reversible. tags: - Organizations parameters: - in: path name: organization_id required: true schema: type: string description: The ID of the organization to delete responses: "200": "$ref": "#/components/responses/DeletedObject" "404": "$ref": "#/components/responses/ResourceNotFound" "/organizations/{organization_id}/metadata": patch: operationId: MergeOrganizationMetadata summary: Merge and update metadata for an organization description: |- 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`. tags: - Organizations parameters: - name: organization_id in: path description: The ID of the organization for which metadata will be merged or updated required: true schema: type: string requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: public_metadata: type: object description: |- Metadata saved on the organization, that is visible to both your frontend and backend. The 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. The new object will be merged with the existing value. responses: "200": "$ref": "#/components/responses/Organization" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" "/organizations/{organization_id}/logo": put: operationId: UploadOrganizationLogo summary: Upload a logo for the organization description: |- Set or replace an organization's logo, by uploading an image file. This endpoint uses the `multipart/form-data` request content type and accepts a file of image type. The file size cannot exceed 10MB. Only the following file content types are supported: `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `image/x-icon`, `image/vnd.microsoft.icon`. tags: - Organizations parameters: - name: organization_id in: path description: The ID of the organization for which to upload a logo required: true schema: type: string requestBody: content: multipart/form-data: schema: type: object properties: uploader_user_id: type: string file: type: string format: binary responses: "200": "$ref": "#/components/responses/OrganizationWithLogo" "400": "$ref": "#/components/responses/ClerkErrors" "403": "$ref": "#/components/responses/AuthorizationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "413": "$ref": "#/components/responses/ClerkErrors" "/organizations/{organization_id}/invitations": post: operationId: CreateOrganizationInvitation summary: Create and send an organization invitation description: |- Creates a new organization invitation and sends an email to the provided `email_address` with a link to accept the invitation and join the organization. You can specify the `role` for the invited organization member. New organization invitations get a "pending" status until they are revoked by an organization administrator or accepted by the invitee. The request body supports passing an optional `redirect_url` parameter. When the invited user clicks the link to accept the invitation, they will be redirected to the URL provided. Use this parameter to implement a custom invitation acceptance flow. You must specify the ID of the user that will send the invitation with the `inviter_user_id` parameter. That user must be a member with administrator privileges in the organization. Only "admin" members can create organization invitations. You can optionally provide public metadata for the organization invitation. These metadata are visible by both the Frontend and the Backend. When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership. tags: - Organization Invitations parameters: - in: path required: true name: organization_id schema: type: string description: The ID of the organization for which to send the invitation requestBody: required: true content: application/json: schema: type: object properties: 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. Must be an administrator in the organization. role: type: string description: The role of the new member in the organization enum: - admin - basic_member 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. 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. required: - email_address - inviter_user_id - role responses: "200": "$ref": "#/components/responses/OrganizationInvitation" "400": "$ref": "#/components/responses/ClerkErrors" "403": "$ref": "#/components/responses/AuthorizationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" "/organizations/{organization_id}/invitations/pending": get: operationId: ListPendingOrganizationInvitations summary: Get a list of pending organization invitations description: |- This request returns the list of organization invitations with "pending" status. These are the organization invitations that can still be used to join the organization, but have not been accepted by the invited user yet. Results can be paginated using the optional `limit` and `offset` query parameters. The organization invitations are ordered by descending creation date. Most recent invitations will be returned first. tags: - Organization Invitations parameters: - in: path required: true name: organization_id schema: type: string description: The organization ID. - "$ref": "#/components/parameters/LimitParameter" - "$ref": "#/components/parameters/OffsetParameter" responses: "200": "$ref": "#/components/responses/OrganizationInvitations" "400": "$ref": "#/components/responses/ClerkErrors" "404": "$ref": "#/components/responses/ResourceNotFound" "/organizations/{organization_id}/invitations/{invitation_id}/revoke": post: operationId: RevokeOrganizationInvitation summary: Revoke a pending organization invitation description: |- Use this request to revoke a previously issued organization invitation. Revoking an organization invitation makes it invalid; the invited user will no longer be able to join the organization with the revoked invitation. Only organization invitations with "pending" status can be revoked. The request needs the `requesting_user_id` parameter to specify the user which revokes the invitation. Only users with "admin" role can revoke invitations. tags: - Organization Invitations parameters: - in: path required: true name: organization_id schema: type: string description: The organization ID. - in: path required: true name: invitation_id schema: type: string description: The organization invitation ID. requestBody: required: true content: application/json: schema: type: object properties: requesting_user_id: type: string description: |- The ID of the user that revokes the invitation. Must be an administrator in the organization. required: - requesting_user_id responses: "200": "$ref": "#/components/responses/OrganizationInvitation" "400": "$ref": "#/components/responses/ClerkErrors" "403": "$ref": "#/components/responses/AuthorizationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "/organizations/{organization_id}/memberships": post: operationId: CreateOrganizationMembership summary: Create a new organization membership description: |- Adds a user as a member to the given organization. Only users in the same instance as the organization can be added as members. tags: - Organization Memberships parameters: - in: path required: true name: organization_id schema: type: string description: The ID of the organization where the new membership will be created requestBody: required: true content: application/json: schema: type: object properties: user_id: type: string description: |- The ID of the user that will be added as a member in the organization. The user needs to exist in the same instance as the organization and must not be a member of the given organization already. role: type: string description: The role that the new member will have in the organization. enum: - admin - basic_member required: - user_id - role responses: "200": "$ref": "#/components/responses/OrganizationMembership" "400": "$ref": "#/components/responses/ClerkErrors" "403": "$ref": "#/components/responses/AuthorizationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" get: operationId: ListOrganizationMemberships summary: Get a list of all members of an organization description: Retrieves all user memberships for the given organization tags: - Organization Memberships parameters: - in: path required: true name: organization_id schema: type: string description: The organization ID. - "$ref": "#/components/parameters/LimitParameter" - "$ref": "#/components/parameters/OffsetParameter" responses: "200": "$ref": "#/components/responses/OrganizationMemberships" "401": "$ref": "#/components/responses/AuthenticationInvalid" "422": "$ref": "#/components/responses/UnprocessableEntity" "/organizations/{organization_id}/memberships/{user_id}": patch: operationId: UpdateOrganizationMembership summary: Update an organization membership description: Updates the properties of an existing organization membership tags: - Organization Memberships parameters: - in: path required: true name: organization_id schema: type: string description: The ID of the organization the membership belongs to - in: path required: true name: user_id schema: type: string description: The ID of the user that this membership belongs to requestBody: required: true content: application/json: schema: type: object properties: role: type: string description: The new role of the given membership. enum: - admin - basic_member required: - role responses: "200": "$ref": "#/components/responses/OrganizationMembership" "400": "$ref": "#/components/responses/ClerkErrors" "404": "$ref": "#/components/responses/ResourceNotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" delete: operationId: DeleteOrganizationMembership summary: Remove a member from an organization description: Removes the given membership from the organization tags: - Organization Memberships parameters: - in: path required: true name: organization_id schema: type: string description: The ID of the organization the membership belongs to - in: path required: true name: user_id schema: type: string description: The ID of the user that this membership belongs to responses: "200": "$ref": "#/components/responses/OrganizationMembership" "400": "$ref": "#/components/responses/ClerkErrors" "401": "$ref": "#/components/responses/AuthenticationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "/organizations/{organization_id}/memberships/{user_id}/metadata": patch: operationId: UpdateOrganizationMembershipMetadata summary: Merge and update organization membership metadata description: |- 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`. tags: - Organization Memberships parameters: - in: path required: true name: organization_id schema: type: string description: The ID of the organization the membership belongs to - in: path required: true name: user_id schema: type: string description: The ID of the user that this membership belongs to requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: public_metadata: type: object description: |- Metadata saved on the organization membership, that is visible to both your frontend and backend. The 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. The new object will be merged with the existing value. responses: "200": "$ref": "#/components/responses/OrganizationMembership" "400": "$ref": "#/components/responses/ClerkErrors" "404": "$ref": "#/components/responses/ResourceNotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" "/redirect_urls": get: summary: List all redirect URLs description: Lists all whitelisted redirect_urls for the instance operationId: ListRedirectURLs tags: - Redirect URLs responses: "200": "$ref": "#/components/responses/RedirectURL.List" post: description: Create a redirect URL operationId: CreateRedirectURL tags: - Redirect URLs requestBody: content: application/json: schema: type: object properties: url: type: string 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"` nullable: false responses: "200": "$ref": "#/components/responses/RedirectURL" "400": "$ref": "#/components/responses/ClerkErrors" "422": "$ref": "#/components/responses/UnprocessableEntity" "/redirect_urls/{id}": get: summary: Retrieve a redirect URL description: Retrieve the details of the redirect URL with the given ID operationId: GetRedirectURL tags: - Redirect URLs parameters: - name: id in: path description: The ID of the redirect URL required: true schema: type: string responses: "200": "$ref": "#/components/responses/RedirectURL" "404": "$ref": "#/components/responses/ResourceNotFound" delete: summary: Delete a redirect URL description: Remove the selected redirect URL from the whitelist of the instance operationId: DeleteRedirectURL tags: - Redirect URLs parameters: - name: id in: path description: The ID of the redirect URL required: true schema: type: string responses: "200": "$ref": "#/components/responses/DeletedObject" "404": "$ref": "#/components/responses/ResourceNotFound" "/sign_in_tokens": post: summary: Create sign-in token description: |- Creates a new sign-in token and associates it with the given user. By default, sign-in tokens expire in 30 days. You can optionally supply a different duration in seconds using the `expires_in_seconds` property. operationId: CreateSignInToken tags: - Sign-in Tokens requestBody: content: application/json: schema: 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 description: |- Optional parameter to specify the life duration of the sign in token in seconds. By default, the duration is 30 days. default: 2592000 responses: "200": "$ref": "#/components/responses/SignInToken" "404": "$ref": "#/components/responses/ResourceNotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" "/sign_in_tokens/{sign_in_token_id}/revoke": post: summary: Revoke the given sign-in token description: Revokes a pending sign-in token operationId: RevokeSignInToken tags: - Sign-in Tokens parameters: - name: sign_in_token_id in: path description: The ID of the sign-in token to be revoked required: true schema: type: string responses: "200": "$ref": "#/components/responses/SignInToken" "400": "$ref": "#/components/responses/ClerkErrors" "404": "$ref": "#/components/responses/ResourceNotFound" "/sign_ups/{id}": patch: operationId: UpdateSignUp summary: Update a sign-up description: Update the sign-up with the given ID tags: - Sign-ups parameters: - name: id in: path description: The ID of the sign-up to update required: true schema: type: string requestBody: content: application/json: schema: type: object properties: custom_action: type: boolean description: |- Specifies whether a custom action has run for this sign-up attempt. This is important when your instance has been configured to require a custom action to run before converting a sign-up into a user. After executing any external business logic you deem necessary, you can mark the sign-up as ready-to-convert by setting `custom_action` to `true`. external_id: type: string description: |- The ID of the guest attempting to sign up as used in your external systems or your previous authentication solution. This will be copied to the resulting user when the sign-up is completed. nullable: true responses: "200": "$ref": "#/components/responses/SignUp" "403": "$ref": "#/components/responses/AuthorizationInvalid" "/oauth_applications": get: operationId: ListOAuthApplications summary: Get a list of OAuth applications for an instance description: |- This request returns the list of OAuth applications for an instance. Results can be paginated using the optional `limit` and `offset` query parameters. The OAuth applications are ordered by descending creation date. Most recent OAuth applications will be returned first. tags: - OAuth Applications parameters: - "$ref": "#/components/parameters/LimitParameter" - "$ref": "#/components/parameters/OffsetParameter" responses: "200": "$ref": "#/components/responses/OAuthApplications" "400": "$ref": "#/components/responses/ClerkErrors" "403": "$ref": "#/components/responses/AuthorizationInvalid" "422": "$ref": "#/components/responses/UnprocessableEntity" post: operationId: CreateOAuthApplication summary: Create an OAuth application description: |- Creates a new OAuth application with the given name and callback URL for an instance. The callback URL must be a valid url. All URL schemes are allowed such as `http://`, `https://`, `myapp://`, etc... tags: - OAuth Applications requestBody: content: application/json: schema: type: object properties: name: type: string description: The name of the new OAuth application callback_url: type: string description: The callback URL of the new OAuth application required: - name - callback_url responses: "200": "$ref": "#/components/responses/OAuthApplicationWithSecret" "400": "$ref": "#/components/responses/ClerkErrors" "403": "$ref": "#/components/responses/AuthorizationInvalid" "422": "$ref": "#/components/responses/UnprocessableEntity" "/oauth_applications/{oauth_application_id}": get: operationId: GetOAuthApplication summary: Retrieve an OAuth application by ID description: Fetches the OAuth application whose ID matches the provided `id` in the path. tags: - OAuth Applications parameters: - in: path name: oauth_application_id required: true schema: type: string description: The ID of the OAuth application responses: "200": "$ref": "#/components/responses/OAuthApplication" "403": "$ref": "#/components/responses/AuthorizationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" patch: operationId: UpdateOAuthApplication summary: Update an OAuth application description: Updates an existing OAuth application tags: - OAuth Applications parameters: - in: path name: oauth_application_id required: true schema: type: string description: The ID of the OAuth application to update requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: name: type: string description: The new name of the OAuth application callback_url: type: string description: The new callback URL of the OAuth application required: - name - callback_url responses: "200": "$ref": "#/components/responses/OAuthApplication" "403": "$ref": "#/components/responses/AuthorizationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "422": "$ref": "#/components/responses/UnprocessableEntity" delete: operationId: DeleteOAuthApplication summary: Delete an OAuth application description: |- Deletes the given OAuth application. This is not reversible. tags: - OAuth Applications parameters: - in: path name: oauth_application_id required: true schema: type: string description: The ID of the OAuth application to delete responses: "200": "$ref": "#/components/responses/DeletedObject" "403": "$ref": "#/components/responses/AuthorizationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound" "/oauth_applications/{oauth_application_id}/rotate_secret": post: operationId: RotateOAuthApplicationSecret summary: Rotate the client secret of the given OAuth application description: |- Rotates the OAuth application's client secret. When the client secret is rotated, make sure to update it in authorized OAuth clients. tags: - OAuth Applications parameters: - name: oauth_application_id in: path description: The ID of the OAuth application for which to rotate the client secret required: true schema: type: string responses: "200": "$ref": "#/components/responses/OAuthApplicationWithSecret" "403": "$ref": "#/components/responses/AuthorizationInvalid" "404": "$ref": "#/components/responses/ResourceNotFound"