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. ### Versions When the API changes in a way that isn''t compatible with older versions, a new version is released. Each version is identified by its release date, e.g. `2025-04-10`. For more information, please see [Clerk API Versions](https://clerk.com/docs/versioning/available-versions). Please see https://clerk.com/docs for more information.' version: '2025-11-10' termsOfService: https://clerk.com/terms license: name: MIT url: https://github.com/clerk/openapi-specs/blob/main/LICENSE servers: - url: https://api.clerk.com/v1 security: - bearerAuth: [] 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/references/javascript/client - name: Billing description: Billing-related endpoints for managing statements and payment attempts. externalDocs: url: https://clerk.com/docs/billing/overview - name: Domains description: Domains represent each instance's URLs and DNS setup. - name: Email Addresses description: A user can be associated with one or more email addresses, which allows them to be contacted via email. externalDocs: url: https://clerk.com/docs/references/javascript/types/email-address - 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: OAuth Access Tokens description: Endpoints for managing OAuth Access Tokens, which are credentials to access protected resources on behalf of a user. - 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: Organization Permissions description: Manage organization permissions that define what members can do within an organization. externalDocs: url: https://clerk.com/docs/organizations/manage-member-roles - name: Organization Roles description: Manage custom roles in an organization. externalDocs: url: https://clerk.com/docs/organizations/manage-member-roles - name: Role Sets description: 'Role sets define collections of roles that can be assigned to organization members. Each organization uses one role set to determine the available roles for its members. Role sets support default roles for new members and creator roles for organization founders.' externalDocs: url: https://clerk.com/docs/organizations/manage-member-roles - name: Phone Numbers description: A user can be associated with one or more phone numbers, which allows them to be contacted via SMS. externalDocs: url: https://clerk.com/docs/references/javascript/types/phone-number - 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: SAML Connections description: 'A SAML Connection holds configuration data required for facilitating a SAML SSO flow between your Clerk Instance (SP) and a particular SAML IdP.' - name: Enterprise Connections description: 'An Enterprise Connection holds configuration data required for facilitating an enterprise SSO flow between your Clerk instance and an identity provider.' externalDocs: url: https://clerk.com/docs/guides/configure/auth-strategies/enterprise-connections/overview - 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/references/javascript/session - name: Machines description: A Machine represents a machine/server/service which can be used in machine-to-machine authentication. - name: M2M Tokens description: Machine to Machine Tokens are used to manage authentication between Machines. - name: API Keys description: Endpoints for managing API Keys - 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: Sign Ups description: Sign-up objects track the progress of a sign-up attempt and store any field collected from user input. externalDocs: url: https://clerk.com/docs/references/javascript/sign-up - name: Testing Tokens description: Tokens meant for use by end-to-end test suites in requests to the Frontend API, so as to bypass bot detection measures. externalDocs: url: https://clerk.com/docs/testing/overview#testing-tokens - name: Agent Tasks description: Tasks that allow creating user sessions for agent-based interactions. - name: Users description: The user object represents a user that has successfully signed up to your application. externalDocs: url: https://clerk.com/docs/references/javascript/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. - name: Waitlist Entries description: Manage waitlist entries. - name: Proxy Checks description: Check if a user is using a proxy. - name: Organization Domains description: Manage organization domains. - name: Accountless Applications description: Create and complete accountless applications. Note that this is an experimental feature and subject to change or be removed without notice. externalDocs: url: https://clerk.com/docs paths: /public/interstitial: get: operationId: GetPublicInterstitial x-speakeasy-group: miscellaneous x-speakeasy-name-override: getPublicInterstitial 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.' tags: - Miscellaneous parameters: - name: frontendApi deprecated: true in: query required: false description: Please use `frontend_api` instead schema: type: string - name: frontend_api 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 - name: proxy_url in: query required: false description: The proxy URL of your instance schema: type: string - name: domain in: query required: false description: The domain of your instance schema: type: string - name: sign_in_url in: query required: false description: The sign in URL of your instance schema: type: string - name: use_domain_for_script in: query required: false description: Whether to use the domain for the script URL schema: type: boolean responses: '200': description: The interstitial page markup '400': description: A required query parameter is missing '500': description: An infinite redirect loop was detected /jwks: get: operationId: GetJWKS x-speakeasy-group: jwks x-speakeasy-name-override: 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': $ref: '#/components/responses/WellKnown.JWKS' /aws_credentials: {} /aws_credentials/{id}: {} /clients: get: deprecated: true operationId: GetClientList x-speakeasy-group: clients x-speakeasy-name-override: list 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. Warning: the endpoint is being deprecated and will be removed in future versions.' parameters: - $ref: '#/components/parameters/Paginated' - $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' '410': $ref: '#/components/responses/DeprecatedEndpoint' '422': $ref: '#/components/responses/UnprocessableEntity' /clients/verify: post: operationId: VerifyClient x-speakeasy-group: clients x-speakeasy-name-override: verify 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 that represents the active client. required: - token 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 x-speakeasy-group: clients x-speakeasy-name-override: get 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/handshake_payload: {} /email_addresses: post: operationId: CreateEmailAddress x-speakeasy-group: emailAddresses x-speakeasy-name-override: create 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 required: - user_id - email_address 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' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' /email_addresses/{email_address_id}: get: operationId: GetEmailAddress x-speakeasy-group: emailAddresses x-speakeasy-name-override: get x-speakeasy-usage-example: true 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 x-speakeasy-group: emailAddresses x-speakeasy-name-override: delete 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' '409': $ref: '#/components/responses/Conflict' patch: operationId: UpdateEmailAddress x-speakeasy-group: emailAddresses x-speakeasy-name-override: update 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' '409': $ref: '#/components/responses/Conflict' /phone_numbers: post: operationId: CreatePhoneNumber x-speakeasy-group: phoneNumbers x-speakeasy-name-override: create 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 reserved_for_second_factor: type: boolean description: 'Create this phone number as reserved for multi-factor authentication. The phone number must also be verified. If there are no other reserved second factors, the phone number will be set as the default second factor.' nullable: true required: - user_id - phone_number 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 x-speakeasy-group: phoneNumbers x-speakeasy-name-override: get 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 x-speakeasy-group: phoneNumbers x-speakeasy-name-override: delete 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 x-speakeasy-group: phoneNumbers x-speakeasy-name-override: update 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 reserved_for_second_factor: type: boolean description: 'Set this phone number as reserved for multi-factor authentication. The phone number must also be verified. If there are no other reserved second factors, the phone number will be set as the default second factor.' 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 x-speakeasy-group: sessions x-speakeasy-name-override: list tags: - Sessions summary: List All Sessions description: 'Returns a list of sessions matching the provided criteria. The sessions are returned sorted by creation date, with the newest sessions appearing first. Note: This endpoint does not return all sessions that have ever existed. Old and inactive sessions are periodically cleaned up and will not be included in the results. **Deprecation Notice (2024-01-01):** All parameters were initially considered optional, however moving forward at least one of `client_id` or `user_id` parameters should be provided.' 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/Paginated' - $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' post: operationId: createSession x-speakeasy-group: sessions x-speakeasy-name-override: create tags: - Sessions summary: Create a New Active Session description: 'Create a new active session for the provided user ID. **This operation is intended only for use in testing, and is not available for production instances.** If you are looking to generate a user session from the backend, we recommend using the [Sign-in Tokens](https://clerk.com/docs/reference/backend-api/tag/Sign-in-Tokens#operation/CreateSignInToken) resource instead.' requestBody: content: application/json: schema: type: object properties: user_id: type: string description: The ID representing the user active_organization_id: type: string description: The ID of the organization to set as active for this session required: - user_id responses: '200': $ref: '#/components/responses/Session' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/UnprocessableEntity' /sessions/{session_id}: get: operationId: GetSession x-speakeasy-group: sessions x-speakeasy-name-override: get 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}/refresh: post: operationId: RefreshSession x-speakeasy-group: sessions x-speakeasy-name-override: refresh tags: - Sessions summary: Refresh a Session description: 'Refreshes a session by creating a new session token. A 401 is returned when there are validation errors, which signals the SDKs to fall back to the handshake flow.' parameters: - name: session_id in: path description: The ID of the session required: true schema: type: string requestBody: description: Refresh session parameters content: application/json: schema: type: object additionalProperties: false properties: expired_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.' refresh_token: type: string description: The refresh token from the `__refresh` cookie set via FAPI's handshake flow. request_origin: type: string description: The origin of the request. request_headers: type: object additionalProperties: true description: The headers of the request. nullable: true format: type: string description: The format of the response. nullable: true default: token enum: - token - cookie request_originating_ip: type: string description: The IP address of the request. nullable: true required: - expired_token - refresh_token - request_origin responses: '200': $ref: '#/components/responses/Session.Refresh' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' /sessions/{session_id}/revoke: post: operationId: RevokeSession x-speakeasy-group: sessions x-speakeasy-name-override: revoke 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}/tokens: post: operationId: CreateSessionToken x-speakeasy-group: sessions x-speakeasy-name-override: createToken tags: - Sessions summary: Create a Session Token description: Creates a session JSON Web Token (JWT) based on a session. parameters: - name: session_id in: path description: The ID of the session required: true schema: type: string requestBody: content: application/json: schema: type: object properties: expires_in_seconds: type: integer minimum: 30 maximum: 315360000 description: Use this parameter to override the default session token lifetime. nullable: true 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' /sessions/{session_id}/tokens/{template_name}: post: operationId: CreateSessionTokenFromTemplate x-speakeasy-group: sessions x-speakeasy-name-override: createTokenFromTemplate 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 requestBody: content: application/json: schema: type: object properties: expires_in_seconds: type: integer minimum: 30 maximum: 315360000 description: Use this parameter to override the JWT lifetime. nullable: true 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: deprecated: true operationId: GetTemplateList x-speakeasy-group: emailSMSTemplates x-speakeasy-name-override: list 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 - $ref: '#/components/parameters/Paginated' - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' 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: deprecated: true operationId: GetTemplate x-speakeasy-group: emailSMSTemplates x-speakeasy-name-override: get 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: deprecated: true operationId: UpsertTemplate x-speakeasy-group: emailAndSmsTemplates x-speakeasy-name-override: upsert 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.' reply_to_email_name: type: string description: 'The local part of the Reply To 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' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /templates/{template_type}/{slug}/revert: post: deprecated: true operationId: RevertTemplate x-speakeasy-group: emailSMSTemplates x-speakeasy-name-override: revert 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: deprecated: true operationId: PreviewTemplate x-speakeasy-group: templates x-speakeasy-name-override: preview 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.' reply_to_email_name: type: string description: 'The local part of the Reply To 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' /templates/{template_type}/{slug}/toggle_delivery: post: deprecated: true operationId: ToggleTemplateDelivery x-speakeasy-group: emailSMSTemplates x-speakeasy-name-override: toggleTemplateDelivery summary: Toggle the Delivery by Clerk for a Template of a Given Type and Slug description: 'Toggles the delivery by Clerk for a template of a given type and slug. If disabled, Clerk will not deliver the resulting email or SMS. The app developer will need to listen to the `email.created` or `sms.created` webhooks in order to handle delivery themselves.' tags: - Email & SMS Templates parameters: - name: template_type in: path description: The type of template to toggle delivery for required: true schema: type: string enum: - email - sms - name: slug in: path description: The slug of the template for which to toggle delivery required: true schema: type: string requestBody: content: application/json: schema: type: object additionalProperties: false properties: delivered_by_clerk: type: boolean description: Whether Clerk should deliver emails or SMS messages based on the current template responses: '200': $ref: '#/components/responses/Template' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' /users: get: operationId: GetUserList x-speakeasy-group: users x-speakeasy-name-override: list 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 addresses 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 - name: email_address_query in: query description: 'Returns users with emails that match the given query, via case-insensitive partial match. For example, `email_address_query=ello` will match a user with the email `HELLO@example.com`.' schema: type: string required: false - name: phone_number_query in: query description: 'Returns users with phone numbers that match the given query, via case-insensitive partial match. For example, `phone_number_query=555` will match a user with the phone number `+1555xxxxxxx`.' schema: type: string required: false - name: username_query in: query description: 'Returns users with usernames that match the given query, via case-insensitive partial match. For example, `username_query=CoolUser` will match a user with the username `SomeCoolUser`.' schema: type: string - name: name_query in: query description: Returns users with names that match the given query, via case-insensitive partial match. schema: type: string - name: banned in: query required: false description: Returns users which are either banned (`banned=true`) or not banned (`banned=false`). schema: type: boolean - name: last_active_at_before in: query description: 'Returns users whose last session activity was before the given date (with millisecond precision). Example: use 1700690400000 to retrieve users whose last session activity was before 2023-11-23.' example: 1700690400000 schema: type: integer - name: last_active_at_after in: query description: 'Returns users whose last session activity was after the given date (with millisecond precision). Example: use 1700690400000 to retrieve users whose last session activity was after 2023-11-23.' example: 1700690400000 schema: type: integer - name: last_active_at_since in: query deprecated: true description: 'Returns users that had session activity since the given date. Example: use 1700690400000 to retrieve users that had session activity from 2023-11-23 until the current day. Deprecated in favor of `last_active_at_after`.' example: 1700690400000 schema: type: integer - name: created_at_before in: query description: 'Returns users who have been created before the given date (with millisecond precision). Example: use 1730160000000 to retrieve users who have been created before 2024-10-29.' example: 1730160000000 schema: type: integer - name: created_at_after in: query description: 'Returns users who have been created after the given date (with millisecond precision). Example: use 1730160000000 to retrieve users who have been created after 2024-10-29.' example: 1730160000000 schema: type: integer - name: last_sign_in_at_before in: query description: 'Returns users whose last sign-in was before the given date (with millisecond precision). Example: use 1700690400000 to retrieve users whose last sign-in was before 2023-11-23.' example: 1700690400000 schema: type: integer - name: last_sign_in_at_after in: query description: 'Returns users whose last sign-in was after the given date (with millisecond precision). Example: use 1700690400000 to retrieve users whose last sign-in was after 2023-11-23.' example: 1700690400000 schema: type: integer - name: provider in: query schema: type: string description: 'Returns users with external accounts for the specified OAuth provider. Must be used in combination with the `provider_user_id` parameter. For example, use `provider=oauth_google&provider_user_id=12345` to retrieve a user with Google provider user ID 12345.' required: false - name: provider_user_id in: query schema: type: array items: type: string description: 'Returns users with the specified provider user IDs for a specific provider. Must be used in combination with the `provider` parameter. For example, use `provider=oauth_google&provider_user_id=12345` to retrieve a user with Google provider user ID 12345. Accepts up to 100 provider user IDs. Any provider user IDs not found are ignored.' 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 by their `created_at`,`updated_at`,`email_address`,`web3wallet`,`first_name`,`last_name`,`phone_number`,`username`,`last_active_at`,`last_sign_in_at`. In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. For example, if you want users to be returned in descending order according to their `created_at` property, you can use `-created_at`. If you don''t use `+` or `-`, then `+` is implied. We only support one `order_by` parameter, and if multiple `order_by` parameters are provided, we will only keep the first one. For example, if you pass `order_by=username&order_by=created_at`, we will consider only the first `order_by` parameter, which is `username`. The `created_at` parameter will be ignored in this case.' 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 x-speakeasy-group: users x-speakeasy-name-override: create 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/migrate-overview). The following rate limit rules apply to this endpoint: 1000 requests per 10 seconds for production instances and 100 requests per 10 seconds for development instances' 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 locale: type: string description: The locale to assign to the user (e.g., "en-US", "fr-FR") 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 cannot 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.' nullable: true password_hasher: $ref: '#/components/schemas/PasswordHasher' 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.' nullable: true 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.' 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 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' nullable: true 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 additionalProperties: true private_metadata: type: object description: Metadata saved on the user, that is only visible to your Backend API additionalProperties: true 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.' additionalProperties: true delete_self_enabled: type: boolean description: 'If enabled, user can delete themselves via FAPI. ' nullable: true legal_accepted_at: type: string description: A custom timestamp denoting _when_ the user accepted legal requirements, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`). nullable: true skip_legal_checks: type: boolean description: 'When set to `true` all legal checks are skipped. It is not recommended to skip legal checks unless you are migrating a user to Clerk.' nullable: true skip_user_requirement: type: boolean description: 'When set to `true`, identification types are not enforced. At least one identification type must be enabled and provided on your instance (email, phone, web3 wallet, or username). Users created without required identification types cannot use those authentication strategies It is not recommended to use this flag unless you need to allow Clerk UI components to prompt for required fields while BAPI creates users with minimal data, or for migration a user to Clerk.' nullable: true create_organization_enabled: type: boolean description: 'If enabled, user can create organizations via FAPI. ' nullable: true create_organizations_limit: type: integer description: 'The maximum number of organizations the user can create. 0 means unlimited. ' nullable: true 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`). nullable: true bypass_client_trust: type: boolean description: When set to `true`, the user will bypass client trust checks during sign-in. nullable: true responses: '200': $ref: '#/components/responses/User' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthenticationInvalid' '422': $ref: '#/components/responses/UnprocessableEntity' /users/count: get: operationId: GetUsersCount x-speakeasy-group: users x-speakeasy-name-override: count 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 addresses 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: 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: '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 - name: email_address_query in: query description: 'Counts users with emails that match the given query, via case-insensitive partial match. For example, `email_address_query=ello` will match a user with the email `HELLO@example.com`, and will be included in the resulting count.' schema: type: string required: false - name: phone_number_query in: query description: 'Counts users with phone numbers that match the given query, via case-insensitive partial match. For example, `phone_number_query=555` will match a user with the phone number `+1555xxxxxxx`, and will be included in the resulting count.' schema: type: string required: false - name: username_query in: query description: 'Counts users with usernames that match the given query, via case-insensitive partial match. For example, `username_query=CoolUser` will match a user with the username `SomeCoolUser`, and will be included in the resulting count.' schema: type: string - name: name_query in: query description: Returns users with names that match the given query, via case-insensitive partial match. schema: type: string - name: banned in: query required: false description: Counts users which are either banned (`banned=true`) or not banned (`banned=false`). schema: type: boolean - name: last_active_at_before in: query description: 'Returns users whose last session activity was before the given date (with millisecond precision). Example: use 1700690400000 to retrieve users whose last session activity was before 2023-11-23.' example: 1700690400000 schema: type: integer - name: last_active_at_after in: query description: 'Returns users whose last session activity was after the given date (with millisecond precision). Example: use 1700690400000 to retrieve users whose last session activity was after 2023-11-23.' example: 1700690400000 schema: type: integer - name: last_active_at_since in: query deprecated: true description: 'Returns users that had session activity since the given date. Example: use 1700690400000 to retrieve users that had session activity from 2023-11-23 until the current day. Deprecated in favor of `last_active_at_after`.' example: 1700690400000 schema: type: integer - name: created_at_before in: query description: 'Returns users who have been created before the given date (with millisecond precision). Example: use 1730160000000 to retrieve users who have been created before 2024-10-29.' example: 1730160000000 schema: type: integer - name: created_at_after in: query description: 'Returns users who have been created after the given date (with millisecond precision). Example: use 1730160000000 to retrieve users who have been created after 2024-10-29.' example: 1730160000000 schema: type: integer - name: last_sign_in_at_before in: query description: 'Counts users whose last sign-in was before the given date (with millisecond precision). Example: use 1700690400000 to count users whose last sign-in was before 2023-11-23.' example: 1700690400000 schema: type: integer - name: last_sign_in_at_after in: query description: 'Counts users whose last sign-in was after the given date (with millisecond precision). Example: use 1700690400000 to count users whose last sign-in was after 2023-11-23.' example: 1700690400000 schema: type: integer - name: provider in: query schema: type: string description: 'Counts users with external accounts for the specified OAuth provider. Must be used in combination with the `provider_user_id` parameter. For example, use `provider=oauth_google&provider_user_id=12345` to count users with Google provider user ID 12345. Accepts up to 100 providers.' required: false - name: provider_user_id in: query schema: type: array items: type: string description: 'Counts users with the specified provider user IDs for a specific provider. Must be used in combination with the `provider` parameter. For example, use `provider=oauth_google&provider_user_id=12345` to count users with Google provider user ID 12345. Accepts up to 100 provider user IDs. Any provider user IDs not found are ignored.' required: false responses: '200': $ref: '#/components/responses/User.Count' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}: get: operationId: GetUser x-speakeasy-group: users x-speakeasy-name-override: get 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 x-speakeasy-group: users x-speakeasy-name-override: update 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. This endpoint allows changing a user''s password. When passing the `password` parameter directly you have two further options. You can ignore the password policy checks for your instance by setting the `skip_password_checks` parameter to `true`. You can also choose to sign the user out of all their active sessions on any device once the password is updated. Just set `sign_out_of_other_sessions` to `true`.' 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 locale: type: string description: The locale to assign to the user (e.g., "en-US", "fr-FR") 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.' nullable: true notify_primary_email_address_changed: type: boolean description: 'If set to `true`, the user will be notified that their primary email address has changed. By default, no notification is sent.' nullable: true default: false 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.' nullable: true 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.' nullable: true 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 cannot 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: $ref: '#/components/schemas/PasswordHasher' skip_password_checks: type: boolean description: Set it to `true` if you're updating the user's password and want to skip any password policy settings check. This parameter can only be used when providing a `password`. nullable: true sign_out_of_other_sessions: type: boolean description: Set to `true` to sign out the user from all their active sessions once their password is updated. This parameter can only be used when providing a `password`. 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' nullable: true 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 additionalProperties: true nullable: true private_metadata: type: object description: Metadata saved on the user, that is only visible to your Backend API additionalProperties: true nullable: true 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.' additionalProperties: true nullable: true delete_self_enabled: type: boolean description: If true, the user can delete themselves with the Frontend API. nullable: true create_organization_enabled: type: boolean description: If true, the user can create organizations with the Frontend API. nullable: true legal_accepted_at: type: string description: A custom timestamp denoting _when_ the user accepted legal requirements, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`). nullable: true skip_legal_checks: type: boolean description: 'When set to `true` all legal checks are skipped. It is not recommended to skip legal checks unless you are migrating a user to Clerk.' nullable: true create_organizations_limit: type: integer description: The maximum number of organizations the user can create. 0 means unlimited. nullable: true 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`). nullable: true bypass_client_trust: type: boolean description: When set to `true`, the user will bypass client trust checks during sign-in. nullable: true responses: '200': $ref: '#/components/responses/User' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' delete: operationId: DeleteUser x-speakeasy-group: users x-speakeasy-name-override: delete 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 x-speakeasy-group: users x-speakeasy-name-override: ban 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 x-speakeasy-group: users x-speakeasy-name-override: unban 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/ban: post: operationId: UsersBan x-speakeasy-group: users x-speakeasy-name-override: bulkBan summary: Ban Multiple Users description: Marks multiple users as banned, which means that all their sessions are revoked and they are not allowed to sign in again. tags: - Users requestBody: required: true content: application/json: schema: type: object required: - user_ids properties: user_ids: type: array items: type: string description: Array of user IDs to ban minItems: 1 maxItems: 50 responses: '200': $ref: '#/components/responses/User.List' '400': $ref: '#/components/responses/ClerkErrors' '402': $ref: '#/components/responses/PaymentRequired' /users/unban: post: operationId: UsersUnban x-speakeasy-group: users x-speakeasy-name-override: bulkUnban summary: Unban Multiple Users description: Removes the ban mark from multiple users. tags: - Users requestBody: required: true content: application/json: schema: type: object required: - user_ids properties: user_ids: type: array items: type: string description: Array of user IDs to unban minItems: 1 maxItems: 50 responses: '200': $ref: '#/components/responses/User.List' '400': $ref: '#/components/responses/ClerkErrors' '402': $ref: '#/components/responses/PaymentRequired' /users/{user_id}/lock: post: operationId: LockUser x-speakeasy-group: users x-speakeasy-name-override: lock summary: Lock a User description: 'Marks the given user as locked, which means they are not allowed to sign in again until the lock expires. Lock duration can be configured in the instance''s restrictions settings.' tags: - Users parameters: - name: user_id in: path description: The ID of the user to lock required: true schema: type: string responses: '200': $ref: '#/components/responses/User' '403': $ref: '#/components/responses/AuthorizationInvalid' /users/{user_id}/unlock: post: operationId: UnlockUser x-speakeasy-group: users x-speakeasy-name-override: unlock summary: Unlock a User description: Removes the lock from the given user. tags: - Users parameters: - name: user_id in: path description: The ID of the user to unlock required: true schema: type: string responses: '200': $ref: '#/components/responses/User' '403': $ref: '#/components/responses/AuthorizationInvalid' /users/{user_id}/profile_image: post: operationId: SetUserProfileImage x-speakeasy-group: users x-speakeasy-name-override: setProfileImage summary: Set User Profile Image description: Update a user's profile image tags: - Users parameters: - name: user_id in: path description: The ID of the user to update the profile image for required: true schema: type: string requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary responses: '200': $ref: '#/components/responses/User' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' delete: operationId: DeleteUserProfileImage x-speakeasy-group: users x-speakeasy-name-override: deleteProfileImage summary: Delete User Profile Image description: Delete a user's profile image tags: - Users parameters: - name: user_id in: path description: The ID of the user to delete the profile image for required: true schema: type: string responses: '200': $ref: '#/components/responses/User' '404': $ref: '#/components/responses/ClerkErrors' /users/{user_id}/metadata: patch: operationId: UpdateUserMetadata x-speakeasy-group: users x-speakeasy-name-override: updateMetadata 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 additionalProperties: true 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 additionalProperties: true 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 additionalProperties: true 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}/billing/subscription: get: operationId: GetUserBillingSubscription x-speakeasy-group: users x-speakeasy-name-override: getBillingSubscription summary: Retrieve a User's Billing Subscription description: 'Retrieves the billing subscription for the specified user. This includes subscription details, active plans, billing information, and payment status. The subscription contains subscription items which represent the individual plans the user is subscribed to.' tags: - Users - Billing parameters: - in: path name: user_id required: true schema: type: string description: The ID of the user whose subscription to retrieve responses: '200': $ref: '#/components/responses/CommerceSubscription' '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' '500': $ref: '#/components/responses/ClerkErrors' /users/{user_id}/billing/credits: get: operationId: GetUserBillingCreditBalance x-speakeasy-group: users x-speakeasy-name-override: getBillingCreditBalance summary: Retrieve a User's Credit Balance description: 'Retrieves the current credit balance for the specified user. Credits can be applied during checkout to reduce the charge or automatically applied to upcoming recurring charges' tags: - Users - Billing parameters: - in: path name: user_id required: true schema: type: string description: The ID of the user whose credit balance to retrieve responses: '200': $ref: '#/components/responses/CommerceCreditBalance' '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' '500': $ref: '#/components/responses/ClerkErrors' post: operationId: AdjustUserBillingCreditBalance x-speakeasy-group: users x-speakeasy-name-override: adjustBillingCreditBalance summary: Adjust a User's Credit Balance description: 'Increases or decreases the credit balance for the specified user. Each adjustment is recorded as a ledger entry. The idempotency_key parameter ensures that duplicate requests are safely handled.' tags: - Users - Billing parameters: - in: path name: user_id required: true schema: type: string description: The ID of the user whose credit balance to adjust requestBody: description: Parameters for the credit balance adjustment required: true content: application/json: schema: $ref: '#/components/schemas/AdjustCreditBalanceRequest' responses: '200': $ref: '#/components/responses/CommerceCreditLedger' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '409': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/ClerkErrors' /users/{user_id}/oauth_access_tokens/{provider}: get: operationId: GetOAuthAccessToken x-speakeasy-group: users x-speakeasy-name-override: 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 - $ref: '#/components/parameters/Paginated' - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' responses: '200': $ref: '#/components/responses/OAuthAccessToken' '400': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /users/{user_id}/organization_memberships: get: operationId: UsersGetOrganizationMemberships x-speakeasy-group: users x-speakeasy-name-override: getOrganizationMemberships 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}/organization_invitations: get: operationId: UsersGetOrganizationInvitations x-speakeasy-group: users x-speakeasy-name-override: getOrganizationInvitations summary: Retrieve All Invitations for a User description: Retrieve a paginated list of the user's organization invitations tags: - Users parameters: - name: user_id in: path description: The ID of the user whose organization invitations we want to retrieve required: true schema: type: string - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' - in: query name: status description: Filter organization invitations based on their status required: false schema: type: string enum: - pending - accepted - revoked - expired responses: '200': $ref: '#/components/responses/OrganizationInvitationsWithPublicOrganizationData' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ResourceNotFound' /users/{user_id}/verify_password: post: operationId: VerifyPassword x-speakeasy-group: users x-speakeasy-name-override: 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 x-speakeasy-group: users x-speakeasy-name-override: 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 x-speakeasy-group: users x-speakeasy-name-override: 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' /users/{user_id}/backup_code: delete: operationId: DeleteBackupCode x-speakeasy-group: users x-speakeasy-name-override: deleteBackupCodes summary: Disable All User's Backup Codes description: Disable all of a user's backup codes. tags: - Users parameters: - name: user_id in: path description: The ID of the user whose backup codes are to be deleted. 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' /users/{user_id}/passkeys/{passkey_identification_id}: delete: operationId: UserPasskeyDelete x-speakeasy-group: users x-speakeasy-name-override: deletePasskey summary: Delete a User Passkey description: Delete the passkey identification for a given user and notify them through email. tags: - Users parameters: - name: user_id in: path description: The ID of the user that owns the passkey identity required: true schema: type: string - name: passkey_identification_id in: path description: The ID of the passkey identity to be deleted required: true schema: type: string responses: '200': $ref: '#/components/responses/DeletedObject' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '500': $ref: '#/components/responses/ClerkErrors' /users/{user_id}/web3_wallets/{web3_wallet_identification_id}: delete: operationId: UserWeb3WalletDelete x-speakeasy-group: users x-speakeasy-name-override: deleteWeb3Wallet summary: Delete a User Web3 Wallet description: Delete the web3 wallet identification for a given user. tags: - Users parameters: - name: user_id in: path description: The ID of the user that owns the web3 wallet required: true schema: type: string - name: web3_wallet_identification_id in: path description: The ID of the web3 wallet identity to be deleted required: true schema: type: string responses: '200': $ref: '#/components/responses/DeletedObject' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '500': $ref: '#/components/responses/ClerkErrors' /users/{user_id}/totp: delete: operationId: DeleteTOTP x-speakeasy-group: users x-speakeasy-name-override: deleteTOTP summary: Delete All the User's TOTPs description: Deletes all of the user's TOTPs. tags: - Users parameters: - name: user_id in: path description: The ID of the user whose TOTPs are to be deleted 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' /users/{user_id}/external_accounts/{external_account_id}: delete: operationId: DeleteExternalAccount x-speakeasy-group: users x-speakeasy-name-override: deleteExternalAccount summary: Delete External Account description: Delete an external account by ID. tags: - Users parameters: - name: user_id in: path description: The ID of the user's external account required: true schema: type: string - name: external_account_id in: path description: The ID of the external account to delete required: true schema: type: string responses: '200': $ref: '#/components/responses/DeletedObject' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ResourceNotFound' '500': $ref: '#/components/responses/ClerkErrors' /users/{user_id}/password/set_compromised: post: operationId: SetUserPasswordCompromised x-speakeasy-group: users x-speakeasy-name-override: setPasswordCompromised summary: Set a User's Password as Compromised description: Sets the given user's password as compromised. The user will be prompted to reset their password on their next sign-in. tags: - Users parameters: - name: user_id in: path description: The ID of the user to set the password as compromised required: true schema: type: string requestBody: content: application/json: schema: type: object additionalProperties: false properties: revoke_all_sessions: type: boolean nullable: true responses: '200': $ref: '#/components/responses/User' '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' /users/{user_id}/password/unset_compromised: post: operationId: UnsetUserPasswordCompromised x-speakeasy-group: users x-speakeasy-name-override: unsetPasswordCompromised summary: Unset a User's Password as Compromised description: Sets the given user's password as no longer compromised. The user will no longer be prompted to reset their password on their next sign-in. tags: - Users parameters: - name: user_id in: path description: The ID of the user to unset the compromised status for required: true schema: type: string responses: '200': $ref: '#/components/responses/User' '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' /invitations: post: operationId: CreateInvitation x-speakeasy-group: invitations x-speakeasy-name-override: create 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.' additionalProperties: true 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.' notify: type: boolean description: 'Optional flag which denotes whether an email invitation should be sent to the given email address. Defaults to `true`.' nullable: true default: true ignore_existing: type: boolean description: Whether an invitation should be created if there is already an existing invitation for this email address, or it's claimed by another user. nullable: true default: false expires_in_days: type: integer description: The number of days the invitation will be valid for. By default, the invitation expires after 30 days. nullable: true minimum: 1 maximum: 365 template_slug: type: string enum: - invitation - waitlist_invitation description: The slug of the email template to use for the invitation email. required: - email_address responses: '200': $ref: '#/components/responses/Invitation' '400': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/UnprocessableEntity' get: summary: List All Invitations x-speakeasy-group: invitations x-speakeasy-name-override: list description: Returns all non-revoked invitations for your application, sorted by creation date operationId: ListInvitations parameters: - in: query name: status required: false description: Filter invitations based on their status schema: type: string enum: - pending - accepted - revoked - expired - in: query required: false name: query description: Filter invitations based on their `email_address` or `id` schema: type: string - name: order_by in: query required: false description: 'Allows to return invitations in a particular order. At the moment, you can order the returned invitations either by their `created_at`, `email_address` or `expires_at`. In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. For example, if you want invitations 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 - $ref: '#/components/parameters/Paginated' - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' tags: - Invitations responses: '200': $ref: '#/components/responses/Invitation.List' /invitations/bulk: post: operationId: CreateBulkInvitations x-speakeasy-group: invitations x-speakeasy-name-override: bulkCreate summary: Create Multiple Invitations description: 'Use this API operation to create multiple invitations for the provided email addresses. You can choose to send the invitations as emails by setting the `notify` parameter to `true`. There cannot be an existing invitation for any of the email addresses you provide unless you set `ignore_existing` to `true` for specific email addresses. Please note that there must be no existing user for any of the email addresses you provide, and this rule cannot be bypassed. This endpoint is limited to a maximum of 10 invitations per API call. If you need to send more invitations, please make multiple requests.' tags: - Invitations requestBody: description: Required parameters content: application/json: schema: type: array minItems: 1 maxItems: 10 items: type: object additionalProperties: false properties: email_address: type: string description: The email address the invitation will be sent to public_metadata: type: object nullable: true 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.' additionalProperties: true redirect_url: type: string nullable: true description: The URL where the user is redirected upon visiting the invitation link, where they can accept the invitation. Required if you have implemented a [custom flow for handling application invitations](/docs/custom-flows/invitations). notify: type: boolean description: 'Optional flag which denotes whether an email invitation should be sent to the given email address. Defaults to true.' nullable: true default: true ignore_existing: type: boolean description: 'Whether an invitation should be created if there is already an existing invitation for this email address, or it''s claimed by another user.' nullable: true default: false expires_in_days: type: integer description: The number of days the invitation will be valid for. By default, the invitation expires after 30 days. nullable: true minimum: 1 maximum: 365 template_slug: type: string enum: - invitation - waitlist_invitation description: The slug of the email template to use for the invitation email. default: invitation required: - email_address responses: '200': $ref: '#/components/responses/Invitation.List' '400': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/UnprocessableEntity' /invitations/{invitation_id}/revoke: post: operationId: RevokeInvitation x-speakeasy-group: invitations x-speakeasy-name-override: revoke 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.Revoked' '400': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ResourceNotFound' /organization_invitations: get: operationId: ListInstanceOrganizationInvitations x-speakeasy-group: organizationInvitations x-speakeasy-name-override: getAll summary: Get a List of Organization Invitations for the Current Instance description: 'This request returns the list of organization invitations for the instance. Results can be paginated using the optional `limit` and `offset` query parameters. You can filter them by providing the ''status'' query parameter, that accepts multiple values. You can change the order by providing the ''order'' query parameter, that accepts multiple values. You can filter by the invited user email address providing the `query` query parameter. The organization invitations are ordered by descending creation date by default.' tags: - Organization Invitations parameters: - in: query name: order_by required: false description: 'Allows to return organization invitations in a particular order. At the moment, you can order the returned organization invitations either by their `created_at` or `email_address`. In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. For example, if you want organization invitations 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 - in: query name: status description: Filter organization invitations based on their status required: false schema: type: string enum: - pending - accepted - revoked - expired - in: query required: false name: query description: Filter organization invitations based on their `email_address` schema: type: string - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' responses: '200': $ref: '#/components/responses/OrganizationInvitationsWithPublicOrganizationData' '400': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/ClerkErrors' '500': $ref: '#/components/responses/ClerkErrors' /allowlist_identifiers: get: operationId: ListAllowlistIdentifiers x-speakeasy-group: allowlistIdentifiers x-speakeasy-name-override: list summary: List All Identifiers on the Allow-list description: Get a list of all identifiers allowed to sign up to an instance parameters: - $ref: '#/components/parameters/Paginated' - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' 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 x-speakeasy-group: allowlistIdentifiers x-speakeasy-name-override: create summary: Add Identifier to the Allow-list description: Create an identifier allowed to sign up to an instance tags: - Allow-list / Block-list requestBody: content: application/json: schema: type: object additionalProperties: false properties: identifier: type: string description: 'The identifier to be added in the allow-list. This can be an email address, a phone number, or a web3 wallet.' notify: type: boolean description: 'This flag denotes whether the given identifier will receive an invitation to join the application. Note that this only works for email address and phone number identifiers.' default: false required: - identifier 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 x-speakeasy-group: allowlistIdentifiers x-speakeasy-name-override: delete 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 x-speakeasy-group: blocklistIdentifiers x-speakeasy-name-override: list 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 x-speakeasy-group: blocklistIdentifiers x-speakeasy-name-override: create summary: Add Identifier to the Block-list description: Create an identifier that is blocked from accessing an instance tags: - Allow-list / Block-list requestBody: content: application/json: schema: type: object additionalProperties: false properties: identifier: type: string description: 'The identifier to be added in the block-list. This can be an email address, a phone number, or a web3 wallet.' required: - identifier 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 x-speakeasy-group: blocklistIdentifiers x-speakeasy-name-override: delete 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 x-speakeasy-group: betaFeatures x-speakeasy-name-override: updateInstanceSettings 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. This feature is deprecated, please contact support if you need assistance. 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: deprecated: true operationId: UpdateProductionInstanceDomain x-speakeasy-group: betaFeatures x-speakeasy-name-override: 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-certificates), 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 is_secondary: type: boolean description: Whether the domain is a secondary app. responses: '202': description: Accepted '400': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /actor_tokens: post: operationId: CreateActorToken x-speakeasy-group: actorTokens x-speakeasy-name-override: create summary: Create Actor Token description: 'Create an actor token that can be used to impersonate the given user. The `actor` parameter needs to include at least a "sub" key whose value is the ID of the actor (impersonating) user.' tags: - Actor Tokens requestBody: content: application/json: schema: type: object additionalProperties: false properties: user_id: type: string description: The ID of the user being impersonated. actor: type: object additionalProperties: true 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.' properties: sub: type: string description: The ID of the actor. required: - sub example: sub: user_2OEpKhcCN1Lat9NQ0G6puh7q5Rb 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: x-speakeasy-group: actorTokens x-speakeasy-name-override: revoke 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' /domains: get: operationId: ListDomains x-speakeasy-group: domains x-speakeasy-name-override: list summary: List All Instance Domains description: 'Use this endpoint to get a list of all domains for an instance. The response will contain the primary domain for the instance and any satellite domains. Each domain in the response contains information about the URLs where Clerk operates and the required CNAME targets.' tags: - Domains responses: '200': $ref: '#/components/responses/Domains' post: summary: Add a Domain operationId: AddDomain x-speakeasy-group: domains x-speakeasy-name-override: add description: 'Add a new domain for your instance. Useful in the case of multi-domain instances, allows adding satellite domains to an instance. The new domain must have a `name`. The domain name can contain the port for development instances, like `localhost:3000`. At the moment, instances can have only one primary domain, so the `is_satellite` parameter must be set to `true`. If you''re planning to configure the new satellite domain to run behind a proxy, pass the `proxy_url` parameter accordingly.' tags: - Domains requestBody: content: application/json: schema: type: object properties: name: type: string description: The new domain name. Can contain the port for development instances. is_satellite: type: boolean description: Marks the new domain as satellite. Only `true` is accepted at the moment. enum: - true proxy_url: type: string description: The full URL of the proxy which will forward requests to the Clerk Frontend API for this domain. Applicable only to production instances. nullable: true required: - name - is_satellite responses: '200': $ref: '#/components/responses/Domain' '400': $ref: '#/components/responses/ClerkErrors' '402': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/UnprocessableEntity' /domains/{domain_id}: delete: operationId: DeleteDomain x-speakeasy-group: domains x-speakeasy-name-override: delete summary: Delete a Satellite Domain description: 'Deletes a satellite domain for the instance. It is currently not possible to delete the instance''s primary domain.' tags: - Domains parameters: - in: path name: domain_id required: true schema: type: string description: The ID of the domain that will be deleted. Must be a satellite domain. responses: '200': $ref: '#/components/responses/DeletedObject' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ResourceNotFound' patch: operationId: UpdateDomain x-speakeasy-group: domains x-speakeasy-name-override: update summary: Update a Domain description: 'The `proxy_url` can be updated only for production instances. Update one of the instance''s domains. Both primary and satellite domains can be updated. If you choose to use Clerk via proxy, use this endpoint to specify the `proxy_url`. Whenever you decide you''d rather switch to DNS setup for Clerk, simply set `proxy_url` to `null` for the domain. When you update a production instance''s primary domain name, you have to make sure that you''ve completed all the necessary setup steps for DNS and emails to work. Expect downtime otherwise. Updating a primary domain''s name will also update the instance''s home origin, affecting the default application paths.' tags: - Domains parameters: - in: path name: domain_id required: true schema: type: string description: The ID of the domain that will be updated. requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: name: type: string description: 'The new domain name. For development instances, can contain the port, i.e `myhostname:3000`. For production instances, must be a valid FQDN, i.e `mysite.com`. Cannot contain protocol scheme.' nullable: true proxy_url: type: string description: 'The full URL of the proxy that will forward requests to Clerk''s Frontend API. Can only be updated for production instances.' nullable: true is_secondary: type: boolean description: 'Whether this is a domain for a secondary app, meaning that any subdomain provided is significant and will be stored as part of the domain. This is useful for supporting multiple apps (one primary and multiple secondaries) on the same root domain (eTLD+1).' nullable: true responses: '200': $ref: '#/components/responses/Domain' '400': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /instance: get: operationId: GetInstance x-speakeasy-group: instanceSettings x-speakeasy-name-override: get summary: Fetch the Current Instance description: Fetches the current instance tags: - Instance Settings responses: '200': $ref: '#/components/responses/Instance' patch: operationId: UpdateInstance x-speakeasy-group: instanceSettings x-speakeasy-name-override: update 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 support_email: type: string nullable: true clerk_js_version: type: string nullable: true development_origin: type: string nullable: true allowed_origins: type: array items: type: string description: For browser-like stacks such as browser extensions, Electron (not officially supported), or Capacitor.js (not officially supported), the instance allowed origins need to be updated with the request origin value. For Chrome extensions popup, background, or service worker pages, the origin is chrome-extension://extension_uuid. For Electron apps the default origin is http://localhost:3000. For Capacitor, the origin is capacitor://localhost. 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 nullable: true url_based_session_syncing: type: boolean description: Whether the instance should use URL-based session syncing in development mode (i.e. without third-party cookies). nullable: true responses: '204': description: Accepted '422': $ref: '#/components/responses/UnprocessableEntity' /instance/restrictions: patch: operationId: UpdateInstanceRestrictions x-speakeasy-group: instanceSettings x-speakeasy-name-override: updateRestrictions 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 allowlist_blocklist_disabled_on_sign_in: type: boolean nullable: true block_email_subaddresses: type: boolean nullable: true block_disposable_email_domains: type: boolean nullable: true responses: '200': $ref: '#/components/responses/InstanceRestrictions' '402': $ref: '#/components/responses/PaymentRequired' '422': $ref: '#/components/responses/UnprocessableEntity' /instance/protect: get: operationId: GetInstanceProtect summary: Get Instance Protect Settings tags: - Instance Settings responses: '200': $ref: '#/components/responses/InstanceProtect' patch: operationId: UpdateInstanceProtect summary: Update Instance Protect Settings tags: - Instance Settings requestBody: content: application/json: schema: type: object additionalProperties: false properties: rules_enabled: type: boolean nullable: true specter_enabled: type: boolean nullable: true responses: '200': $ref: '#/components/responses/InstanceProtect' '422': $ref: '#/components/responses/UnprocessableEntity' /instance/communication: get: operationId: GetInstanceCommunication x-speakeasy-group: instanceSettings x-speakeasy-name-override: getCommunication summary: Get Instance Communication Settings description: Retrieves the per-instance SMS communication settings, including the SMS country blocklist. tags: - Instance Settings responses: '200': $ref: '#/components/responses/InstanceCommunication' patch: operationId: UpdateInstanceCommunication x-speakeasy-group: instanceSettings x-speakeasy-name-override: updateCommunication summary: Update Instance Communication Settings description: 'Replaces the SMS country blocklist for this instance. Pass the full set of ISO 3166-1 alpha-2 country codes that should be blocked; codes that aren''t recognized as SMS-tier countries are silently dropped from the persisted list. Omitting `blocked_country_codes` is a no-op. ' tags: - Instance Settings requestBody: content: application/json: schema: type: object additionalProperties: false properties: blocked_country_codes: type: array nullable: true description: ISO 3166-1 alpha-2 country codes to block for SMS delivery. Whole-list replacement. Codes must be uppercase, 2-letter, and unique within the array. maxItems: 250 uniqueItems: true items: type: string pattern: ^[A-Z]{2}$ responses: '200': $ref: '#/components/responses/InstanceCommunication' '422': $ref: '#/components/responses/UnprocessableEntity' /instance/oauth_application_settings: get: operationId: GetInstanceOAuthApplicationSettings x-speakeasy-group: instanceSettings x-speakeasy-name-override: getOAuthApplicationSettings summary: Get OAuth Application Settings description: Retrieves the settings for OAuth applications for the instance (dynamic client registration, JWT access tokens, etc.). tags: - Instance Settings responses: '200': $ref: '#/components/responses/InstanceOAuthApplicationSettings' patch: operationId: UpdateInstanceOAuthApplicationSettings x-speakeasy-group: instanceSettings x-speakeasy-name-override: updateOAuthApplicationSettings summary: Update OAuth Application Settings description: Updates the OAuth application settings for the instance. tags: - Instance Settings requestBody: content: application/json: schema: type: object additionalProperties: false properties: dynamic_oauth_client_registration: type: boolean nullable: true description: Whether dynamic OAuth client registration is enabled for the instance (RFC 7591). oauth_jwt_access_tokens: type: boolean nullable: true description: Whether OAuth JWT access tokens are enabled for the instance (disabled indicates opaque access tokens). responses: '200': $ref: '#/components/responses/InstanceOAuthApplicationSettings' '422': $ref: '#/components/responses/UnprocessableEntity' /instance/change_domain: post: operationId: ChangeProductionInstanceDomain x-speakeasy-group: instanceSettings x-speakeasy-name-override: changeDomain 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-certificates), 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 is_secondary: type: boolean description: 'Whether this is a domain for a secondary app, meaning that any subdomain provided is significant and will be stored as part of the domain. This is useful for supporting multiple apps (one primary and multiple secondaries) on the same root domain (eTLD+1).' responses: '202': description: Accepted '400': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /instance/organization_settings: get: operationId: GetInstanceOrganizationSettings x-speakeasy-group: instanceSettings x-speakeasy-name-override: getOrganizationSettings summary: Get Instance Organization Settings description: Retrieves the organization settings of the instance tags: - Instance Settings responses: '200': $ref: '#/components/responses/OrganizationSettings' '402': $ref: '#/components/responses/PaymentRequired' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' patch: operationId: UpdateInstanceOrganizationSettings x-speakeasy-group: instanceSettings x-speakeasy-name-override: updateOrganizationSettings 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 admin_delete_enabled: type: boolean nullable: true domains_enabled: type: boolean nullable: true slug_disabled: type: boolean nullable: true domains_enrollment_modes: type: array items: type: string description: 'Specify which enrollment modes to enable for your Organization Domains. Supported modes are ''automatic_invitation'' & ''automatic_suggestion''.' creator_role_id: type: string description: Specify what the default organization role is for an organization creator. nullable: true domains_default_role_id: type: string description: Specify what the default organization role is for the organization domains. nullable: true responses: '200': $ref: '#/components/responses/OrganizationSettings' '400': $ref: '#/components/responses/ClerkErrors' '402': $ref: '#/components/responses/PaymentRequired' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /webhooks/svix: post: operationId: CreateSvixApp x-speakeasy-group: webhooks x-speakeasy-name-override: 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 x-speakeasy-group: webhooks x-speakeasy-name-override: 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 x-speakeasy-group: webhooks x-speakeasy-name-override: 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: operationId: ListJWTTemplates x-speakeasy-group: jwtTemplates x-speakeasy-name-override: list summary: List All Templates parameters: - $ref: '#/components/parameters/Paginated' - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' tags: - JWT Templates responses: '200': $ref: '#/components/responses/JWTTemplate.List' post: operationId: CreateJWTTemplate x-speakeasy-group: jwtTemplates x-speakeasy-name-override: create 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: integer minimum: 30 maximum: 315360000 description: JWT lifetime nullable: true allowed_clock_skew: type: integer minimum: 0 maximum: 300 description: JWT allowed clock skew nullable: true custom_signing_key: type: boolean description: Whether a custom signing key/algorithm is also provided for this template signing_algorithm: type: string description: The custom signing algorithm to use when minting JWTs. Required if `custom_signing_key` is `true`. nullable: true signing_key: type: string description: The custom signing private key to use when minting JWTs. Required if `custom_signing_key` is `true`. nullable: true required: - name - claims 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 x-speakeasy-group: jwtTemplates x-speakeasy-name-override: get 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 x-speakeasy-group: jwtTemplates x-speakeasy-name-override: update 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: integer minimum: 30 maximum: 315360000 description: JWT lifetime nullable: true allowed_clock_skew: type: integer minimum: 0 maximum: 300 description: JWT allowed clock skew nullable: true custom_signing_key: type: boolean description: Whether a custom signing key/algorithm is also provided for this template signing_algorithm: type: string description: The custom signing algorithm to use when minting JWTs. Required if `custom_signing_key` is `true`. nullable: true signing_key: type: string description: The custom signing private key to use when minting JWTs. Required if `custom_signing_key` is `true`. nullable: true required: - name - claims responses: '200': $ref: '#/components/responses/JWTTemplate' '400': $ref: '#/components/responses/ClerkErrors' '402': $ref: '#/components/responses/PaymentRequired' '422': $ref: '#/components/responses/UnprocessableEntity' delete: operationId: DeleteJWTTemplate x-speakeasy-group: jwtTemplates x-speakeasy-name-override: delete 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' /machine_tokens: {} /machines: get: operationId: ListMachines x-speakeasy-group: machines x-speakeasy-name-override: list summary: Get a List of Machines for an Instance description: 'This request returns the list of machines for an instance. The machines are ordered by descending creation date (i.e. most recent machines will be returned first)' tags: - Machines parameters: - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' - in: query name: query description: Returns machines with ID or name that match the given query. Uses exact match for machine ID and partial match for name. schema: type: string allowEmptyValue: true required: false - in: query name: order_by description: 'Allows to return machines in a particular order. You can order the returned machines by their `name` or `created_at`. To specify the direction, use the `+` or `-` symbols prepended to the property to order by. For example, to return machines in descending order by `created_at`, 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/Machine.List' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '422': $ref: '#/components/responses/UnprocessableEntity' post: operationId: CreateMachine x-speakeasy-group: machines x-speakeasy-name-override: create summary: Create a Machine description: Creates a new machine. tags: - Machines requestBody: content: application/json: schema: type: object required: - name properties: name: type: string description: The name of the machine minLength: 1 maxLength: 255 scoped_machines: type: array items: type: string description: Array of machine IDs that this machine will have access to. Maximum of 150 scopes per machine. maxItems: 150 default_token_ttl: type: integer description: The default time-to-live (TTL) in seconds for tokens created by this machine. Must be at least 1 second. minimum: 1 maximum: 315360000 default: 3600 responses: '200': $ref: '#/components/responses/Machine.Created' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '422': $ref: '#/components/responses/UnprocessableEntity' /machines/{machine_id}: get: operationId: GetMachine x-speakeasy-group: machines x-speakeasy-name-override: get summary: Retrieve a Machine description: Returns the details of a machine. tags: - Machines parameters: - name: machine_id in: path description: The ID of the machine to retrieve required: true schema: type: string responses: '200': $ref: '#/components/responses/Machine' '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' patch: operationId: UpdateMachine x-speakeasy-group: machines x-speakeasy-name-override: update summary: Update a Machine description: 'Updates an existing machine. Only the provided fields will be updated.' tags: - Machines parameters: - name: machine_id in: path description: The ID of the machine to update required: true schema: type: string requestBody: content: application/json: schema: type: object properties: name: type: string description: The name of the machine minLength: 1 maxLength: 255 default_token_ttl: type: integer description: The default time-to-live (TTL) in seconds for tokens created by this machine. Must be at least 1 second. minimum: 1 maximum: 315360000 responses: '200': $ref: '#/components/responses/Machine' '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' delete: operationId: DeleteMachine x-speakeasy-group: machines x-speakeasy-name-override: delete summary: Delete a Machine description: Deletes a machine. tags: - Machines parameters: - name: machine_id in: path description: The ID of the machine to delete required: true schema: type: string responses: '200': $ref: '#/components/responses/Machine.Deleted' '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' /machines/{machine_id}/secret_key: get: operationId: GetMachineSecretKey x-speakeasy-group: machines x-speakeasy-name-override: getSecretKey summary: Retrieve a Machine Secret Key description: Returns the secret key for a machine. tags: - Machines parameters: - name: machine_id in: path description: The ID of the machine to retrieve the secret key for required: true schema: type: string responses: '200': $ref: '#/components/responses/Machine.SecretKey' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' /machines/{machine_id}/secret_key/rotate: post: operationId: RotateMachineSecretKey x-speakeasy-group: machines x-speakeasy-name-override: rotateSecretKey summary: Rotate a Machine's Secret Key description: 'Rotates the machine''s secret key. When the secret key is rotated, make sure to update it in your machine/application. The previous secret key will remain valid for the duration specified by the previous_token_ttl parameter.' tags: - Machines parameters: - name: machine_id in: path description: The ID of the machine to rotate the secret key for required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - previous_token_ttl properties: previous_token_ttl: type: integer minimum: 0 maximum: 28800 description: 'The time in seconds that the previous secret key will remain valid after rotation. This ensures a graceful transition period for updating applications with the new secret key. Set to 0 to immediately expire the previous key. Maximum value is 8 hours (28800 seconds).' responses: '200': $ref: '#/components/responses/Machine.SecretKey' '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' /machines/{machine_id}/scopes: post: operationId: CreateMachineScope x-speakeasy-group: machines x-speakeasy-name-override: createScope summary: Create a Machine Scope description: 'Creates a new machine scope, allowing the specified machine to access another machine. Maximum of 150 scopes per machine.' tags: - Machines parameters: - name: machine_id in: path description: The ID of the machine that will have access to another machine required: true schema: type: string requestBody: content: application/json: schema: type: object required: - to_machine_id properties: to_machine_id: type: string description: The ID of the machine that will be scoped to the current machine responses: '200': $ref: '#/components/responses/MachineScope' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' /machines/{machine_id}/scopes/{other_machine_id}: delete: operationId: DeleteMachineScope x-speakeasy-group: machines x-speakeasy-name-override: deleteScope summary: Delete a Machine Scope description: Deletes a machine scope, removing access from one machine to another. tags: - Machines parameters: - name: machine_id in: path description: The ID of the machine that has access to another machine required: true schema: type: string - name: other_machine_id in: path description: The ID of the machine that is being accessed required: true schema: type: string responses: '200': $ref: '#/components/responses/MachineScope.Deleted' '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' /organizations: get: operationId: ListOrganizations x-speakeasy-group: organizations x-speakeasy-name-override: list 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: - 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: include_missing_member_with_elevated_permissions description: Flag to denote whether or not to include a member with elevated permissions who is not currently a member of the organization. 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 - in: query name: user_id description: 'Returns organizations that include any of the specified user IDs as members. Any user IDs not found are ignored. For each user ID, the `+` and `-` can be prepended to the ID, which denote whether the respective organization should be included or excluded from the result set.' schema: type: array items: type: string required: false - in: query name: organization_id description: 'Returns organizations with the organization IDs specified. Any organization IDs not found are ignored. 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. Example: ?organization_id=+org_1&organization_id=-org_2' schema: type: array items: type: string required: false - in: query name: order_by description: 'Allows to return organizations in a particular order. At the moment, you can order the returned organizations either by their `name`, `created_at` or `members_count`. In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. For example, if you want organizations to be returned in descending order according to their `created_at` property, you can use `-created_at`. If you don''t use `+` or `-`, then `+` is implied. Defaults to `-created_at`.' schema: type: string default: -created_at required: false - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' responses: '200': $ref: '#/components/responses/Organizations' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/AuthorizationInvalid' '422': $ref: '#/components/responses/UnprocessableEntity' post: operationId: CreateOrganization x-speakeasy-group: organizations x-speakeasy-name-override: create summary: Create an Organization description: 'Creates a new organization with the given name for an instance. 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. The `created_by` user will see this as their [active organization](https://clerk.com/docs/organizations/overview#active-organization) the next time they create a session, presuming they don''t explicitly set a different organization as active before then.' tags: - Organizations requestBody: content: application/json: schema: type: object properties: name: type: string description: 'The name of the new organization. May not contain URLs or HTML. Max length: 256' created_by: type: string description: The ID of the User who will become the administrator for the new organization nullable: true private_metadata: type: object description: Metadata saved on the organization, accessible only from the Backend API additionalProperties: true nullable: true 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 additionalProperties: true nullable: true 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. This field should only be included when slugs are enabled in the organization settings, refer to our [documentation](https://clerk.com/docs/guides/organizations/overview#organization-slugs).' nullable: true max_allowed_memberships: type: integer minimum: 0 description: The maximum number of memberships allowed for this organization nullable: true created_at: type: string description: A custom date/time denoting _when_ the organization was created, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`). nullable: true role_set_key: type: string description: The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) to assign to this organization. nullable: true required: - name responses: '200': $ref: '#/components/responses/Organization' '400': $ref: '#/components/responses/ClerkErrors' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AuthorizationInvalid' '422': $ref: '#/components/responses/UnprocessableEntity' /organizations/{organization_id}: get: operationId: GetOrganization x-speakeasy-group: organizations x-speakeasy-name-override: get 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 - in: query required: false name: include_members_count description: Flag to denote whether or not the organization's members count should be included in the response. schema: type: boolean - in: query required: false name: include_missing_member_with_elevated_permissions description: Flag to denote whether or not to include a member with elevated permissions who is not currently a member of the organization. schema: type: boolean responses: '200': $ref: '#/components/responses/Organization' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' patch: operationId: UpdateOrganization x-speakeasy-group: organizations x-speakeasy-name-override: update 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. additionalProperties: true nullable: true private_metadata: type: object description: Metadata saved on the organization that is only visible to your backend. additionalProperties: true nullable: true name: type: string description: 'The new name of the organization. May not contain URLs or HTML. Max length: 256' 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 minimum: 0 description: The maximum number of memberships allowed for this organization nullable: true admin_delete_enabled: type: boolean description: If true, an admin can delete this organization with the Frontend API. nullable: true created_at: type: string description: A custom date/time denoting _when_ the organization was created, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`). nullable: true role_set_key: type: string description: The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) to assign to this organization. nullable: true responses: '200': $ref: '#/components/responses/Organization' '400': $ref: '#/components/responses/ClerkErrors' '402': $ref: '#/components/responses/ResourceNotFound' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' delete: operationId: DeleteOrganization x-speakeasy-group: organizations x-speakeasy-name-override: delete 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. After the organization is deleted, any user''s active sessions that contain the deleted organization will be cleared.' 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 x-speakeasy-group: organizations x-speakeasy-name-override: mergeMetadata 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.' additionalProperties: true 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.' additionalProperties: true 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 x-speakeasy-group: organizations x-speakeasy-name-override: uploadLogo 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`.' 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 description: The ID of the user that will be credited with the image upload. file: type: string format: binary required: - file 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' delete: operationId: DeleteOrganizationLogo x-speakeasy-group: organizations x-speakeasy-name-override: deleteLogo summary: Delete the Organization's Logo. description: Delete the organization's logo. tags: - Organizations parameters: - name: organization_id in: path description: The ID of the organization for which the logo will be deleted. required: true schema: type: string responses: '200': $ref: '#/components/responses/Organization' '404': $ref: '#/components/responses/ResourceNotFound' /organizations/{organization_id}/billing/subscription: get: operationId: GetOrganizationBillingSubscription x-speakeasy-group: organizations x-speakeasy-name-override: getBillingSubscription summary: Retrieve an Organization's Billing Subscription description: 'Retrieves the billing subscription for the specified organization. This includes subscription details, active plans, billing information, and payment status. The subscription contains subscription items which represent the individual plans the organization is subscribed to.' tags: - Organizations - Billing parameters: - in: path name: organization_id required: true schema: type: string description: The ID of the organization whose subscription to retrieve responses: '200': $ref: '#/components/responses/CommerceSubscription' '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' '500': $ref: '#/components/responses/ClerkErrors' /organizations/{organization_id}/billing/credits: get: operationId: GetOrganizationBillingCreditBalance x-speakeasy-group: organizations x-speakeasy-name-override: getBillingCreditBalance summary: Retrieve an Organization's Credit Balance description: 'Retrieves the current credit balance for the specified organization. Credits can be applied during checkout to reduce the charge or automatically applied to upcoming recurring charges.' tags: - Organizations - Billing parameters: - in: path name: organization_id required: true schema: type: string description: The ID of the organization whose credit balance to retrieve responses: '200': $ref: '#/components/responses/CommerceCreditBalance' '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' '500': $ref: '#/components/responses/ClerkErrors' post: operationId: AdjustOrganizationBillingCreditBalance x-speakeasy-group: organizations x-speakeasy-name-override: adjustBillingCreditBalance summary: Adjust an Organization's Credit Balance description: 'Increases or decreases the credit balance for the specified organization. Each adjustment is recorded as a ledger entry. The idempotency_key parameter ensures that duplicate requests are safely handled.' tags: - Organizations - Billing parameters: - in: path name: organization_id required: true schema: type: string description: The ID of the organization whose credit balance to adjust requestBody: description: Parameters for the credit balance adjustment required: true content: application/json: schema: $ref: '#/components/schemas/AdjustCreditBalanceRequest' responses: '200': $ref: '#/components/responses/CommerceCreditLedger' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '409': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/ClerkErrors' /organizations/{organization_id}/invitations: post: operationId: CreateOrganizationInvitation x-speakeasy-group: organizationInvitations x-speakeasy-name-override: create 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 can 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 and private metadata for the organization invitation. The public metadata are visible by both the Frontend and the Backend whereas the private ones only by 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: 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 nullable: true 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 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. When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership.' additionalProperties: true nullable: true private_metadata: type: object description: 'Metadata saved on the organization invitation, fully accessible (read/write) from the Backend API but not visible from the Frontend API. When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership.' additionalProperties: true nullable: true 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. nullable: true expires_in_days: type: integer description: The number of days the invitation will be valid for. By default, the invitation has a 30 days expire. nullable: true minimum: 1 maximum: 365 notify: type: boolean description: 'Optional flag which denotes whether an email invitation should be sent to the given email address. Defaults to `true`.' nullable: true default: true required: - email_address - role responses: '200': $ref: '#/components/responses/OrganizationInvitation' '400': $ref: '#/components/responses/ClerkErrors' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' get: operationId: ListOrganizationInvitations x-speakeasy-group: organizationInvitations x-speakeasy-name-override: list summary: Get a List of Organization Invitations description: 'This request returns the list of organization invitations. Results can be paginated using the optional `limit` and `offset` query parameters. You can filter them by providing the ''status'' query parameter, that accepts multiple values. The organization invitations are ordered by descending creation date. Most recent invitations will be returned first. Any invitations created as a result of an Organization Domain are not included in the results.' tags: - Organization Invitations parameters: - in: path required: true name: organization_id schema: type: string description: The organization ID. - in: query name: status description: Filter organization invitations based on their status required: false schema: type: string enum: - pending - accepted - revoked - expired - in: query required: false name: email_address description: Returns organization invitations inviting the specified email address. schema: type: string - in: query name: order_by required: false description: 'Allows to return organization invitations in a particular order. You can order the returned organization invitations either by their `created_at` or `email_address`. In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. For example, if you want organization invitations 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 - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' responses: '200': $ref: '#/components/responses/OrganizationInvitations' '400': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /organizations/{organization_id}/invitations/bulk: post: operationId: CreateOrganizationInvitationBulk x-speakeasy-group: organizationInvitations x-speakeasy-name-override: bulkCreate summary: Bulk Create and Send Organization Invitations description: 'Creates new organization invitations in bulk and sends out emails to the provided email addresses with a link to accept the invitation and join the organization. This endpoint is limited to a maximum of 10 invitations per API call. If you need to send more invitations, please make multiple requests. You can specify a different `role` for each 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 for each invitation. When the invited user clicks the link to accept the invitation, they will be redirected to the provided URL. Use this parameter to implement a custom invitation acceptance flow. You can specify the ID of the user that will send the invitation with the `inviter_user_id` parameter. Each invitation can have a different inviter user. Inviter users must be members with administrator privileges in the organization. Only "admin" members can create organization invitations. You can optionally provide public and private metadata for each organization invitation. The public metadata are visible by both the Frontend and the Backend, whereas the private metadata are only visible by 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 organization ID. requestBody: required: true content: application/json: schema: type: array minItems: 1 maxItems: 10 items: 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 nullable: true 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 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. When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership.' additionalProperties: true nullable: true private_metadata: type: object description: 'Metadata saved on the organization invitation, fully accessible (read/write) from the Backend API but not visible from the Frontend API. When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership.' additionalProperties: true nullable: true 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. nullable: true expires_in_days: type: integer description: The number of days the invitation will be valid for. By default, the invitation has a 30 days expire. nullable: true minimum: 1 maximum: 365 notify: type: boolean description: 'Optional flag which denotes whether an email invitation should be sent to the given email address. Defaults to `true`.' nullable: true default: true required: - email_address - role responses: '200': $ref: '#/components/responses/OrganizationInvitations' '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: deprecated: true operationId: ListPendingOrganizationInvitations x-speakeasy-group: organizationInvitations x-speakeasy-name-override: listPending 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. Any invitations created as a result of an Organization Domain are not included in the results.' 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}: get: operationId: GetOrganizationInvitation x-speakeasy-group: organizationInvitations x-speakeasy-name-override: get summary: Retrieve an Organization Invitation by ID description: Use this request to get an existing organization invitation by ID. 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. responses: '200': $ref: '#/components/responses/OrganizationInvitation' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' /organizations/{organization_id}/invitations/{invitation_id}/revoke: post: operationId: RevokeOrganizationInvitation x-speakeasy-group: organizationInvitations x-speakeasy-name-override: revoke 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 accepts 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: false content: application/json: schema: type: object properties: requesting_user_id: type: string nullable: true description: 'The ID of the user that revokes the invitation. Must be an administrator in the organization.' responses: '200': $ref: '#/components/responses/OrganizationInvitation' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' /organization_roles: get: operationId: ListOrganizationRoles x-speakeasy-group: organizationRoles x-speakeasy-name-override: list summary: Get a List of Organization Roles description: 'This request returns the list of organization roles for the instance. Results can be paginated using the optional `limit` and `offset` query parameters. The organization roles are ordered by descending creation date. Most recent roles will be returned first.' tags: - Organization Roles parameters: - in: query name: query description: 'Returns organization roles with ID, name, or key that match the given query. Uses exact match for organization role ID and partial match for name and key.' required: false schema: type: string - in: query name: order_by description: 'Allows to return organization roles in a particular order. At the moment, you can order the returned organization roles by their `created_at`, `name`, or `key`. In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. For example, if you want organization roles 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`.' required: false schema: type: string default: -created_at - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' responses: '200': $ref: '#/components/responses/Roles' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '422': $ref: '#/components/responses/UnprocessableEntity' post: operationId: CreateOrganizationRole x-speakeasy-group: organizationRoles x-speakeasy-name-override: create summary: Create an Organization Role description: 'Creates a new organization role with the given name and permissions for an instance. The key must be unique for the instance and start with the ''org:'' prefix, followed by lowercase alphanumeric characters and underscores only. You can optionally provide a description for the role and specify whether it should be included in the initial role set. Organization roles support permissions that can be assigned to control access within the organization.' tags: - Organization Roles requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: The name of the new organization role key: type: string description: A unique key for the organization role. Must start with 'org:' and contain only lowercase alphanumeric characters and underscores. description: type: string description: Optional description for the role nullable: true permissions: type: array items: type: string description: Array of permission IDs to assign to the role nullable: true include_in_initial_role_set: type: boolean description: Whether this role should be included in the initial role set nullable: true additionalProperties: false required: - name - key responses: '200': $ref: '#/components/responses/Role' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /organization_roles/{organization_role_id}: get: operationId: GetOrganizationRole x-speakeasy-group: organizationRoles x-speakeasy-name-override: get summary: Retrieve an Organization Role description: Use this request to retrieve an existing organization role by its ID. tags: - Organization Roles parameters: - in: path required: true name: organization_role_id schema: type: string description: The ID of the organization role responses: '200': $ref: '#/components/responses/Role' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' patch: operationId: UpdateOrganizationRole x-speakeasy-group: organizationRoles x-speakeasy-name-override: update summary: Update an Organization Role description: 'Updates an existing organization role. You can update the name, key, description, and permissions of the role. All parameters are optional - you can update only the fields you want to change. If the role is used as a creator role or domain default role, updating the key will cascade the update to the organization settings.' tags: - Organization Roles parameters: - in: path required: true name: organization_role_id schema: type: string description: The ID of the organization role to update requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: The new name for the organization role nullable: true key: type: string description: A unique key for the organization role. Must start with 'org:' and contain only lowercase alphanumeric characters and underscores. nullable: true description: type: string description: Optional description for the role nullable: true permissions: type: array items: type: string description: Array of permission IDs to assign to the role. If provided, this will replace the existing permissions. nullable: true responses: '200': $ref: '#/components/responses/Role' '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' delete: operationId: DeleteOrganizationRole x-speakeasy-group: organizationRoles x-speakeasy-name-override: delete summary: Delete an Organization Role description: 'Deletes the organization role. The role cannot be deleted if it is currently used as the default creator role, domain default role, assigned to any members, or exists in any invitations.' tags: - Organization Roles parameters: - in: path required: true name: organization_role_id schema: type: string description: The ID of the organization role to delete responses: '200': $ref: '#/components/responses/DeletedObject' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /organization_roles/{organization_role_id}/permissions/{permission_id}: post: operationId: AssignPermissionToOrganizationRole x-speakeasy-group: organizationRoles x-speakeasy-name-override: assignPermission summary: Assign a Permission to an Organization Role description: Assigns a permission to an organization role tags: - Organization Roles parameters: - in: path required: true name: organization_role_id schema: type: string description: The ID of the organization role - in: path required: true name: permission_id schema: type: string description: The ID of the permission to assign responses: '200': $ref: '#/components/responses/Role' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '409': $ref: '#/components/responses/Conflict' delete: operationId: RemovePermissionFromOrganizationRole x-speakeasy-group: organizationRoles x-speakeasy-name-override: removePermission summary: Remove a Permission from an Organization Role description: Removes a permission from an organization role tags: - Organization Roles parameters: - in: path required: true name: organization_role_id schema: type: string description: The ID of the organization role - in: path required: true name: permission_id schema: type: string description: The ID of the permission to remove responses: '200': $ref: '#/components/responses/Role' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /organizations/{organization_id}/memberships: post: operationId: CreateOrganizationMembership x-speakeasy-group: organizationMemberships x-speakeasy-name-override: create 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. This organization will be the user''s [active organization] (https://clerk.com/docs/organizations/overview#active-organization) the next time they create a session, presuming they don''t explicitly set a different organization as active before then.' 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. public_metadata: type: object description: Metadata saved on the organization membership, that is visible to both your frontend and backend. additionalProperties: true nullable: true private_metadata: type: object description: Metadata saved on the organization membership that is only visible to your backend. additionalProperties: true nullable: true 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 x-speakeasy-group: organizationMemberships x-speakeasy-name-override: list 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. - in: query required: false name: order_by description: 'Sorts organizations memberships by phone_number, email_address, created_at, first_name, last_name or username. By prepending one of those values with + or -, we can choose to sort in ascending (ASC) or descending (DESC) order."' schema: type: string - 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: 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: 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 addresses not found are ignored.' required: false - name: role in: query schema: type: array items: type: string description: Returns users with the specified roles. Accepts up to 100 roles. Any roles not found are ignored. 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 - name: email_address_query in: query description: 'Returns users with emails that match the given query, via case-insensitive partial match. For example, `email_address_query=ello` will match a user with the email `HELLO@example.com`.' schema: type: string required: false - name: phone_number_query in: query description: 'Returns users with phone numbers that match the given query, via case-insensitive partial match. For example, `phone_number_query=555` will match a user with the phone number `+1555xxxxxxx`.' schema: type: string required: false - name: username_query in: query description: 'Returns users with usernames that match the given query, via case-insensitive partial match. For example, `username_query=CoolUser` will match a user with the username `SomeCoolUser`.' schema: type: string - name: name_query in: query description: Returns users with names that match the given query, via case-insensitive partial match. schema: type: string - name: last_active_at_before in: query description: 'Returns users whose last session activity was before the given date (with millisecond precision). Example: use 1700690400000 to retrieve users whose last session activity was before 2023-11-23.' example: 1700690400000 schema: type: integer - name: last_active_at_after in: query description: 'Returns users whose last session activity was after the given date (with millisecond precision). Example: use 1700690400000 to retrieve users whose last session activity was after 2023-11-23.' example: 1700690400000 schema: type: integer - name: created_at_before in: query description: 'Returns users who have been created before the given date (with millisecond precision). Example: use 1730160000000 to retrieve users who have been created before 2024-10-29.' example: 1730160000000 schema: type: integer - name: created_at_after in: query description: 'Returns users who have been created after the given date (with millisecond precision). Example: use 1730160000000 to retrieve users who have been created after 2024-10-29.' example: 1730160000000 schema: type: integer - $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 x-speakeasy-group: organizationMemberships x-speakeasy-name-override: update 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 to which this membership belongs - in: path required: true name: user_id schema: type: string description: The ID of the user to which this membership belongs requestBody: required: true content: application/json: schema: type: object properties: role: type: string description: The new role of the given membership. required: - role responses: '200': $ref: '#/components/responses/OrganizationMembership' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' delete: operationId: DeleteOrganizationMembership x-speakeasy-group: organizationMemberships x-speakeasy-name-override: delete 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 to which this membership belongs - in: path required: true name: user_id schema: type: string description: The ID of the user to which this membership belongs responses: '200': $ref: '#/components/responses/OrganizationMembership' '401': $ref: '#/components/responses/AuthenticationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /organizations/{organization_id}/memberships/{user_id}/metadata: patch: operationId: UpdateOrganizationMembershipMetadata x-speakeasy-group: organizationMemberships x-speakeasy-name-override: updateMetadata 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 to which this membership belongs - in: path required: true name: user_id schema: type: string description: The ID of the user to which this membership belongs requestBody: 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.' additionalProperties: true 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.' additionalProperties: true responses: '200': $ref: '#/components/responses/OrganizationMembership' '400': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /organizations/{organization_id}/domains: post: operationId: CreateOrganizationDomain x-speakeasy-group: organizationDomains x-speakeasy-name-override: create summary: Create a New Organization Domain. description: Creates a new organization domain. By default the domain is verified, but can be optionally set to unverified. tags: - Organization Domains parameters: - in: path required: true name: organization_id schema: type: string description: The ID of the organization where the new domain will be created. requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: name: type: string description: The name of the new domain nullable: false enrollment_mode: type: string description: The enrollment_mode for the new domain. This can be `automatic_invitation`, `automatic_suggestion` or `manual_invitation` nullable: false verified: type: boolean description: The status of domain's verification. Defaults to true nullable: true responses: '200': $ref: '#/components/responses/OrganizationDomain' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' get: operationId: ListOrganizationDomains x-speakeasy-group: organizationDomains x-speakeasy-name-override: list summary: Get a List of All Domains of an Organization. description: Get a list of all domains of an organization. tags: - Organization Domains parameters: - in: path required: true name: organization_id schema: type: string description: The organization ID. - in: query required: false name: verified description: Filter domains by their verification status. `true` or `false` schema: type: string - in: query required: false name: enrollment_mode description: Filter domains by their enrollment mode schema: type: string - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' responses: '200': $ref: '#/components/responses/OrganizationDomains' '401': $ref: '#/components/responses/AuthenticationInvalid' '422': $ref: '#/components/responses/UnprocessableEntity' /organizations/{organization_id}/domains/{domain_id}: patch: operationId: UpdateOrganizationDomain x-speakeasy-group: organizationDomains x-speakeasy-name-override: update summary: Update an Organization Domain. description: Updates the properties of an existing organization domain. tags: - Organization Domains parameters: - in: path required: true name: organization_id schema: type: string description: The ID of the organization to which the domain belongs - in: path required: true name: domain_id schema: type: string description: The ID of the domain requestBody: required: true content: application/json: schema: type: object properties: enrollment_mode: type: string description: The enrollment_mode for the new domain. This can be `automatic_invitation`, `automatic_suggestion` or `manual_invitation` nullable: true verified: type: boolean description: The status of the domain's verification nullable: true responses: '200': $ref: '#/components/responses/OrganizationDomain' '400': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' delete: operationId: DeleteOrganizationDomain x-speakeasy-group: organizationDomains x-speakeasy-name-override: delete summary: Remove a Domain from an Organization. description: Removes the given domain from the organization. tags: - Organization Domains parameters: - in: path required: true name: organization_id schema: type: string description: The ID of the organization to which the domain belongs - in: path required: true name: domain_id schema: type: string description: The ID of the domain responses: '200': $ref: '#/components/responses/DeletedObject' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' /organization_domains: get: operationId: ListAllOrganizationDomains x-speakeasy-group: organizationDomains x-speakeasy-name-override: listAll summary: List All Organization Domains description: 'Retrieves a list of all organization domains within the current instance. This endpoint can be used to list all domains across all organizations or filter domains by organization, verification status, enrollment mode, or search query. The response includes pagination information and details about each domain including its verification status, enrollment mode, and associated counts. ' tags: - Organization Domains parameters: - in: query name: organization_id description: The ID of the organization to filter domains by required: false schema: type: string - in: query name: verified description: Filter by verification status required: false schema: type: string enum: - 'true' - 'false' - in: query name: enrollment_mode description: Filter by enrollment mode required: false style: form explode: false schema: type: array items: type: string enum: - manual_invitation - automatic_invitation - automatic_suggestion - in: query name: query description: 'Search domains by name or organization ID. If the query starts with "org_", it will search by exact organization ID match. Otherwise, it performs a case-insensitive partial match on the domain name. Note: An empty string or whitespace-only value is not allowed and will result in a validation error. ' required: false schema: type: string - in: query name: domains description: Filter by exact domain names. Accepts multiple values (e.g. domains=example.com&domains=test.org). required: false style: form explode: true schema: type: array items: type: string - in: query name: order_by description: 'Allows to return organization domains in a particular order. At the moment, you can order the returned domains by their `name` or `created_at`. In order to specify the direction, you can use the `+/-` symbols prepended to the property to order by. For example, if you want domains 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`. ' required: false schema: type: string default: -created_at - $ref: '#/components/parameters/OffsetParameter' - $ref: '#/components/parameters/LimitParameter' responses: '200': $ref: '#/components/responses/OrganizationDomains' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '422': $ref: '#/components/responses/UnprocessableEntity' /proxy_checks: post: summary: Verify the Proxy Configuration for Your Domain x-speakeasy-group: proxyChecks x-speakeasy-name-override: verify description: 'This endpoint can be used to validate that a proxy-enabled domain is operational. It tries to verify that the proxy URL provided in the parameters maps to a functional proxy that can reach the Clerk Frontend API. You can use this endpoint before you set a proxy URL for a domain. This way you can ensure that switching to proxy-based configuration will not lead to downtime for your instance. The `proxy_url` parameter allows for testing proxy configurations for domains that don''t have a proxy URL yet, or operate on a different proxy URL than the one provided. It can also be used to re-validate a domain that is already configured to work with a proxy.' operationId: VerifyDomainProxy tags: - Proxy Checks requestBody: content: application/json: schema: type: object properties: domain_id: type: string description: The ID of the domain that will be updated. proxy_url: type: string description: The full URL of the proxy which will forward requests to the Clerk Frontend API for this domain. e.g. https://example.com/__clerk responses: '200': $ref: '#/components/responses/ProxyCheck' '400': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/UnprocessableEntity' /redirect_urls: get: summary: List All Redirect URLs x-speakeasy-group: redirectUrls x-speakeasy-name-override: list description: Lists all whitelisted redirect_urls for the instance operationId: ListRedirectURLs tags: - Redirect URLs parameters: - $ref: '#/components/parameters/Paginated' - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' responses: '200': $ref: '#/components/responses/RedirectURL.List' post: summary: Create a Redirect URL x-speakeasy-group: redirectUrls x-speakeasy-name-override: create 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"` required: - url 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 x-speakeasy-group: redirectUrls x-speakeasy-name-override: get 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 x-speakeasy-group: redirectUrls x-speakeasy-name-override: delete 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 x-speakeasy-group: signInTokens x-speakeasy-name-override: create 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.' minimum: 1 default: 2592000 nullable: true required: - user_id 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: operationId: RevokeSignInToken x-speakeasy-group: signInTokens x-speakeasy-name-override: revoke summary: Revoke the Given Sign-in Token description: Revokes a pending sign-in token 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}: get: operationId: GetSignUp x-speakeasy-group: signUps x-speakeasy-name-override: get summary: Retrieve a Sign-up by ID description: Retrieve the details of the sign-up with the given ID tags: - Sign Ups parameters: - name: id in: path description: The ID of the sign-up to retrieve required: true schema: type: string responses: '200': $ref: '#/components/responses/SignUp' '403': $ref: '#/components/responses/AuthorizationInvalid' patch: operationId: UpdateSignUp x-speakeasy-group: signUps x-speakeasy-name-override: update 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: 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 custom_action: type: boolean description: If true, the sign-up will be marked as a custom action. nullable: true responses: '200': $ref: '#/components/responses/SignUp' '403': $ref: '#/components/responses/AuthorizationInvalid' /oauth_applications: get: operationId: ListOAuthApplications x-speakeasy-group: oauthApplications x-speakeasy-name-override: list 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' - name: order_by in: query description: 'Allows to return OAuth applications in a particular order. At the moment, you can order the returned OAuth applications by their `created_at` and `name`. In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. For example, if you want OAuth applications to be returned in descending order according to their `created_at` property, you can use `-created_at`. If you don''t use `+` or `-`, then `+` is implied. We only support one `order_by` parameter, and if multiple `order_by` parameters are provided, we will only keep the first one. For example, if you pass `order_by=name&order_by=created_at`, we will consider only the first `order_by` parameter, which is `name`. The `created_at` parameter will be ignored in this case.' required: false schema: type: string default: +created_at - name: name_query in: query description: Returns OAuth applications with names that match the given query, via case-insensitive partial match. required: false schema: type: string responses: '200': $ref: '#/components/responses/OAuthApplications' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/AuthorizationInvalid' '422': $ref: '#/components/responses/UnprocessableEntity' post: operationId: CreateOAuthApplication x-speakeasy-group: oauthApplications x-speakeasy-name-override: create 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. Max length: 256' redirect_uris: type: array items: type: string description: An array of redirect URIs of the new OAuth application nullable: true callback_url: type: string maxLength: 1024 description: The callback URL of the new OAuth application nullable: true deprecated: true scopes: type: string maxLength: 1024 description: Define the allowed scopes for the new OAuth applications that dictate the user payload of the OAuth user info endpoint. Available scopes are `profile`, `email`, `public_metadata`, `private_metadata`. Provide the requested scopes as a string, separated by spaces. default: profile email example: profile email public_metadata nullable: true consent_screen_enabled: type: boolean default: true description: True to enable a consent screen to display in the authentication flow. nullable: true pkce_required: type: boolean default: false description: True to require the Proof Key of Code Exchange (PKCE) flow. nullable: true public: type: boolean description: If true, this client is public and you can use the Proof Key of Code Exchange (PKCE) flow. nullable: true required: - name 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 x-speakeasy-group: oauthApplications x-speakeasy-name-override: get 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 x-speakeasy-group: oauthApplications x-speakeasy-name-override: update 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. Max length: 256' nullable: true redirect_uris: type: array items: type: string description: An array of redirect URIs of the new OAuth application nullable: true callback_url: type: string maxLength: 1024 description: The new callback URL of the OAuth application nullable: true deprecated: true scopes: type: string maxLength: 1024 description: Define the allowed scopes for the new OAuth applications that dictate the user payload of the OAuth user info endpoint. Available scopes are `profile`, `email`, `public_metadata`, `private_metadata`. Provide the requested scopes as a string, separated by spaces. default: profile email example: profile email public_metadata private_metadata nullable: true consent_screen_enabled: type: boolean description: True to enable a consent screen to display in the authentication flow. This cannot be disabled for dynamically registered OAuth Applications. nullable: true pkce_required: type: boolean description: True to require the Proof Key of Code Exchange (PKCE) flow. nullable: true public: type: boolean description: If true, this client is public and you can use the Proof Key of Code Exchange (PKCE) flow. nullable: true responses: '200': $ref: '#/components/responses/OAuthApplication' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' delete: operationId: DeleteOAuthApplication x-speakeasy-group: oauthApplications x-speakeasy-name-override: delete 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}/logo: put: operationId: UploadOAuthApplicationLogo x-speakeasy-group: oauthApplications x-speakeasy-name-override: uploadLogo summary: Upload a Logo for the OAuth Application description: 'Set or replace an OAuth application''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`.' tags: - OAuth Applications parameters: - name: oauth_application_id in: path description: The ID of the OAuth application 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 description: The ID of the user that will be credited with the image upload. file: type: string format: binary required: - file responses: '200': $ref: '#/components/responses/OAuthApplication' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '413': $ref: '#/components/responses/ClerkErrors' /oauth_applications/{oauth_application_id}/rotate_secret: post: operationId: RotateOAuthApplicationSecret x-speakeasy-group: oauthApplications x-speakeasy-name-override: rotateSecret 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' /saml_connections: get: deprecated: true operationId: ListSAMLConnections x-speakeasy-group: samlConnections x-speakeasy-name-override: list summary: Get a List of SAML Connections for an Instance description: 'Returns the list of SAML Connections for an instance. Results can be paginated using the optional `limit` and `offset` query parameters. The SAML Connections are ordered by descending creation date and the most recent will be returned first. Deprecated: Use the Enterprise Connections API instead. This endpoint will be removed in future versions.' tags: - SAML Connections parameters: - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' - name: query in: query required: false description: Returns SAML connections that have a name that matches the given query, via case-insensitive partial match. schema: type: string - name: order_by in: query required: false description: 'Sorts organizations memberships by phone_number, email_address, created_at, first_name, last_name or username. By prepending one of those values with + or -, we can choose to sort in ascending (ASC) or descending (DESC) order.' schema: type: string - name: organization_id in: query schema: type: array items: type: string description: 'Returns SAML connections that have an associated organization ID 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.' responses: '200': $ref: '#/components/responses/SAMLConnections' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AuthorizationInvalid' '422': $ref: '#/components/responses/UnprocessableEntity' post: deprecated: true operationId: CreateSAMLConnection x-speakeasy-group: samlConnections x-speakeasy-name-override: create summary: Create a SAML Connection description: 'Create a new SAML Connection. Deprecated: Use the Enterprise Connections API instead. This endpoint will be removed in future versions.' tags: - SAML Connections requestBody: content: application/json: schema: type: object additionalProperties: false properties: name: type: string description: The name to use as a label for this SAML Connection domain: type: string deprecated: true description: The domain of your organization. Sign in flows using an email with this domain, will use this SAML Connection. domains: type: array items: type: string description: The domains of your organization. Sign in flows using an email with one of these domains, will use this SAML Connection. provider: type: string description: The IdP provider of the connection. enum: - saml_custom - saml_okta - saml_google - saml_microsoft idp_entity_id: type: string description: The Entity ID as provided by the IdP nullable: true idp_sso_url: type: string description: The Single-Sign On URL as provided by the IdP nullable: true idp_certificate: type: string description: The X.509 certificate as provided by the IdP nullable: true idp_metadata_url: type: string description: The URL which serves the IdP metadata. If present, it takes priority over the corresponding individual properties nullable: true idp_metadata: type: string description: The XML content of the IdP metadata file. If present, it takes priority over the corresponding individual properties nullable: true organization_id: type: string description: The ID of the organization to which users of this SAML Connection will be added nullable: true attribute_mapping: type: object description: Define the attribute name mapping between Identity Provider and Clerk's user properties nullable: true additionalProperties: false properties: user_id: type: string email_address: type: string first_name: type: string last_name: type: string force_authn: type: boolean description: Enable or deactivate ForceAuthn required: - name - provider anyOf: - required: - domain - required: - domains responses: '200': $ref: '#/components/responses/SAMLConnection' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '409': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/UnprocessableEntity' /saml_connections/{saml_connection_id}: get: deprecated: true operationId: GetSAMLConnection x-speakeasy-group: samlConnections x-speakeasy-name-override: get summary: Retrieve a SAML Connection by ID description: 'Fetches the SAML Connection whose ID matches the provided `saml_connection_id` in the path. Deprecated: Use the Enterprise Connections API instead. This endpoint will be removed in future versions.' tags: - SAML Connections parameters: - in: path name: saml_connection_id required: true schema: type: string description: The ID of the SAML Connection responses: '200': $ref: '#/components/responses/SAMLConnection' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' patch: deprecated: true operationId: UpdateSAMLConnection x-speakeasy-group: samlConnections x-speakeasy-name-override: update summary: Update a SAML Connection description: 'Updates the SAML Connection whose ID matches the provided `id` in the path. Deprecated: Use the Enterprise Connections API instead. This endpoint will be removed in future versions.' tags: - SAML Connections parameters: - in: path name: saml_connection_id required: true schema: type: string description: The ID of the SAML Connection to update requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: name: type: string description: The name of the new SAML Connection nullable: true domain: type: string description: The domain to use for the new SAML Connection deprecated: true nullable: true domains: type: array items: type: string nullable: true description: A list of the domains on use for the SAML connection idp_entity_id: type: string description: The Entity ID as provided by the IdP nullable: true idp_sso_url: type: string description: The SSO URL as provided by the IdP nullable: true idp_certificate: type: string description: The x509 certificated as provided by the IdP nullable: true idp_metadata_url: type: string description: The URL which serves the IdP metadata. If present, it takes priority over the corresponding individual properties and replaces them nullable: true idp_metadata: type: string description: The XML content of the IdP metadata file. If present, it takes priority over the corresponding individual properties nullable: true organization_id: type: string description: The ID of the organization to which users of this SAML Connection will be added nullable: true attribute_mapping: type: object description: Define the attribute name mapping between Identity Provider and Clerk's user properties nullable: true additionalProperties: false properties: user_id: type: string email_address: type: string first_name: type: string last_name: type: string active: type: boolean description: Activate or de-activate the SAML Connection nullable: true sync_user_attributes: type: boolean description: Controls whether to update the user's attributes in each sign-in nullable: true allow_subdomains: type: boolean description: Allow users with an email address subdomain to use this connection in order to authenticate nullable: true allow_idp_initiated: type: boolean description: Enable or deactivate IdP-initiated flows nullable: true disable_additional_identifications: type: boolean description: Enable or deactivate additional identifications nullable: true allow_organization_account_linking: type: boolean description: Whether this connection supports account linking via organization membership nullable: true force_authn: type: boolean description: Enable or deactivate ForceAuthn consent_verified_domains_deletion: type: boolean description: When enabling the connection, controls behavior when verified domains used for enrollment modes like automatic invitation or automatic suggestion already exist for the same domain. If true, those verified domains are removed and the connection is enabled. If false or omitted, the request fails when any such verified domain exists. nullable: true responses: '200': $ref: '#/components/responses/SAMLConnection' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '409': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/UnprocessableEntity' delete: deprecated: true operationId: DeleteSAMLConnection x-speakeasy-group: samlConnections x-speakeasy-name-override: delete summary: Delete a SAML Connection description: 'Deletes the SAML Connection whose ID matches the provided `id` in the path. Deprecated: Use the Enterprise Connections API instead. This endpoint will be removed in future versions.' tags: - SAML Connections parameters: - in: path name: saml_connection_id required: true schema: type: string description: The ID of the SAML Connection to delete responses: '200': $ref: '#/components/responses/DeletedObject' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' /enterprise_connections: get: operationId: ListEnterpriseConnections x-speakeasy-group: enterpriseConnections x-speakeasy-name-override: list summary: List Enterprise Connections description: 'Returns the list of enterprise connections for the instance. Results can be paginated using the optional `limit` and `offset` query parameters.' tags: - Enterprise Connections parameters: - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' - name: organization_id in: query required: false description: Filter enterprise connections by organization ID schema: type: string - name: active in: query required: false description: Filter by active status. If true, only active connections are returned. If false, only inactive connections are returned. If omitted, all connections are returned. schema: type: boolean responses: '200': $ref: '#/components/responses/EnterpriseConnections' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AuthorizationInvalid' '422': $ref: '#/components/responses/UnprocessableEntity' post: operationId: CreateEnterpriseConnection x-speakeasy-group: enterpriseConnections x-speakeasy-name-override: create summary: Create an Enterprise Connection description: Create a new enterprise connection. tags: - Enterprise Connections requestBody: content: application/json: schema: type: object additionalProperties: false required: - name - provider - domains properties: name: type: string description: The display name of the connection provider: type: string description: The identity provider (e.g. saml_custom, oidc_custom, oidc_github_enterprise, oidc_gitlab) enum: - saml_custom - saml_okta - saml_google - saml_microsoft - oidc_custom - oidc_github_enterprise - oidc_gitlab domains: type: array items: type: string minItems: 1 description: Domains associated with the enterprise connection (required; at least one). Values are normalized to lowercase. Each domain must be a valid fully qualified domain name. organization_id: type: string description: Organization ID when the connection is linked to an organization nullable: true allow_organization_account_linking: type: boolean description: Whether this connection supports account linking via organization membership nullable: true active: type: boolean description: Whether the enterprise connection is active. When true, IdP metadata must be provided via the `saml` object. nullable: true saml: type: object description: 'SAML connection-specific properties. Only applied when the enterprise connection uses SAML (e.g. provider is saml_custom). Use this to set IdP configuration, attribute mapping, and other SAML-specific settings at creation time.' nullable: true additionalProperties: false properties: idp_entity_id: type: string description: IdP entity ID nullable: true idp_sso_url: type: string description: IdP SSO URL nullable: true idp_certificate: type: string description: IdP certificate (PEM) nullable: true idp_metadata_url: type: string description: URL to IdP metadata nullable: true idp_metadata: type: string description: Raw IdP metadata XML nullable: true attribute_mapping: type: object description: Attribute mapping for SAML attributes nullable: true additionalProperties: false properties: user_id: type: string nullable: true email_address: type: string nullable: true first_name: type: string nullable: true last_name: type: string nullable: true allow_subdomains: type: boolean nullable: true allow_idp_initiated: type: boolean nullable: true force_authn: type: boolean nullable: true oidc: type: object description: OIDC connection-specific properties. Only applied when the enterprise connection uses OIDC (e.g. provider is oidc_custom, oidc_github_enterprise, or oidc_gitlab). nullable: true additionalProperties: false properties: client_id: type: string description: OIDC client ID nullable: true client_secret: type: string description: OIDC client secret nullable: true discovery_url: type: string description: OIDC discovery URL nullable: true auth_url: type: string description: OIDC authorization URL nullable: true token_url: type: string description: OIDC token URL nullable: true user_info_url: type: string description: OIDC userinfo URL nullable: true requires_pkce: type: boolean description: Whether PKCE is required (must be true for public clients with no client secret) nullable: true custom_attributes: type: array description: Custom attributes to map from the IdP to the user's profile via SSO or SCIM provisioning. Requires the custom attributes feature to be enabled for the instance. items: type: object additionalProperties: false required: - name - key properties: name: type: string description: Display name for the custom attribute minLength: 1 key: type: string description: Key used to store the attribute in the user's metadata minLength: 1 pattern: ^[^_][A-Za-z0-9_-]*$ sso_path: type: string description: Path to extract the attribute value from SSO claims scim_path: type: string description: GJSON path to extract the attribute value from SCIM user resources responses: '201': $ref: '#/components/responses/EnterpriseConnection' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '409': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/UnprocessableEntity' /enterprise_connections/{enterprise_connection_id}: get: operationId: GetEnterpriseConnection x-speakeasy-group: enterpriseConnections x-speakeasy-name-override: get summary: Retrieve an Enterprise Connection description: Fetches the enterprise connection whose ID matches the provided `enterprise_connection_id` in the path. tags: - Enterprise Connections parameters: - in: path name: enterprise_connection_id required: true schema: type: string description: The ID of the enterprise connection responses: '200': $ref: '#/components/responses/EnterpriseConnection' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' patch: operationId: UpdateEnterpriseConnection x-speakeasy-group: enterpriseConnections x-speakeasy-name-override: update summary: Update an Enterprise Connection description: 'Updates the enterprise connection whose ID matches the provided `enterprise_connection_id` in the path. When enabling the connection (setting `active` to true), any existing verified organization domains that match the connection''s domains (e.g. used for enrollment modes like automatic invitation) may be deleted so the connection can be enabled.' tags: - Enterprise Connections parameters: - in: path name: enterprise_connection_id required: true schema: type: string description: The ID of the enterprise connection to update requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: name: type: string description: The display name of the enterprise connection nullable: true domains: type: array items: type: string description: 'Domains associated with the enterprise connection. Values are normalized to lowercase. Empty array means ignored (no change); non-empty array means set domains to the given list (replaces existing).' nullable: true active: type: boolean description: Whether the enterprise connection is active. When set to true (enabling), any existing verified organization domains for the same domain(s) will be removed so the connection can be enabled. nullable: true sync_user_attributes: type: boolean description: Whether to sync user attributes on sign-in nullable: true disable_additional_identifications: type: boolean description: Whether to disable additional identifications nullable: true allow_organization_account_linking: type: boolean description: Whether this connection supports account linking via organization membership nullable: true organization_id: type: string description: Organization ID to link to this enterprise connection. Only linking is supported; sending this field sets or changes the linked organization. There is no way to unlink an organization once linked. nullable: true saml: type: object description: 'SAML connection-specific properties. Only applied when the enterprise connection uses SAML. Use this to update IdP configuration, attribute mapping, and other SAML-specific settings.' nullable: true additionalProperties: false properties: name: type: string description: Display name of the SAML connection nullable: true idp_entity_id: type: string description: IdP entity ID nullable: true idp_sso_url: type: string description: IdP SSO URL nullable: true idp_certificate: type: string description: IdP certificate (PEM) nullable: true idp_metadata_url: type: string description: URL to IdP metadata nullable: true idp_metadata: type: string description: Raw IdP metadata XML nullable: true attribute_mapping: type: object description: Attribute mapping for SAML attributes nullable: true additionalProperties: false properties: user_id: type: string nullable: true email_address: type: string nullable: true first_name: type: string nullable: true last_name: type: string nullable: true allow_subdomains: type: boolean nullable: true allow_idp_initiated: type: boolean nullable: true force_authn: type: boolean nullable: true oidc: type: object description: OIDC connection-specific properties. Only applied when the enterprise connection uses OIDC (e.g. oidc_custom, oidc_github_enterprise, or oidc_gitlab). nullable: true additionalProperties: false properties: client_id: type: string description: OIDC client ID nullable: true client_secret: type: string description: OIDC client secret nullable: true discovery_url: type: string description: OIDC discovery URL nullable: true auth_url: type: string description: OIDC authorization URL nullable: true token_url: type: string description: OIDC token URL nullable: true user_info_url: type: string description: OIDC userinfo URL nullable: true requires_pkce: type: boolean description: Whether PKCE is required (must be true for public clients with no client secret) nullable: true custom_attributes: type: array description: Custom attributes to map from the IdP to the user's profile via SSO or SCIM provisioning. Requires the custom attributes feature to be enabled for the instance. nullable: true items: type: object additionalProperties: false required: - name - key properties: name: type: string description: Display name for the custom attribute minLength: 1 key: type: string description: Key used to store the attribute in the user's metadata minLength: 1 pattern: ^[^_][A-Za-z0-9_-]*$ sso_path: type: string description: Path to extract the attribute value from SSO claims scim_path: type: string description: GJSON path to extract the attribute value from SCIM user resources responses: '200': $ref: '#/components/responses/EnterpriseConnection' '400': $ref: '#/components/responses/ClerkErrors' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' delete: operationId: DeleteEnterpriseConnection x-speakeasy-group: enterpriseConnections x-speakeasy-name-override: delete summary: Delete an Enterprise Connection description: Deletes the enterprise connection whose ID matches the provided `enterprise_connection_id` in the path. tags: - Enterprise Connections parameters: - in: path name: enterprise_connection_id required: true schema: type: string description: The ID of the enterprise connection to delete responses: '200': $ref: '#/components/responses/DeletedObject' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' /testing_tokens: post: operationId: CreateTestingToken x-speakeasy-group: testingTokens x-speakeasy-name-override: create summary: Retrieve a New Testing Token description: Retrieve a new testing token. tags: - Testing Tokens responses: '200': $ref: '#/components/responses/TestingToken' /agents/tasks: post: operationId: CreateAgentTask x-speakeasy-group: agentTasks x-speakeasy-name-override: create summary: Create Agent Task description: 'Create an agent task on behalf of a user. The response contains a URL that, when visited, creates a session for the user. The agent_id is stable per agent_name within an instance. The agent_task_id is unique per call.' tags: - Agent Tasks requestBody: content: application/json: schema: type: object additionalProperties: false properties: on_behalf_of: type: object description: 'Identifies the user on whose behalf the agent task is created. Exactly one of user_id or identifier must be provided.' properties: user_id: type: string description: The ID of the user. identifier: type: string description: A verified identifier (e.g. email address) belonging to the user. permissions: type: string description: The permissions granted to the agent task. Must be "*" (all permissions). enum: - '*' agent_name: type: string description: 'A name identifying the agent. Used to derive a stable agent_id per instance. Logged for audit purposes.' task_description: type: string description: A description of the task being performed. Logged for audit purposes. redirect_url: type: string format: uri description: 'The URL the user is redirected to after the agent task is accepted. Must be a valid absolute URL with an `https` scheme in production instances. In development instances, `http` is also permitted. The URL''s domain must belong to one of the instance''s associated domains (primary or satellite); otherwise the redirect will be rejected when the task ticket is consumed.' session_max_duration_in_seconds: type: integer description: 'The maximum duration that the session which will be created by the generated agent task should last. By default, the duration of a session created via an agent task lasts 30 minutes.' default: 1800 required: - on_behalf_of - permissions - agent_name - task_description - redirect_url responses: '200': $ref: '#/components/responses/AgentTask' '400': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /agents/tasks/{agent_task_id}/revoke: post: operationId: RevokeAgentTask x-speakeasy-group: agentTasks x-speakeasy-name-override: revoke summary: Revoke Agent Task description: Revokes a pending agent task. tags: - Agent Tasks parameters: - name: agent_task_id in: path description: The ID of the agent task to be revoked. required: true schema: type: string responses: '200': $ref: '#/components/responses/AgentTask' '400': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ResourceNotFound' /organization_memberships: get: operationId: InstanceGetOrganizationMemberships x-speakeasy-group: users x-speakeasy-name-override: getInstanceOrganizationMemberships summary: Get a List of All Organization Memberships Within an Instance. description: Retrieves all organization user memberships for the given instance. tags: - Organization Memberships parameters: - name: order_by in: query required: false description: 'Sorts organizations memberships by phone_number, email_address, created_at, first_name, last_name or username. By prepending one of those values with + or -, we can choose to sort in ascending (ASC) or descending (DESC) order.' schema: type: string - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' responses: '200': $ref: '#/components/responses/OrganizationMemberships' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/ClerkErrors' /waitlist_entries: get: operationId: ListWaitlistEntries x-speakeasy-group: waitlistEntries x-speakeasy-name-override: list summary: List All Waitlist Entries description: 'Retrieve a list of waitlist entries for the instance. Entries are ordered by creation date in descending order by default. Supports filtering by email address or status and pagination with limit and offset parameters.' tags: - Waitlist Entries parameters: - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' - in: query name: query description: Filter waitlist entries by `email_address` or `id` required: false schema: type: string - in: query name: status description: Filter waitlist entries by their status required: false schema: type: string enum: - pending - invited - completed - rejected - in: query name: order_by required: false description: 'Specify the order of results. Supported values are: - `created_at` - `email_address` - `invited_at` Use `+` for ascending or `-` for descending order. Defaults to `-created_at`.' schema: type: string default: -created_at responses: '200': $ref: '#/components/responses/WaitlistEntries' post: operationId: CreateWaitlistEntry x-speakeasy-group: waitlistEntries x-speakeasy-name-override: create summary: Create a Waitlist Entry description: 'Creates a new waitlist entry for the given email address. If the email address is already on the waitlist, no new entry will be created and the existing waitlist entry will be returned.' tags: - Waitlist Entries requestBody: content: application/json: schema: type: object properties: email_address: type: string description: The email address to add to the waitlist notify: type: boolean description: 'Optional flag which denotes whether a confirmation email should be sent to the given email address. Defaults to `true`.' default: true nullable: true required: - email_address responses: '200': $ref: '#/components/responses/WaitlistEntry' '400': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/UnprocessableEntity' /waitlist_entries/bulk: post: operationId: CreateBulkWaitlistEntries x-speakeasy-group: waitlistEntries x-speakeasy-name-override: bulkCreate summary: Create Multiple Waitlist Entries description: 'Creates multiple waitlist entries for the provided email addresses. You can choose whether to send confirmation emails by setting the `notify` parameter to `true` or `false` for each entry. If the `notify` parameter is omitted, it defaults to `true`. If an email address is already on the waitlist, no new entry will be created and the existing waitlist entry will be returned. Duplicate email addresses within the same request are not allowed. This endpoint is limited to a maximum of 50 entries per API call. If you need to add more entries, please make multiple requests.' tags: - Waitlist Entries requestBody: description: Required parameters content: application/json: schema: type: array minItems: 1 maxItems: 50 items: type: object additionalProperties: false properties: email_address: type: string format: email description: The email address to add to the waitlist notify: type: boolean description: 'Optional flag which denotes whether a confirmation email should be sent to the given email address. Defaults to `true`.' nullable: true default: true required: - email_address responses: '200': $ref: '#/components/responses/WaitlistEntry.List' '400': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/UnprocessableEntity' /waitlist_entries/{waitlist_entry_id}: delete: operationId: DeleteWaitlistEntry x-speakeasy-group: waitlistEntries x-speakeasy-name-override: delete summary: Delete a Pending Waitlist Entry description: Delete a pending waitlist entry. tags: - Waitlist Entries parameters: - name: waitlist_entry_id in: path description: The ID of the waitlist entry to delete required: true schema: type: string responses: '200': $ref: '#/components/responses/DeletedObject' '400': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ResourceNotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' /waitlist_entries/{waitlist_entry_id}/invite: post: operationId: InviteWaitlistEntry x-speakeasy-group: waitlistEntries x-speakeasy-name-override: invite summary: Invite a Waitlist Entry description: Send an invite to the email address in a waitlist entry. tags: - Waitlist Entries parameters: - name: waitlist_entry_id in: path description: The ID of the waitlist entry to invite required: true schema: type: string requestBody: content: application/json: schema: type: object properties: ignore_existing: type: boolean description: Whether an invitation should be created if there is already an existing invitation for this email address, or it's claimed by another user. nullable: true default: false responses: '200': $ref: '#/components/responses/WaitlistEntry' '400': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ResourceNotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' /waitlist_entries/{waitlist_entry_id}/reject: post: operationId: RejectWaitlistEntry x-speakeasy-group: waitlistEntries x-speakeasy-name-override: reject summary: Reject a Waitlist Entry description: Reject a waitlist entry. tags: - Waitlist Entries parameters: - name: waitlist_entry_id in: path description: The ID of the waitlist entry to reject required: true schema: type: string responses: '200': $ref: '#/components/responses/WaitlistEntry' '400': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ResourceNotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' /accountless_applications: {} /accountless_applications/complete: {} /billing/plans: get: operationId: GetCommercePlanList x-speakeasy-group: billing x-speakeasy-name-override: listPlans tags: - Billing summary: List All Billing Plans description: 'Returns a list of all billing plans for the instance. The plans are returned sorted by creation date, with the newest plans appearing first. This includes both free and paid plans. Pagination is supported.' parameters: - $ref: '#/components/parameters/Paginated' - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' - in: query name: payer_type description: Filter plans by payer type required: false schema: type: string enum: - user - org responses: '200': $ref: '#/components/responses/CommercePlan.List' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/ClerkErrors' /billing/prices: get: operationId: GetBillingPriceList x-speakeasy-group: billing x-speakeasy-name-override: listPrices tags: - Billing summary: List All Billing Prices description: 'Returns a list of all prices for the instance. The prices are returned sorted by amount ascending, then by creation date descending. This includes both default and custom prices. Pagination is supported.' parameters: - $ref: '#/components/parameters/Paginated' - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' - in: query name: plan_id description: Filter prices by plan ID required: false schema: type: string responses: '200': $ref: '#/components/responses/BillingPrice.List' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/ClerkErrors' post: operationId: CreateBillingPrice x-speakeasy-group: billing x-speakeasy-name-override: createPrice tags: - Billing summary: Create a Custom Billing Price description: 'Creates a custom price for a billing plan. Custom prices allow you to offer different pricing to specific customers while maintaining the same plan structure.' requestBody: description: Parameters for creating a custom price required: true content: application/json: schema: $ref: '#/components/schemas/CreateBillingPriceRequest' responses: '200': $ref: '#/components/responses/BillingPrice' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/ClerkErrors' /billing/subscription_items: get: operationId: GetCommerceSubscriptionItemList x-speakeasy-group: billing x-speakeasy-name-override: listSubscriptionItems tags: - Billing summary: List All Subscription Items description: 'Returns a list of all subscription items for the instance. The subscription items are returned sorted by creation date, with the newest appearing first. This includes subscriptions for both users and organizations. Pagination is supported.' parameters: - $ref: '#/components/parameters/Paginated' - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' - in: query name: status description: Filter subscription items by status required: false schema: type: string enum: - active - ended - past_due - upcoming - free_trial - in: query name: payer_type description: Filter subscription items by payer type required: false schema: type: string enum: - user - org - in: query name: plan_id description: Filter subscription items by plan ID required: false schema: type: string - in: query name: include_free description: Whether to include free plan subscription items required: false schema: type: boolean default: false - in: query name: query description: Search query to filter subscription items required: false schema: type: string responses: '200': $ref: '#/components/responses/CommerceSubscriptionItem.List' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/ClerkErrors' /billing/subscription_items/{subscription_item_id}: delete: operationId: CancelCommerceSubscriptionItem x-speakeasy-group: billing x-speakeasy-name-override: cancelSubscriptionItem tags: - Billing summary: Cancel a Subscription Item description: Cancel a specific subscription item. The subscription item can be canceled immediately or at the end of the current billing period. parameters: - name: subscription_item_id in: path description: The ID of the subscription item to cancel required: true schema: type: string - in: query name: end_now description: Whether to cancel the subscription immediately (true) or at the end of the current billing period (false, default) required: false schema: type: boolean default: false responses: '200': $ref: '#/components/responses/CommerceSubscriptionItem' '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' '500': $ref: '#/components/responses/ClerkErrors' /billing/subscription_items/{subscription_item_id}/extend_free_trial: post: operationId: ExtendBillingSubscriptionItemFreeTrial x-speakeasy-group: billing x-speakeasy-name-override: extendSubscriptionItemFreeTrial tags: - Billing summary: Extend Free Trial for a Subscription Item description: 'Extends the free trial period for a specific subscription item to the specified timestamp. The subscription item must be currently in a free trial period, and the plan must support free trials. The timestamp must be in the future and not more than 365 days from the end of the current trial period This operation is idempotent - repeated requests with the same timestamp will not change the trial period.' parameters: - name: subscription_item_id in: path description: The ID of the subscription item to extend the free trial for required: true schema: type: string requestBody: description: Parameters for extending the free trial required: true content: application/json: schema: $ref: '#/components/schemas/ExtendFreeTrialRequest' responses: '200': $ref: '#/components/responses/responses-CommerceSubscriptionItem' '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' '500': $ref: '#/components/responses/ClerkErrors' /billing/subscription_items/{subscription_item_id}/price_transition: post: operationId: CreateBillingPriceTransition x-speakeasy-group: billing x-speakeasy-name-override: createPriceTransition tags: - Billing summary: Create a Price Transition for a Subscription Item description: 'Creates a price transition for the specified subscription item. This may create an upcoming subscription item or activate immediately depending on plan and payer rules.' parameters: - name: subscription_item_id in: path description: The ID of the subscription item to transition required: true schema: type: string requestBody: description: Parameters for the price transition required: true content: application/json: schema: $ref: '#/components/schemas/PriceTransitionRequest' responses: '200': $ref: '#/components/responses/CommercePriceTransition' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/ClerkErrors' /billing/statements: get: operationId: GetBillingStatementList x-speakeasy-group: billing x-speakeasy-name-override: listStatements tags: - Billing summary: List All Billing Statements description: 'Returns a list of all billing statements for the instance. The statements are returned sorted by creation date, with the newest statements appearing first. Pagination is supported.' parameters: - $ref: '#/components/parameters/Paginated' - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' responses: '200': $ref: '#/components/responses/BillingStatement.List' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/ClerkErrors' /billing/statements/{statementID}: get: operationId: GetBillingStatement x-speakeasy-group: billing x-speakeasy-name-override: getStatement tags: - Billing summary: Retrieve a Billing Statement description: Retrieves the details of a billing statement. parameters: - name: statementID in: path description: The ID of the statement to retrieve. required: true schema: type: string responses: '200': $ref: '#/components/responses/BillingStatement' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/ClerkErrors' /billing/statements/{statementID}/payment_attempts: get: operationId: GetBillingStatementPaymentAttempts x-speakeasy-group: billing x-speakeasy-name-override: getStatementPaymentAttempts tags: - Billing summary: List Payment Attempts for a Billing Statement description: 'Returns a list of all payment attempts for a specific billing statement. The payment attempts are returned sorted by creation date, with the newest payment attempts appearing first. Pagination is supported.' parameters: - name: statementID in: path description: The ID of the statement to retrieve payment attempts for. required: true schema: type: string - $ref: '#/components/parameters/Paginated' - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' responses: '200': $ref: '#/components/responses/BillingPaymentAttempt.List' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '500': $ref: '#/components/responses/ClerkErrors' /organization_permissions: get: operationId: ListOrganizationPermissions x-speakeasy-group: organizationPermissions x-speakeasy-name-override: list summary: Get a List of All Organization Permissions description: Retrieves all organization permissions for the given instance. tags: - Organization Permissions parameters: - name: query in: query description: 'Returns organization permissions with ID, name, or key that match the given query. Uses exact match for permission ID and partial match for name and key.' schema: type: string required: false - name: order_by in: query description: 'Allows to return organization permissions in a particular order. At the moment, you can order the returned permissions by their `created_at`, `name`, or `key`. In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. For example, if you want permissions to be returned in descending order according to their `created_at` property, you can use `-created_at`.' schema: type: string required: false - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' responses: '200': $ref: '#/components/responses/Permissions' '401': $ref: '#/components/responses/AuthenticationInvalid' '422': $ref: '#/components/responses/UnprocessableEntity' post: operationId: CreateOrganizationPermission x-speakeasy-group: organizationPermissions x-speakeasy-name-override: create summary: Create a New Organization Permission description: Creates a new organization permission for the given instance. tags: - Organization Permissions requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: The name of the permission. key: type: string description: The key of the permission. Must have the format "org:feature:action" where feature and action are segments consisting of lowercase letters, digits, or underscores, for example "org:billing:manage" or "org:team:read". Cannot begin with "org:sys_" as that prefix is reserved for system permissions. description: type: string description: A description of the permission. required: - name - key responses: '200': $ref: '#/components/responses/Permission' '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' /organization_permissions/{permission_id}: get: operationId: GetOrganizationPermission x-speakeasy-group: organizationPermissions x-speakeasy-name-override: get summary: Get an Organization Permission description: Retrieves the details of an organization permission. tags: - Organization Permissions parameters: - in: path required: true name: permission_id schema: type: string description: The ID of the permission to retrieve responses: '200': $ref: '#/components/responses/Permission' '401': $ref: '#/components/responses/AuthenticationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' patch: operationId: UpdateOrganizationPermission x-speakeasy-group: organizationPermissions x-speakeasy-name-override: update summary: Update an Organization Permission description: 'Updates the properties of an existing organization permission. System permissions cannot be updated.' tags: - Organization Permissions parameters: - in: path required: true name: permission_id schema: type: string description: The ID of the permission to update requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: The name of the permission. key: type: string description: The key of the permission. Must have the format "org:feature:action" where feature and action are segments consisting of lowercase letters, digits, or underscores. Cannot begin with "org:sys_" as that prefix is reserved for system permissions. description: type: string description: A description of the permission. responses: '200': $ref: '#/components/responses/Permission' '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' delete: operationId: DeleteOrganizationPermission x-speakeasy-group: organizationPermissions x-speakeasy-name-override: delete summary: Delete an Organization Permission description: 'Deletes an organization permission. System permissions cannot be deleted.' tags: - Organization Permissions parameters: - in: path required: true name: permission_id schema: type: string description: The ID of the permission to delete responses: '200': $ref: '#/components/responses/DeletedObject' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' /role_sets: get: operationId: ListRoleSets x-speakeasy-group: roleSets x-speakeasy-name-override: list summary: Get a List of Role Sets description: 'Returns a list of role sets for the instance. Results can be paginated using the optional `limit` and `offset` query parameters. The role sets are ordered by descending creation date by default.' tags: - Role Sets parameters: - in: query name: query description: 'Returns role sets with ID, name, or key that match the given query. Uses exact match for role set ID and partial match for name and key.' required: false schema: type: string - in: query name: order_by description: 'Allows to return role sets in a particular order. At the moment, you can order the returned role sets by their `created_at`, `name`, or `key`. In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. For example, if you want role sets 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`.' required: false schema: type: string default: -created_at - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' responses: '200': $ref: '#/components/responses/RoleSets' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '422': $ref: '#/components/responses/UnprocessableEntity' post: operationId: CreateRoleSet x-speakeasy-group: roleSets x-speakeasy-name-override: create summary: Create a Role Set description: 'Creates a new role set with the given name and roles. The key must be unique for the instance and start with the ''role_set:'' prefix, followed by lowercase alphanumeric characters and underscores only. You must provide at least one role and specify a default role key and creator role key.' tags: - Role Sets requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: The name of the new role set key: type: string description: 'A unique key for the role set. Must start with ''role_set:'' and contain only lowercase alphanumeric characters and underscores. If not provided, a key will be generated from the name.' description: type: string description: Optional description for the role set nullable: true default_role_key: type: string description: 'The key of the role to use as the default role for new organization members. Must be one of the roles in the `roles` array.' creator_role_key: type: string description: 'The key of the role to assign to organization creators. Must be one of the roles in the `roles` array.' type: type: string enum: - initial - custom description: 'The type of the role set. "initial" role sets are the default for new organizations. Only one role set can be "initial" per instance.' roles: type: array items: type: string description: 'Array of role keys to include in the role set. Must contain at least one role and no more than 10 roles.' additionalProperties: false required: - name - default_role_key - creator_role_key - roles responses: '200': $ref: '#/components/responses/RoleSet' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /role_sets/{role_set_key_or_id}: get: operationId: GetRoleSet x-speakeasy-group: roleSets x-speakeasy-name-override: get summary: Retrieve a Role Set description: Retrieves an existing role set by its key or ID. tags: - Role Sets parameters: - in: path required: true name: role_set_key_or_id schema: type: string description: The key or ID of the role set responses: '200': $ref: '#/components/responses/RoleSet' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' patch: operationId: UpdateRoleSet x-speakeasy-group: roleSets x-speakeasy-name-override: update summary: Update a Role Set description: 'Updates an existing role set. You can update the name, key, description, type, default role, or creator role. All parameters are optional - you can update only the fields you want to change.' tags: - Role Sets parameters: - in: path required: true name: role_set_key_or_id schema: type: string description: The key or ID of the role set to update requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: The new name for the role set nullable: true key: type: string description: A unique key for the role set. Must start with 'role_set:' and contain only lowercase alphanumeric characters and underscores. nullable: true description: type: string description: Optional description for the role set nullable: true type: type: string enum: - initial description: 'Set to "initial" to make this the default role set for new organizations. Only one role set can be "initial" per instance; setting this will change any existing initial role set to "custom".' nullable: true default_role_key: type: string description: 'The key of the role to use as the default role for new organization members. Must be an existing role in the role set.' nullable: true creator_role_key: type: string description: 'The key of the role to assign to organization creators. Must be an existing role in the role set.' nullable: true responses: '200': $ref: '#/components/responses/RoleSet' '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' /role_sets/{role_set_key_or_id}/replace: post: operationId: ReplaceRoleSet x-speakeasy-group: roleSets x-speakeasy-name-override: replace summary: Replace a Role Set description: 'Replaces a role set with another role set. This is functionally equivalent to deleting the role set but allows for atomic replacement with migration support. Organizations using this role set will be migrated to the destination role set.' tags: - Role Sets parameters: - in: path required: true name: role_set_key_or_id schema: type: string description: The key or ID of the role set to replace requestBody: required: true content: application/json: schema: type: object properties: dest_role_set_key: type: string description: The key of the destination role set reassignment_mappings: allOf: - $ref: '#/components/schemas/ReassignmentMappings' description: 'Mappings from source role keys to destination role keys. Required if members have roles that need to be reassigned.' required: - dest_role_set_key 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' '422': $ref: '#/components/responses/UnprocessableEntity' /role_sets/{role_set_key_or_id}/roles: post: operationId: AddRolesToRoleSet x-speakeasy-group: roleSets x-speakeasy-name-override: addRoles summary: Add Roles to a Role Set description: 'Adds one or more roles to an existing role set. You can optionally update the default role or creator role when adding new roles.' tags: - Role Sets parameters: - in: path required: true name: role_set_key_or_id schema: type: string description: The key or ID of the role set requestBody: required: true content: application/json: schema: type: object properties: role_keys: type: array items: type: string description: 'Array of role keys to add to the role set. Must contain at least one role and no more than 10 roles.' default_role_key: type: string description: Optionally update the default role to one of the newly added roles. creator_role_key: type: string description: Optionally update the creator role to one of the newly added roles. required: - role_keys responses: '200': $ref: '#/components/responses/RoleSet' '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' /role_sets/{role_set_key_or_id}/roles/replace: post: operationId: ReplaceRoleInRoleSet x-speakeasy-group: roleSets x-speakeasy-name-override: replaceRole summary: Replace a Role in a Role Set description: 'Replaces a role in a role set with another role. This atomically removes the source role and reassigns any members to the destination role.' tags: - Role Sets parameters: - in: path required: true name: role_set_key_or_id schema: type: string description: The key or ID of the role set requestBody: required: true content: application/json: schema: type: object properties: role_key: type: string description: The key of the role to remove from the role set to_role_key: type: string description: The key of the role to reassign members to required: - role_key - to_role_key responses: '200': $ref: '#/components/responses/RoleSet' '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' /audit_logs: {} /audit_logs/{event_time_and_id}: {} /scim_directories: {} /scim_directories/{scim_directory_id}: {} /api_keys: post: operationId: createApiKey summary: Create an API Key tags: - API Keys requestBody: required: true content: application/json: schema: type: object properties: type: type: string minLength: 3 maxLength: 25 default: api_key name: type: string minLength: 3 pattern: ^(\S(.*\S)?)?$ description: type: string nullable: true maxLength: 255 subject: type: string pattern: ^(user|org|mch|scim)_\w{27}$ claims: nullable: true scopes: type: array items: type: string default: [] created_by: type: string nullable: true pattern: ^user_\w{27}$ seconds_until_expiration: type: number nullable: true minimum: 0 exclusiveMinimum: true required: - name - subject additionalProperties: false responses: '200': description: 200 OK content: application/json: schema: type: object properties: object: type: string enum: - api_key id: type: string pattern: ^ak_[0-9A-Fa-f]{32}$ example: ak_3beecc9c60adb5f9b850e91a8ee1e992 type: type: string minLength: 3 example: api_key subject: type: string pattern: ^(user|org|mch)_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk name: type: string example: MY_SERVICE_API_KEY description: type: string nullable: true maxLength: 255 example: This is my API Key claims: nullable: true example: foo: bar scopes: type: array items: type: string example: - read - write secret: type: string example: ak_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX revoked: type: boolean example: false revocation_reason: type: string nullable: true example: Revoked by user expired: type: boolean example: false expiration: type: number nullable: true description: The timestamp for when the API key will expire, in milliseconds example: 1716883200 created_by: type: string nullable: true pattern: ^user_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk last_used_at: type: number nullable: true description: The timestamp for when the API key was last used, in milliseconds example: 1716883200 created_at: type: number description: The timestamp for when the API key was created, in milliseconds example: 1716883200 updated_at: type: number description: The timestamp for when the API key was last updated, in milliseconds example: 1716883200 required: - object - id - type - subject - name - claims - scopes - secret - revoked - revocation_reason - expired - expiration - created_by - last_used_at - created_at - updated_at additionalProperties: false '400': description: 400 Bad Request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: Bad Request long_message: type: string example: 'Invalid ''url_parameter.example'': Failed regex check' code: type: string example: bad_request required: - message - long_message - code required: - errors '409': description: 409 Conflict content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: some details about the error long_message: type: string example: some details about the error code: type: string example: some_error_code required: - message - long_message - code required: - errors get: operationId: getApiKeys summary: Get API Keys tags: - API Keys parameters: - schema: type: string minLength: 3 default: api_key required: false name: type in: query - schema: type: string pattern: ^(user|org|mch|scim)_\w{27}$ required: true name: subject in: query - schema: type: string enum: - 'true' - 'false' default: 'false' required: false name: include_invalid in: query - schema: type: number minimum: 1 maximum: 100 default: 10 required: false name: limit in: query - schema: type: number nullable: true minimum: 0 default: 0 required: false name: offset in: query - schema: type: string required: false name: query in: query responses: '200': description: 200 OK content: application/json: schema: type: object properties: data: type: array items: type: object properties: object: type: string enum: - api_key id: type: string pattern: ^ak_[0-9A-Fa-f]{32}$ example: ak_3beecc9c60adb5f9b850e91a8ee1e992 type: type: string minLength: 3 example: api_key subject: type: string pattern: ^(user|org|mch)_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk name: type: string example: MY_SERVICE_API_KEY description: type: string nullable: true maxLength: 255 example: This is my API Key claims: nullable: true example: foo: bar scopes: type: array items: type: string example: - read - write revoked: type: boolean example: false revocation_reason: type: string nullable: true example: Revoked by user expired: type: boolean example: false expiration: type: number nullable: true description: The timestamp for when the API key will expire, in milliseconds example: 1716883200 created_by: type: string nullable: true pattern: ^user_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk last_used_at: type: number nullable: true description: The timestamp for when the API key was last used, in milliseconds example: 1716883200 created_at: type: number description: The timestamp for when the API key was created, in milliseconds example: 1716883200 updated_at: type: number description: The timestamp for when the API key was last updated, in milliseconds example: 1716883200 required: - object - id - type - subject - name - claims - scopes - revoked - revocation_reason - expired - expiration - created_by - last_used_at - created_at - updated_at additionalProperties: false total_count: type: number required: - data - total_count '400': description: 400 Bad Request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: Bad Request long_message: type: string example: 'Invalid ''url_parameter.example'': Failed regex check' code: type: string example: bad_request required: - message - long_message - code required: - errors '404': description: 404 Not Found content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: some details about the error long_message: type: string example: some details about the error code: type: string example: some_error_code required: - message - long_message - code required: - errors /api_keys/{apiKeyID}: get: operationId: getApiKey summary: Get an API Key by ID tags: - API Keys parameters: - schema: type: string pattern: ^(ak|api_key)_[0-9A-Fa-f]{32}$ required: true name: apiKeyID in: path responses: '200': description: 200 OK content: application/json: schema: type: object properties: object: type: string enum: - api_key id: type: string pattern: ^ak_[0-9A-Fa-f]{32}$ example: ak_3beecc9c60adb5f9b850e91a8ee1e992 type: type: string minLength: 3 example: api_key subject: type: string pattern: ^(user|org|mch)_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk name: type: string example: MY_SERVICE_API_KEY description: type: string nullable: true maxLength: 255 example: This is my API Key claims: nullable: true example: foo: bar scopes: type: array items: type: string example: - read - write revoked: type: boolean example: false revocation_reason: type: string nullable: true example: Revoked by user expired: type: boolean example: false expiration: type: number nullable: true description: The timestamp for when the API key will expire, in milliseconds example: 1716883200 created_by: type: string nullable: true pattern: ^user_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk last_used_at: type: number nullable: true description: The timestamp for when the API key was last used, in milliseconds example: 1716883200 created_at: type: number description: The timestamp for when the API key was created, in milliseconds example: 1716883200 updated_at: type: number description: The timestamp for when the API key was last updated, in milliseconds example: 1716883200 required: - object - id - type - subject - name - claims - scopes - revoked - revocation_reason - expired - expiration - created_by - last_used_at - created_at - updated_at additionalProperties: false '400': description: 400 Bad Request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: Bad Request long_message: type: string example: 'Invalid ''url_parameter.example'': Failed regex check' code: type: string example: bad_request required: - message - long_message - code required: - errors '404': description: 404 Not Found content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: some details about the error long_message: type: string example: some details about the error code: type: string example: some_error_code required: - message - long_message - code required: - errors patch: operationId: updateApiKey summary: Update an API Key tags: - API Keys parameters: - schema: type: string pattern: ^(ak|api_key)_[0-9A-Fa-f]{32}$ required: true name: apiKeyID in: path requestBody: required: true content: application/json: schema: type: object properties: claims: nullable: true scopes: type: array items: type: string description: type: string nullable: true maxLength: 255 subject: type: string pattern: ^(user|org|mch|scim)_\w{27}$ seconds_until_expiration: type: number nullable: true minimum: 0 exclusiveMinimum: true additionalProperties: false responses: '200': description: 200 OK content: application/json: schema: type: object properties: object: type: string enum: - api_key id: type: string pattern: ^ak_[0-9A-Fa-f]{32}$ example: ak_3beecc9c60adb5f9b850e91a8ee1e992 type: type: string minLength: 3 example: api_key subject: type: string pattern: ^(user|org|mch)_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk name: type: string example: MY_SERVICE_API_KEY description: type: string nullable: true maxLength: 255 example: This is my API Key claims: nullable: true example: foo: bar scopes: type: array items: type: string example: - read - write revoked: type: boolean example: false revocation_reason: type: string nullable: true example: Revoked by user expired: type: boolean example: false expiration: type: number nullable: true description: The timestamp for when the API key will expire, in milliseconds example: 1716883200 created_by: type: string nullable: true pattern: ^user_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk last_used_at: type: number nullable: true description: The timestamp for when the API key was last used, in milliseconds example: 1716883200 created_at: type: number description: The timestamp for when the API key was created, in milliseconds example: 1716883200 updated_at: type: number description: The timestamp for when the API key was last updated, in milliseconds example: 1716883200 required: - object - id - type - subject - name - claims - scopes - revoked - revocation_reason - expired - expiration - created_by - last_used_at - created_at - updated_at additionalProperties: false '400': description: 400 Bad Request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: Bad Request long_message: type: string example: 'Invalid ''url_parameter.example'': Failed regex check' code: type: string example: bad_request required: - message - long_message - code required: - errors '404': description: 404 Not Found content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: some details about the error long_message: type: string example: some details about the error code: type: string example: some_error_code required: - message - long_message - code required: - errors delete: operationId: deleteApiKey summary: Delete an API Key tags: - API Keys parameters: - schema: type: string pattern: ^(ak|api_key)_[0-9A-Fa-f]{32}$ required: true name: apiKeyID in: path responses: '200': description: 200 OK content: application/json: schema: type: object properties: id: type: string example: ak_3beecc9c60adb5f9b850e91a8ee1e992 object: type: string enum: - api_key deleted: type: boolean enum: - true required: - id - object - deleted '400': description: 400 Bad Request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: Bad Request long_message: type: string example: 'Invalid ''url_parameter.example'': Failed regex check' code: type: string example: bad_request required: - message - long_message - code required: - errors '404': description: 404 Not Found content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: some details about the error long_message: type: string example: some details about the error code: type: string example: some_error_code required: - message - long_message - code required: - errors /api_keys/{apiKeyID}/secret: get: operationId: getApiKeySecret summary: Get an API Key Secret tags: - API Keys parameters: - schema: type: string pattern: ^(ak|api_key)_[0-9A-Fa-f]{32}$ required: true name: apiKeyID in: path responses: '200': description: 200 OK content: application/json: schema: type: object properties: secret: type: string required: - secret '400': description: 400 Bad Request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: Bad Request long_message: type: string example: 'Invalid ''url_parameter.example'': Failed regex check' code: type: string example: bad_request required: - message - long_message - code required: - errors '404': description: 404 Not Found content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: some details about the error long_message: type: string example: some details about the error code: type: string example: some_error_code required: - message - long_message - code required: - errors /api_keys/{apiKeyID}/revoke: post: operationId: revokeApiKey summary: Revoke an API Key tags: - API Keys parameters: - schema: type: string pattern: ^(ak|api_key)_[0-9A-Fa-f]{32}$ required: true name: apiKeyID in: path requestBody: required: true content: application/json: schema: type: object properties: revocation_reason: type: string nullable: true additionalProperties: false responses: '200': description: 200 OK content: application/json: schema: type: object properties: object: type: string enum: - api_key id: type: string pattern: ^ak_[0-9A-Fa-f]{32}$ example: ak_3beecc9c60adb5f9b850e91a8ee1e992 type: type: string minLength: 3 example: api_key subject: type: string pattern: ^(user|org|mch)_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk name: type: string example: MY_SERVICE_API_KEY description: type: string nullable: true maxLength: 255 example: This is my API Key claims: nullable: true example: foo: bar scopes: type: array items: type: string example: - read - write revoked: type: boolean example: false revocation_reason: type: string nullable: true example: Revoked by user expired: type: boolean example: false expiration: type: number nullable: true description: The timestamp for when the API key will expire, in milliseconds example: 1716883200 created_by: type: string nullable: true pattern: ^user_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk last_used_at: type: number nullable: true description: The timestamp for when the API key was last used, in milliseconds example: 1716883200 created_at: type: number description: The timestamp for when the API key was created, in milliseconds example: 1716883200 updated_at: type: number description: The timestamp for when the API key was last updated, in milliseconds example: 1716883200 required: - object - id - type - subject - name - claims - scopes - revoked - revocation_reason - expired - expiration - created_by - last_used_at - created_at - updated_at additionalProperties: false '400': description: 400 Bad Request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: Bad Request long_message: type: string example: 'Invalid ''url_parameter.example'': Failed regex check' code: type: string example: bad_request required: - message - long_message - code required: - errors '404': description: 404 Not Found content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: some details about the error long_message: type: string example: some details about the error code: type: string example: some_error_code required: - message - long_message - code required: - errors /api_keys/verify: post: operationId: verifyApiKey summary: Verify an API Key tags: - API Keys requestBody: required: true content: application/json: schema: type: object properties: secret: type: string required: - secret additionalProperties: false responses: '200': description: 200 OK content: application/json: schema: type: object properties: object: type: string enum: - api_key id: type: string pattern: ^ak_[0-9A-Fa-f]{32}$ example: ak_3beecc9c60adb5f9b850e91a8ee1e992 type: type: string minLength: 3 example: api_key subject: type: string pattern: ^(user|org|mch)_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk name: type: string example: MY_SERVICE_API_KEY description: type: string nullable: true maxLength: 255 example: This is my API Key claims: nullable: true example: foo: bar scopes: type: array items: type: string example: - read - write revoked: type: boolean example: false revocation_reason: type: string nullable: true example: Revoked by user expired: type: boolean example: false expiration: type: number nullable: true description: The timestamp for when the API key will expire, in milliseconds example: 1716883200 created_by: type: string nullable: true pattern: ^user_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk last_used_at: type: number nullable: true description: The timestamp for when the API key was last used, in milliseconds example: 1716883200 created_at: type: number description: The timestamp for when the API key was created, in milliseconds example: 1716883200 updated_at: type: number description: The timestamp for when the API key was last updated, in milliseconds example: 1716883200 required: - object - id - type - subject - name - claims - scopes - revoked - revocation_reason - expired - expiration - created_by - last_used_at - created_at - updated_at additionalProperties: false '400': description: 400 Bad Request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: Bad Request long_message: type: string example: 'Invalid ''url_parameter.example'': Failed regex check' code: type: string example: bad_request required: - message - long_message - code required: - errors '404': description: 404 Not Found content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: some details about the error long_message: type: string example: some details about the error code: type: string example: some_error_code required: - message - long_message - code required: - errors /m2m_tokens: post: x-speakeasy-group: m2m x-speakeasy-name-override: createToken operationId: createM2MToken summary: Create a M2M Token description: Creates a new M2M Token. Must be authenticated via a Machine Secret Key. tags: - M2M Tokens requestBody: required: true content: application/json: schema: type: object properties: token_format: type: string enum: - opaque - jwt default: opaque seconds_until_expiration: type: number nullable: true minimum: 0 exclusiveMinimum: true claims: nullable: true min_remaining_ttl_seconds: type: integer minimum: 0 description: 'Enables server-side token reuse for opaque-format tokens. When set, if a non-revoked, non-expired M2M token already exists for this machine with identical `claims` and `scopes` and at least this many seconds of remaining lifetime, that existing token is returned and no new token is minted. Use this when caching tokens in application memory across requests is impractical — for example, in serverless functions, short-lived job workers, or autoscaling containers that churn faster than the token TTL. Pooling at the server collapses many redundant create calls into reuse of a single live token, which is the recommended pattern for high-volume M2M traffic. Must be strictly less than the effective token lifetime — that is, `seconds_until_expiration` when provided, or the machine''s default TTL otherwise. A value greater than or equal to the lifetime is rejected with a 400, since no freshly-minted token would ever satisfy the requirement. Only applies to opaque-format tokens (`token_format` defaults to `opaque`). JWT-format tokens are stateless and are never deduplicated.' example: 240 additionalProperties: false responses: '201': description: 201 Created content: application/json: schema: type: object properties: object: type: string enum: - machine_to_machine_token id: type: string pattern: ^mt_[0-9A-Fa-f]{32}$ example: mt_f7f0ba8c3b4843ce7d85fcdd5e71853e subject: type: string pattern: ^mch_\w{27}$ example: mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk claims: nullable: true example: important_metadata: Some useful data scopes: type: array items: type: string pattern: ^mch_\w{27}$ default: [] example: - mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk - mch_2yGkLpQ7Y3rXSwtU24CzTk9I7Em token: type: string example: mt_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX revoked: type: boolean example: false revocation_reason: type: string nullable: true example: Revoked by user expired: type: boolean example: false expiration: type: number nullable: true description: The timestamp for when the token will expire, in milliseconds example: 1716883200 last_used_at: type: number nullable: true description: The timestamp for when the token was last used, in milliseconds example: 1716883200 created_at: type: number description: The timestamp for when the token was created, in milliseconds example: 1716883200 updated_at: type: number description: The timestamp for when the token was last updated, in milliseconds example: 1716883200 required: - object - id - subject - token - revoked - revocation_reason - expired - expiration - last_used_at - created_at - updated_at additionalProperties: false '400': description: 400 Bad Request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: Bad Request long_message: type: string example: 'Invalid ''url_parameter.example'': Failed regex check' code: type: string example: bad_request required: - message - long_message - code required: - errors '409': description: 409 Conflict content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: some details about the error long_message: type: string example: some details about the error code: type: string example: some_error_code required: - message - long_message - code required: - errors get: x-speakeasy-group: m2m x-speakeasy-name-override: listTokens operationId: getM2MTokens summary: Get M2M Tokens description: 'Fetches M2M tokens for a specific machine. Only tokens created with the opaque token format are returned by this endpoint. JWT-format M2M tokens are stateless and are not stored. This endpoint can be authenticated by either a Machine Secret Key or by a Clerk Secret Key. - When fetching M2M tokens with a Machine Secret Key, only tokens associated with the authenticated machine can be retrieved. - When fetching M2M tokens with a Clerk Secret Key, tokens for any machine in the instance can be retrieved.' tags: - M2M Tokens parameters: - schema: type: string pattern: ^mch_\w{27}$ required: true name: subject in: query - schema: type: boolean nullable: true default: false required: false name: revoked in: query - schema: type: boolean nullable: true default: false required: false name: expired in: query - schema: type: number minimum: 1 maximum: 100 default: 10 required: false name: limit in: query - schema: type: number nullable: true minimum: 0 default: 0 required: false name: offset in: query responses: '200': description: 200 OK content: application/json: schema: type: object properties: m2m_tokens: type: array items: type: object properties: object: type: string enum: - machine_to_machine_token id: type: string pattern: ^mt_[0-9A-Fa-f]{32}$ example: mt_f7f0ba8c3b4843ce7d85fcdd5e71853e subject: type: string pattern: ^mch_\w{27}$ example: mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk claims: nullable: true example: important_metadata: Some useful data scopes: type: array items: type: string pattern: ^mch_\w{27}$ default: [] example: - mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk - mch_2yGkLpQ7Y3rXSwtU24CzTk9I7Em revoked: type: boolean example: false revocation_reason: type: string nullable: true example: Revoked by user expired: type: boolean example: false expiration: type: number nullable: true description: The timestamp for when the token will expire, in milliseconds example: 1716883200 last_used_at: type: number nullable: true description: The timestamp for when the token was last used, in milliseconds example: 1716883200 created_at: type: number description: The timestamp for when the token was created, in milliseconds example: 1716883200 updated_at: type: number description: The timestamp for when the token was last updated, in milliseconds example: 1716883200 required: - object - id - subject - revoked - revocation_reason - expired - expiration - last_used_at - created_at - updated_at additionalProperties: false total_count: type: number required: - m2m_tokens - total_count additionalProperties: false '400': description: 400 Bad Request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: Bad Request long_message: type: string example: 'Invalid ''url_parameter.example'': Failed regex check' code: type: string example: bad_request required: - message - long_message - code required: - errors '403': description: 403 Forbidden content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: some details about the error long_message: type: string example: some details about the error code: type: string example: some_error_code required: - message - long_message - code required: - errors '404': description: 404 Not Found content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: some details about the error long_message: type: string example: some details about the error code: type: string example: some_error_code required: - message - long_message - code required: - errors /m2m_tokens/{m2m_token_id}/revoke: post: x-speakeasy-group: m2m x-speakeasy-name-override: revokeToken operationId: revokeM2MToken summary: Revoke a M2M Token description: 'Revokes a M2M Token. This endpoint only revokes stored opaque-format M2M tokens. JWT-format M2M tokens are stateless and cannot be revoked. This endpoint can be authenticated by either a Machine Secret Key or by a Clerk Secret Key. - When revoking a M2M Token with a Machine Secret Key, the token must managed by the Machine associated with the Machine Secret Key. - When revoking a M2M Token with a Clerk Secret Key, any token on the Instance can be revoked.' tags: - M2M Tokens parameters: - schema: type: string pattern: ^mt_[0-9A-Fa-f]{32}$ required: true name: m2m_token_id in: path requestBody: required: true content: application/json: schema: type: object properties: revocation_reason: type: string nullable: true additionalProperties: false responses: '200': description: 200 OK content: application/json: schema: type: object properties: object: type: string enum: - machine_to_machine_token id: type: string pattern: ^mt_[0-9A-Fa-f]{32}$ example: mt_f7f0ba8c3b4843ce7d85fcdd5e71853e subject: type: string pattern: ^mch_\w{27}$ example: mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk claims: nullable: true example: important_metadata: Some useful data scopes: type: array items: type: string pattern: ^mch_\w{27}$ default: [] example: - mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk - mch_2yGkLpQ7Y3rXSwtU24CzTk9I7Em revoked: type: boolean example: false revocation_reason: type: string nullable: true example: Revoked by user expired: type: boolean example: false expiration: type: number nullable: true description: The timestamp for when the token will expire, in milliseconds example: 1716883200 last_used_at: type: number nullable: true description: The timestamp for when the token was last used, in milliseconds example: 1716883200 created_at: type: number description: The timestamp for when the token was created, in milliseconds example: 1716883200 updated_at: type: number description: The timestamp for when the token was last updated, in milliseconds example: 1716883200 required: - object - id - subject - revoked - revocation_reason - expired - expiration - last_used_at - created_at - updated_at additionalProperties: false '400': description: 400 Bad Request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: Bad Request long_message: type: string example: 'Invalid ''url_parameter.example'': Failed regex check' code: type: string example: bad_request required: - message - long_message - code required: - errors '404': description: 404 Not Found content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: some details about the error long_message: type: string example: some details about the error code: type: string example: some_error_code required: - message - long_message - code required: - errors /m2m_tokens/verify: post: x-speakeasy-group: m2m x-speakeasy-name-override: verifyToken operationId: verifyM2MToken summary: Verify a M2M Token description: 'Verifies a M2M Token. This endpoint can be authenticated by either a Machine Secret Key or by a Clerk Secret Key. - When verifying a M2M Token with a Machine Secret Key, the token must be granted access to the Machine associated with the Machine Secret Key. - When verifying a M2M Token with a Clerk Secret Key, any token on the Instance can be verified.' tags: - M2M Tokens requestBody: required: true content: application/json: schema: type: object properties: token: type: string required: - token additionalProperties: false responses: '200': description: 200 OK content: application/json: schema: type: object properties: object: type: string enum: - machine_to_machine_token id: type: string pattern: ^mt_[0-9A-Fa-f]{32}$ example: mt_f7f0ba8c3b4843ce7d85fcdd5e71853e subject: type: string pattern: ^mch_\w{27}$ example: mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk claims: nullable: true example: important_metadata: Some useful data scopes: type: array items: type: string pattern: ^mch_\w{27}$ default: [] example: - mch_2xhFjEI5X2qWRvtV13BzSj8H6Dk - mch_2yGkLpQ7Y3rXSwtU24CzTk9I7Em revoked: type: boolean example: false revocation_reason: type: string nullable: true example: Revoked by user expired: type: boolean example: false expiration: type: number nullable: true description: The timestamp for when the token will expire, in milliseconds example: 1716883200 last_used_at: type: number nullable: true description: The timestamp for when the token was last used, in milliseconds example: 1716883200 created_at: type: number description: The timestamp for when the token was created, in milliseconds example: 1716883200 updated_at: type: number description: The timestamp for when the token was last updated, in milliseconds example: 1716883200 required: - object - id - subject - revoked - revocation_reason - expired - expiration - last_used_at - created_at - updated_at additionalProperties: false '400': description: 400 Bad Request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: Bad Request long_message: type: string example: 'Invalid ''url_parameter.example'': Failed regex check' code: type: string example: bad_request required: - message - long_message - code required: - errors '404': description: 404 Not Found content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: some details about the error long_message: type: string example: some details about the error code: type: string example: some_error_code required: - message - long_message - code required: - errors /oauth_applications/access_tokens/verify: post: x-speakeasy-group: oauthAccessTokens x-speakeasy-name-override: verify operationId: verifyOAuthAccessToken summary: Verify an OAuth Access Token tags: - OAuth Access Tokens requestBody: required: true content: application/json: schema: type: object properties: access_token: type: string description: The access token to verify. example: XXXXXXXXXXXXXX secret: type: string description: The access token to verify. This is deprecated, use `access_token` instead. deprecated: true example: XXXXXXXXXXXXXX responses: '200': description: 200 OK content: application/json: schema: anyOf: - type: object properties: object: type: string enum: - clerk_idp_oauth_access_token example: clerk_idp_oauth_access_token id: type: string pattern: ^oat_[0-9A-Fa-f]{32}$ example: oat_0ef5a7a33d87ed87ee7954c845d80450 client_id: type: string example: client_2xhFjEI5X2qWRvtV13BzSj8H6Dk subject: type: string pattern: ^user_\w{27}$ example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk scopes: type: array items: type: string example: - read - write revoked: type: boolean example: false revocation_reason: type: string nullable: true example: Revoked by user expired: type: boolean example: false expiration: type: number nullable: true example: 1716883200 created_at: type: number example: 1716883200 updated_at: type: number example: 1716883200 required: - object - id - client_id - subject - scopes - revoked - revocation_reason - expired - expiration - created_at - updated_at additionalProperties: false - type: object properties: active: type: boolean enum: - false description: Indicates that a JWT access token is not active (expired) example: false required: - active additionalProperties: false '400': description: 400 Bad Request content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: Bad Request long_message: type: string example: 'Invalid ''url_parameter.example'': Failed regex check' code: type: string example: bad_request required: - message - long_message - code required: - errors '404': description: 404 Not Found content: application/json: schema: type: object properties: errors: type: array items: type: object properties: message: type: string example: some details about the error long_message: type: string example: some details about the error code: type: string example: some_error_code required: - message - long_message - code required: - errors components: securitySchemes: bearerAuth: type: http scheme: bearer description: Secret key, obtained under "API Keys" in the Clerk Dashboard. bearerFormat: sk__ schemas: JWKS.ed25519.PublicKey: type: object properties: kid: type: string alg: type: string use: type: string kty: type: string enum: - OKP crv: type: string enum: - Ed25519 x: type: string x5c: type: array items: type: string x5t: type: string x5t#S256: type: string x5u: type: string required: - kid - alg - use - kty - crv - x JWKS.ecdsa.PublicKey: type: object properties: kid: type: string alg: type: string use: type: string kty: type: string enum: - EC crv: type: string x: type: string y: type: string x5c: type: array items: type: string x5t: type: string x5t#S256: type: string x5u: type: string required: - kid - alg - use - kty - crv - x - y JWKS.rsa.PublicKey: type: object properties: kid: type: string alg: type: string use: type: string kty: type: string enum: - RSA n: type: string e: type: string x5c: type: array items: type: string x5t: type: string x5t#S256: type: string x5u: type: string required: - kid - alg - use - kty - n - e JWKS.ed25519.PrivateKey: type: object properties: kid: type: string alg: type: string use: type: string kty: type: string enum: - OKP crv: type: string enum: - Ed25519 x: type: string d: type: string x5c: type: array items: type: string x5t: type: string x5t#S256: type: string x5u: type: string required: - kid - alg - use - kty - crv - x - d JWKS.ecdsa.PrivateKey: type: object properties: kid: type: string alg: type: string use: type: string kty: type: string enum: - EC crv: type: string x: type: string y: type: string d: type: string x5c: type: array items: type: string x5t: type: string x5t#S256: type: string x5u: type: string required: - kid - alg - use - kty - crv - x - y - d JWKS.rsa.PrivateKey: type: object properties: kid: type: string alg: type: string use: type: string kty: type: string enum: - RSA n: type: string e: type: string d: type: string p: type: string q: type: string dp: type: string dq: type: string qi: type: string x5c: type: array items: type: string x5t: type: string x5t#S256: type: string x5u: type: string required: - kid - alg - use - kty - crv - n - e - d - p - q JWKS.symmetric.Key: type: object properties: kid: type: string alg: type: string use: type: string kty: type: string enum: - oct k: type: string x5c: type: array items: type: string x5t: type: string x5t#S256: type: string x5u: type: string required: - kid - alg - use - kty - k JWKS: type: object additionalProperties: false properties: keys: type: array items: oneOf: - $ref: '#/components/schemas/JWKS.ed25519.PublicKey' - $ref: '#/components/schemas/JWKS.ecdsa.PublicKey' - $ref: '#/components/schemas/JWKS.rsa.PublicKey' - $ref: '#/components/schemas/JWKS.ed25519.PrivateKey' - $ref: '#/components/schemas/JWKS.ecdsa.PrivateKey' - $ref: '#/components/schemas/JWKS.rsa.PrivateKey' - $ref: '#/components/schemas/JWKS.symmetric.Key' SessionActivityResponse: type: object nullable: true properties: object: type: string id: type: string device_type: type: string is_mobile: type: boolean browser_name: type: string browser_version: type: string ip_address: type: string city: type: string country: type: string required: - id - object - is_mobile SessionTask: type: object properties: key: type: string required: - key 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 - replaced - pending last_active_organization_id: type: string nullable: true last_active_at: type: integer latest_activity: $ref: '#/components/schemas/SessionActivityResponse' expire_at: type: integer format: int64 description: 'Unix timestamp of expiration. ' abandon_at: type: integer format: int64 description: 'Unix timestamp of abandonment. ' updated_at: type: integer format: int64 description: 'Unix timestamp of last update. ' created_at: type: integer format: int64 description: 'Unix timestamp of creation. ' tasks: type: array nullable: true items: $ref: '#/components/schemas/SessionTask' 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_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. ' last_authentication_strategy: nullable: true type: string description: 'The authentication strategy that was last used to authenticate the user on this client. ' 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_id - sign_up_id - last_active_session_id - last_authentication_strategy - 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 clerk_trace_id: type: string required: - errors verification_otp: x-speakeasy-name-override: OTP type: object additionalProperties: false properties: object: type: string enum: - verification_otp status: type: string enum: - unverified - verified - failed - expired strategy: x-speakeasy-unknown-values: allow type: string enum: - phone_code - email_code - reset_password_email_code attempts: type: integer nullable: true expire_at: type: integer nullable: true verified_at_client: type: string nullable: true required: - status - strategy - attempts - expire_at verification_admin: x-speakeasy-name-override: Admin type: object additionalProperties: false properties: object: type: string enum: - verification_admin status: type: string enum: - verified strategy: x-speakeasy-unknown-values: allow type: string enum: - admin attempts: type: integer nullable: true expire_at: type: integer nullable: true verified_at_client: type: string nullable: true required: - status - strategy - attempts - expire_at verification_from_oauth: x-speakeasy-name-override: FromOAuth type: object additionalProperties: false properties: object: type: string enum: - verification_from_oauth status: type: string enum: - unverified - verified strategy: type: string pattern: ^from_oauth_(?:(?:token_)|(?:custom_))?[a-z]+$ error: type: object nullable: true oneOf: - $ref: '#/components/schemas/ClerkError' expire_at: type: integer nullable: true attempts: type: integer nullable: true verified_at_client: type: string nullable: true required: - status - strategy - attempts - expire_at verification_ticket: x-speakeasy-name-override: Ticket type: object additionalProperties: false properties: object: type: string enum: - verification_ticket status: type: string enum: - unverified - verified - expired strategy: x-speakeasy-unknown-values: allow type: string enum: - ticket attempts: type: integer nullable: true expire_at: type: integer nullable: true verified_at_client: type: string nullable: true required: - status - strategy - attempts - expire_at verification_saml: x-speakeasy-name-override: SAML type: object additionalProperties: false properties: object: type: string enum: - verification_saml status: type: string enum: - unverified - verified - failed - expired - transferable strategy: type: string enum: - saml external_verification_redirect_url: nullable: true type: string error: nullable: true type: object oneOf: - $ref: '#/components/schemas/ClerkError' expire_at: type: integer nullable: true attempts: type: integer nullable: true verified_at_client: type: string nullable: true required: - status - strategy - attempts verification_email_link: x-speakeasy-name-override: EmailLink type: object additionalProperties: false properties: object: type: string enum: - verification_email_link status: type: string enum: - unverified - verified - failed - expired strategy: type: string enum: - email_link attempts: type: integer nullable: true expire_at: type: integer nullable: true verified_at_client: type: string nullable: true required: - status - strategy - attempts - expire_at IdentificationLink: type: object additionalProperties: false properties: type: type: string pattern: ^oauth_[a-z]+$ id: type: string required: - type - id EmailAddress: type: object additionalProperties: false properties: id: type: string object: type: string x-speakeasy-unknown-values: allow 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/verification_otp' - $ref: '#/components/schemas/verification_admin' - $ref: '#/components/schemas/verification_from_oauth' - $ref: '#/components/schemas/verification_ticket' - $ref: '#/components/schemas/verification_saml' - $ref: '#/components/schemas/verification_email_link' discriminator: propertyName: object mapping: verification_otp: '#/components/schemas/verification_otp' verification_admin: '#/components/schemas/verification_admin' verification_from_oauth: '#/components/schemas/verification_from_oauth' verification_ticket: '#/components/schemas/verification_ticket' verification_saml: '#/components/schemas/verification_saml' verification_email_link: '#/components/schemas/verification_email_link' linked_to: type: array items: $ref: '#/components/schemas/IdentificationLink' matches_sso_connection: description: 'Indicates whether this email address domain matches an active enterprise connection. ' type: boolean created_at: type: integer format: int64 description: 'Unix timestamp of creation ' updated_at: type: integer format: int64 description: 'Unix timestamp of creation ' required: - object - email_address - verification - linked_to - reserved - created_at - updated_at DeletedObject: type: object additionalProperties: false properties: object: type: string id: type: string slug: type: string deleted: type: boolean external_id: type: string 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/verification_otp' - $ref: '#/components/schemas/verification_admin' discriminator: propertyName: object mapping: verification_otp: '#/components/schemas/verification_otp' verification_admin: '#/components/schemas/verification_admin' linked_to: type: array items: $ref: '#/components/schemas/IdentificationLink' backup_codes: type: array items: 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 creation ' required: - object - phone_number - verification - linked_to - reserved - created_at - updated_at Token: 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: - token jwt: type: string description: 'String representing the encoded JSON Web Token (JWT) value. ' required: - object - jwt Cookies: 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: - cookies cookies: type: array description: Array of cookie directives. items: type: string required: - object - cookies SessionRefresh: oneOf: - $ref: '#/components/schemas/Token' - $ref: '#/components/schemas/Cookies' 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 to which the template belongs 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 can_edit_body: type: boolean description: whether the body of this template can be edited can_toggle: type: boolean description: whether this template can be enabled or disabled, true only for notification SMS templates 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 reply_to_email_name: type: string delivered_by_clerk: type: boolean enabled: type: boolean flagged_as_suspicious: 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. ' verification_web3: x-speakeasy-name-override: Web3Signature type: object additionalProperties: false properties: object: type: string enum: - verification_web3 status: type: string enum: - unverified - verified - failed - expired strategy: type: string enum: - web3_metamask_signature - web3_base_signature - web3_coinbase_wallet_signature - web3_okx_wallet_signature - web3_solana_signature nonce: type: string nullable: true message: type: string nullable: true attempts: type: integer nullable: true expire_at: type: integer nullable: true verified_at_client: type: string nullable: true required: - status - strategy - attempts - expire_at 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/verification_web3' - $ref: '#/components/schemas/verification_admin' discriminator: propertyName: object created_at: type: integer format: int64 description: 'Unix timestamp of creation ' updated_at: type: integer format: int64 description: 'Unix timestamp of creation ' required: - object - web3_wallet - verification - created_at - updated_at verification_passkey: x-speakeasy-name-override: Passkey type: object additionalProperties: false properties: object: type: string enum: - verification_passkey status: type: string enum: - verified strategy: type: string enum: - passkey nonce: type: string enum: - nonce message: type: string nullable: true attempts: type: integer nullable: true expire_at: type: integer nullable: true verified_at_client: type: string nullable: true required: - status - strategy - attempts - expire_at Passkey: 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: - passkey name: type: string last_used_at: type: integer format: int64 description: 'Unix timestamp of when the passkey was last used. ' verification: type: object nullable: true oneOf: - $ref: '#/components/schemas/verification_passkey' discriminator: propertyName: object required: - object - name - last_used_at - verification verification_oauth: x-speakeasy-name-override: Oauth type: object additionalProperties: false properties: object: type: string enum: - verification_oauth status: type: string x-speakeasy-unknown-values: allow enum: - unverified - verified - failed - expired - transferable strategy: type: string x-speakeasy-unknown-values: allow pattern: ^oauth_(?:(?:token_)|(?:custom_))?[a-z]+$ external_verification_redirect_url: type: string error: type: object nullable: true oneOf: - $ref: '#/components/schemas/ClerkError' expire_at: type: integer attempts: type: integer nullable: true verified_at_client: type: string nullable: true required: - status - strategy - attempts - expire_at verification_google_one_tap: x-speakeasy-name-override: GoogleOneTap type: object additionalProperties: false properties: object: type: string enum: - verification_google_one_tap status: type: string enum: - unverified - verified strategy: type: string enum: - google_one_tap expire_at: type: integer nullable: true attempts: type: integer nullable: true verified_at_client: type: string nullable: true error: type: object nullable: true oneOf: - $ref: '#/components/schemas/ClerkError' required: - status - strategy - attempts - expire_at ExternalAccountWithVerification: type: object additionalProperties: true properties: object: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - external_account - facebook_account - google_account id: type: string provider: type: string identification_id: type: string provider_user_id: description: The unique ID of the user in the external provider's system type: string approved_scopes: type: string email_address: type: string email_address_verified: type: boolean nullable: true description: 'Whether the email was verified by the OAuth provider at creation time. null = unknown (pre-migration data or custom OAuth providers), true = provider confirmed email was verified, false = provider confirmed email was NOT verified ' first_name: type: string last_name: type: string avatar_url: type: string deprecated: true description: Please use `image_url` instead image_url: type: string nullable: true username: type: string nullable: true phone_number: type: string nullable: true public_metadata: type: object additionalProperties: true label: 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 creation ' verification: type: object nullable: true oneOf: - $ref: '#/components/schemas/verification_oauth' - $ref: '#/components/schemas/verification_google_one_tap' discriminator: propertyName: object required: - object - id - provider - identification_id - provider_user_id - approved_scopes - email_address - first_name - last_name - public_metadata - created_at - updated_at - verification SAMLAccountConnection: type: object additionalProperties: false properties: id: type: string name: type: string domain: type: string deprecated: true domains: type: array items: type: string active: type: boolean provider: type: string sync_user_attributes: type: boolean allow_subdomains: type: boolean allow_idp_initiated: type: boolean disable_additional_identifications: type: boolean created_at: type: integer format: int64 description: 'Unix timestamp of creation. ' updated_at: type: integer format: int64 description: 'Unix timestamp of last update. ' required: - id - name - active - provider - sync_user_attributes - created_at - updated_at anyOf: - required: - domain - required: - domains SAMLAccount: 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: - saml_account provider: type: string active: type: boolean email_address: type: string first_name: type: string nullable: true last_name: type: string nullable: true provider_user_id: type: string nullable: true last_authenticated_at: type: integer format: int64 nullable: true description: 'Unix timestamp of last authentication. ' public_metadata: type: object additionalProperties: true verification: type: object nullable: true oneOf: - $ref: '#/components/schemas/verification_saml' - $ref: '#/components/schemas/verification_ticket' discriminator: propertyName: object saml_connection: type: object nullable: true oneOf: - $ref: '#/components/schemas/SAMLAccountConnection' required: - id - object - provider - active - email_address - verification EnterpriseAccountConnection: type: object additionalProperties: false properties: id: type: string protocol: type: string provider: type: string name: type: string logo_public_url: type: string nullable: true domain: type: string deprecated: true domains: type: array items: type: string active: type: boolean sync_user_attributes: type: boolean allow_subdomains: type: boolean allow_idp_initiated: type: boolean disable_additional_identifications: type: boolean created_at: type: integer format: int64 description: 'Unix timestamp of creation. ' updated_at: type: integer format: int64 description: 'Unix timestamp of last update. ' required: - id - protocol - name - logo_public_url - active - provider - sync_user_attributes - disable_additional_identifications - allow_subdomains - allow_idp_initiated - created_at - updated_at anyOf: - required: - domain - required: - domains EnterpriseAccount: 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: - enterprise_account protocol: type: string description: 'The authentication protocol used to sign in. ' enum: - oauth - saml provider: type: string active: type: boolean email_address: type: string first_name: type: string nullable: true last_name: type: string nullable: true provider_user_id: description: The unique ID of the user in the external provider's system type: string nullable: true enterprise_connection_id: type: string nullable: true public_metadata: type: object additionalProperties: true verification: type: object nullable: true oneOf: - $ref: '#/components/schemas/verification_ticket' - $ref: '#/components/schemas/verification_saml' - $ref: '#/components/schemas/verification_oauth' discriminator: propertyName: object enterprise_connection: type: object nullable: true oneOf: - $ref: '#/components/schemas/EnterpriseAccountConnection' last_authenticated_at: type: integer format: int64 nullable: true description: 'Unix timestamp of last authentication. ' required: - id - object - provider - active - email_address - verification Organization: type: object properties: object: type: string enum: - organization id: type: string name: type: string slug: type: string image_url: type: string has_image: type: boolean members_count: type: integer missing_member_with_elevated_permissions: type: boolean pending_invitations_count: type: integer max_allowed_memberships: type: integer admin_delete_enabled: type: boolean public_metadata: type: object additionalProperties: true private_metadata: type: object additionalProperties: true 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. ' last_active_at: type: integer format: int64 description: 'Unix timestamp of last activity. ' role_set_key: type: string description: 'The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) assigned to this organization. ' nullable: true required: - object - id - name - slug - has_image - max_allowed_memberships - admin_delete_enabled - public_metadata - created_at - updated_at OrganizationMembershipPublicUserData: description: An organization membership with public user data populated 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 has_image: type: boolean identifier: type: string nullable: true username: type: string nullable: true banned: type: boolean required: - user_id - first_name - last_name - profile_image_url - image_url - has_image OrganizationMembership: description: A user's membership in an organization 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 role_name: type: string permissions: type: array items: type: string public_metadata: type: object description: Metadata saved on the organization membership, accessible from both Frontend and Backend APIs additionalProperties: true private_metadata: type: object description: Metadata saved on the organization membership, accessible only from the Backend API additionalProperties: true organization: type: object nullable: false allOf: - $ref: '#/components/schemas/Organization' public_user_data: $ref: '#/components/schemas/OrganizationMembershipPublicUserData' 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 - role - permissions - public_metadata - created_at - updated_at - organization SCIMUserMetadata: type: object additionalProperties: false description: 'Metadata describing a user''s linkage to a SCIM directory. This object is only delivered on `user.created` and `user.updated` webhook events, and only when the user is provisioned through a SCIM directory. Its absence does not necessarily mean the user is not SCIM-managed. ' properties: directory_id: type: string description: 'The ID of the SCIM directory the user is provisioned from. ' directory_enabled: type: boolean description: 'Whether the SCIM directory is currently enabled. Omitted when false. ' external_id: type: string nullable: true description: 'The user''s external ID as reported by the SCIM directory, if any. ' required: - directory_id - external_id 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 locale: nullable: true type: string profile_image_url: type: string deprecated: true image_url: type: string has_image: type: boolean public_metadata: type: object additionalProperties: true private_metadata: nullable: true type: object additionalProperties: true unsafe_metadata: type: object additionalProperties: true 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' passkeys: type: array items: $ref: '#/components/schemas/Passkey' password_enabled: type: boolean two_factor_enabled: type: boolean totp_enabled: type: boolean backup_code_enabled: type: boolean mfa_enabled_at: type: integer format: int64 description: 'Unix timestamp of when MFA was last enabled for this user. It should be noted that this field is not nullified if MFA is disabled. ' nullable: true mfa_disabled_at: type: integer format: int64 description: 'Unix timestamp of when MFA was last disabled for this user. It should be noted that this field is not nullified if MFA is enabled again. ' nullable: true password_last_updated_at: type: integer format: int64 description: 'Unix timestamp of when the user''s password was last updated. ' nullable: true external_accounts: type: array items: $ref: '#/components/schemas/ExternalAccountWithVerification' saml_accounts: type: array items: $ref: '#/components/schemas/SAMLAccount' enterprise_accounts: type: array items: $ref: '#/components/schemas/EnterpriseAccount' organization_memberships: type: array items: $ref: '#/components/schemas/OrganizationMembership' 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. ' locked: type: boolean description: 'Flag to denote whether user is currently locked, i.e. restricted from signing in or not. ' deprovisioned: type: boolean description: 'Flag to denote whether user has been deprovisioned and is restricted from signing in. ' lockout_expires_in_seconds: type: integer format: int64 nullable: true description: 'The number of seconds remaining until the lockout period expires for a locked user. A null value for a locked user indicates that lockout never expires. ' verification_attempts_remaining: type: integer format: int64 nullable: true description: 'The number of verification attempts remaining until the user is locked. Null if account lockout is not enabled. Note: if a user is locked explicitly via the Backend API, they may still have verification attempts remaining. ' updated_at: type: integer format: int64 description: 'Unix timestamp of last update. ' created_at: type: integer format: int64 description: 'Unix timestamp of creation. ' delete_self_enabled: type: boolean description: 'If enabled, user can delete themselves via FAPI. ' create_organization_enabled: type: boolean description: 'If enabled, user can create organizations via FAPI. ' create_organizations_limit: type: integer description: 'The maximum number of organizations the user can create. 0 means unlimited. ' nullable: true last_active_at: type: integer format: int64 nullable: true description: 'Unix timestamp of the latest session activity, with day precision. ' example: 1700690400000 legal_accepted_at: type: integer format: int64 nullable: true description: 'Unix timestamp of when the user accepted the legal requirements. ' example: 1700690400000 bypass_client_trust: type: boolean description: When set to `true`, the user will bypass client trust checks during sign-in. default: false scim: nullable: true allOf: - $ref: '#/components/schemas/SCIMUserMetadata' required: - id - object - username - first_name - last_name - has_image - primary_email_address_id - primary_phone_number_id - primary_web3_wallet_id - password_enabled - two_factor_enabled - totp_enabled - backup_code_enabled - email_addresses - phone_numbers - web3_wallets - passkeys - external_accounts - saml_accounts - enterprise_accounts - public_metadata - external_id - last_sign_in_at - banned - locked - lockout_expires_in_seconds - verification_attempts_remaining - created_at - updated_at - delete_self_enabled - create_organization_enabled - last_active_at - mfa_enabled_at - mfa_disabled_at - legal_accepted_at PasswordHasher: 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), [`bcrypt_sha256_django`](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/), [`md5`](https://en.wikipedia.org/wiki/MD5), `pbkdf2_sha1`, `pbkdf2_sha256`, [`pbkdf2_sha256_django`](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/), `pbkdf2_sha512`, [`phpass`](https://www.openwall.com/phpass/), `md5_phpass`, [`scrypt_firebase`](https://firebaseopensource.com/projects/firebase/scrypt/), [`scrypt_werkzeug`](https://werkzeug.palletsprojects.com/en/3.0.x/utils/#werkzeug.security.generate_password_hash), [`sha256`](https://en.wikipedia.org/wiki/SHA-2), [`ldap_ssha`](https://www.openldap.org/faq/data/cache/347.html), the [`argon2`](https://argon2.online/) variants: `argon2i` and `argon2id`, `sha512_symfony`, the SHA-512 variant of the [Symfony](https://symfony.com/doc/current/security/passwords.html) legacy hasher, and `pbkdf2_sha512_hex`, a variant of `pbkdf2_sha512` that accepts hex-encoded salt and hash. Each of the supported hashers expects the incoming digest to be in a particular format. See the [Clerk docs](https://clerk.com/docs/references/backend/user/create-user) for more information.' 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 CommerceMoneyResponse: type: object additionalProperties: false properties: amount: type: integer format: int64 description: The amount in cents. amount_formatted: type: string description: The formatted amount as a string (e.g., "$49.99"). currency: type: string description: The currency code (e.g., "USD"). currency_symbol: type: string description: The currency symbol (e.g., "$"). required: - amount - amount_formatted - currency - currency_symbol CommerceSubscriptionCreditResponse: type: object additionalProperties: false properties: amount: allOf: - $ref: '#/components/schemas/CommerceMoneyResponse' nullable: true description: Credit amount. cycle_remaining_percent: type: number format: float description: Percentage of the billing cycle remaining. CommerceProrationCreditDetailResponse: type: object additionalProperties: false properties: amount: $ref: '#/components/schemas/CommerceMoneyResponse' cycle_days_remaining: type: integer format: int64 cycle_days_total: type: integer format: int64 cycle_remaining_percent: type: number format: double required: - amount - cycle_days_remaining - cycle_days_total - cycle_remaining_percent CommercePayerCreditResponse: type: object additionalProperties: false properties: remaining_balance: $ref: '#/components/schemas/CommerceMoneyResponse' applied_amount: $ref: '#/components/schemas/CommerceMoneyResponse' required: - remaining_balance - applied_amount CommerceCreditsResponse: type: object additionalProperties: false properties: proration: allOf: - $ref: '#/components/schemas/CommerceProrationCreditDetailResponse' nullable: true payer: allOf: - $ref: '#/components/schemas/CommercePayerCreditResponse' nullable: true total: $ref: '#/components/schemas/CommerceMoneyResponse' required: - proration - payer - total FeatureResponse: type: object additionalProperties: false required: - object - id - name - description - slug - avatar_url properties: object: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - feature id: type: string description: Unique identifier for the feature. name: type: string description: The name of the feature. description: type: string nullable: true description: The description of the feature. slug: type: string description: The URL-friendly slug for the feature. avatar_url: type: string nullable: true description: The URL of the feature's avatar image. CommercePlanUnitPriceTier: type: object additionalProperties: false properties: starts_at_block: type: integer format: int64 description: Start block (inclusive) for this tier ends_after_block: type: integer format: int64 nullable: true description: End block (inclusive) for this tier; null means unlimited fee_per_block: $ref: '#/components/schemas/CommerceMoneyResponse' description: Price charged per block in this tier required: - starts_at_block - fee_per_block CommercePlanUnitPrice: type: object additionalProperties: false properties: name: type: string description: Name of the billable unit (for example, seats) block_size: type: integer format: int64 description: Number of units included in each pricing block tiers: type: array items: $ref: '#/components/schemas/CommercePlanUnitPriceTier' description: Tiered pricing configuration for this unit required: - name - block_size - tiers CommercePlan: type: object additionalProperties: false required: - object - id - name - fee - annual_monthly_fee - annual_fee - description - product_id - is_default - is_recurring - publicly_visible - has_base_fee - for_payer_type - slug - avatar_url - free_trial_enabled - free_trial_days properties: object: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - commerce_plan id: type: string description: Unique identifier for the plan. name: type: string description: The name of the plan. fee: allOf: - $ref: '#/components/schemas/CommerceMoneyResponse' nullable: true annual_monthly_fee: allOf: - $ref: '#/components/schemas/CommerceMoneyResponse' nullable: true annual_fee: allOf: - $ref: '#/components/schemas/CommerceMoneyResponse' nullable: true description: type: string description: The description of the plan. nullable: true product_id: type: string description: The ID of the product this plan belongs to. deprecated: true is_default: type: boolean description: Whether this is the default plan. is_recurring: type: boolean description: Whether this is a recurring plan. publicly_visible: type: boolean description: Whether this plan is publicly visible. has_base_fee: type: boolean description: Whether this plan has a base fee. for_payer_type: type: string description: The payer type this plan is designed for. slug: type: string description: The URL-friendly slug for the plan. avatar_url: type: string description: The URL of the plan's avatar image. nullable: true features: type: array items: $ref: '#/components/schemas/FeatureResponse' description: The features included in this plan. free_trial_enabled: type: boolean description: Whether free trial is enabled for this plan. free_trial_days: type: integer format: int64 nullable: true description: Number of free trial days for this plan. unit_prices: type: array items: $ref: '#/components/schemas/CommercePlanUnitPrice' description: Per-unit pricing tiers for this plan (for example, seats) CommercePaymentMethodResponse: type: object additionalProperties: false required: - object - id - payer_id - payment_type - gateway - gateway_external_id - gateway_external_account_id - last4 - status - card_type properties: object: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - commerce_payment_method id: type: string description: Unique identifier for the payment method. payer_id: type: string description: Unique identifier for the payer. payment_type: type: string description: The payment method type. enum: - card - link is_default: type: boolean description: Whether this is the default payment method for the payer. gateway: type: string description: The payment gateway. gateway_external_id: type: string description: External ID in the payment gateway. gateway_external_account_id: type: string nullable: true description: External account ID in the payment gateway. last4: type: string description: Last 4 digits of the card (for card payment methods). nullable: true status: type: string description: Status of the payment method. enum: - active - disconnected wallet_type: type: string description: Type of wallet (if applicable). nullable: true card_type: type: string description: Type of card (if applicable). nullable: true expiry_year: type: integer description: Card expiration year (for card payment methods). nullable: true expiry_month: type: integer description: Card expiration month (for card payment methods). nullable: true created_at: type: integer format: int64 description: Unix timestamp (in milliseconds) when the payment method was created. updated_at: type: integer format: int64 description: Unix timestamp (in milliseconds) when the payment method was last updated. is_removable: type: boolean description: Whether this payment method can be removed. CommerceSubscriptionItemNextPaymentResponse: type: object additionalProperties: false properties: amount: allOf: - $ref: '#/components/schemas/CommerceMoneyResponse' nullable: true description: Amount for the next payment. date: type: integer format: int64 nullable: true description: Unix timestamp (in milliseconds) for the next payment date. CommercePayerResponse: type: object additionalProperties: false required: - object - id - instance_id properties: object: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - commerce_payer id: type: string description: Unique identifier for the payer. instance_id: type: string description: Unique identifier for the Clerk instance. user_id: type: string description: User ID for user-type payers. nullable: true first_name: type: string description: First name of the payer. nullable: true last_name: type: string description: Last name of the payer. nullable: true email: type: string description: Email address of the payer. nullable: true organization_id: type: string description: Organization ID for org-type payers. nullable: true organization_name: type: string description: Organization name for org-type payers. nullable: true image_url: type: string description: URL of the payer's image/avatar. credits_balance: $ref: '#/components/schemas/CommerceMoneyResponse' description: Current credits balance for the payer. created_at: type: integer format: int64 description: Unix timestamp (in milliseconds) when the payer was created. updated_at: type: integer format: int64 description: Unix timestamp (in milliseconds) when the payer was last updated. CommercePerUnitTotalTier: type: object additionalProperties: false properties: quantity: type: integer format: int64 nullable: true description: Units billed in this tier; null means unlimited fee_per_block: $ref: '#/components/schemas/CommerceMoneyResponse' description: Price charged per block in this tier total: $ref: '#/components/schemas/CommerceMoneyResponse' description: Total charge for this tier required: - fee_per_block - total CommerceSubscriptionItemSeatsResponse: type: object additionalProperties: false properties: quantity: type: integer format: int64 nullable: true description: Seat quantity being billed; null means unlimited tiers: type: array items: $ref: '#/components/schemas/CommercePerUnitTotalTier' description: Per-unit cost breakdown by pricing tier required: - quantity CommercePerUnitTotal: type: object additionalProperties: false properties: name: type: string description: Name of the billable unit (for example, seats) block_size: type: integer format: int64 description: Number of units included in each pricing block tiers: type: array items: $ref: '#/components/schemas/CommercePerUnitTotalTier' description: Computed totals for each pricing tier required: - name - block_size - tiers CommerceTotalsResponse: type: object additionalProperties: false properties: subtotal: $ref: '#/components/schemas/CommerceMoneyResponse' base_fee: $ref: '#/components/schemas/CommerceMoneyResponse' tax_total: $ref: '#/components/schemas/CommerceMoneyResponse' grand_total: $ref: '#/components/schemas/CommerceMoneyResponse' per_unit_totals: type: array items: $ref: '#/components/schemas/CommercePerUnitTotal' credits: allOf: - $ref: '#/components/schemas/CommerceCreditsResponse' nullable: true required: - subtotal - base_fee - tax_total - grand_total CommerceSubscriptionItem: type: object additionalProperties: false required: - object - id - instance_id - status - plan_id - plan_period - payer_id - is_free_trial - period_start - period_end - canceled_at - past_due_at - ended_at properties: object: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - commerce_subscription_item id: type: string description: Unique identifier for the subscription item. instance_id: type: string description: Unique identifier for the Clerk instance. status: type: string description: Current status of the subscription item. enum: - active - canceled - expired - ended - past_due - upcoming - incomplete - abandoned credit: $ref: '#/components/schemas/CommerceSubscriptionCreditResponse' description: Credit information (only available in PaymentAttempt events). credits: allOf: - $ref: '#/components/schemas/CommerceCreditsResponse' nullable: true description: Unified credits breakdown for this subscription item. plan_id: type: string description: Unique identifier for the associated plan. nullable: true price_id: type: string description: Unique identifier for the associated price plan: allOf: - $ref: '#/components/schemas/CommercePlan' nullable: true description: The associated plan. plan_period: type: string description: The billing period for this subscription item. enum: - month - annual payment_method: $ref: '#/components/schemas/CommercePaymentMethodResponse' description: The payment method used for this subscription item. lifetime_paid: $ref: '#/components/schemas/CommerceMoneyResponse' description: Total amount paid over the lifetime of this subscription item. next_payment: allOf: - $ref: '#/components/schemas/CommerceSubscriptionItemNextPaymentResponse' nullable: true description: Information about the next payment. payer_id: type: string description: Unique identifier for the payer. payer: $ref: '#/components/schemas/CommercePayerResponse' description: The payer associated with this subscription item. is_free_trial: type: boolean description: Whether this subscription item includes a free trial. period_start: type: integer format: int64 description: Unix timestamp (in milliseconds) when the current period started. period_end: type: integer format: int64 nullable: true description: Unix timestamp (in milliseconds) when the current period ends. proration_date: type: string format: date description: The day the subscription item was prorated from. Only available in some responses. canceled_at: type: integer format: int64 nullable: true description: Unix timestamp (in milliseconds) when the subscription item was canceled. past_due_at: type: integer format: int64 nullable: true description: Unix timestamp (in milliseconds) when the subscription item became past due. ended_at: type: integer format: int64 nullable: true description: Unix timestamp (in milliseconds) when the subscription item ended. created_at: type: integer format: int64 description: Unix timestamp (in milliseconds) when the subscription item was created. updated_at: type: integer format: int64 description: Unix timestamp (in milliseconds) when the subscription item was last updated. seats: allOf: - $ref: '#/components/schemas/CommerceSubscriptionItemSeatsResponse' nullable: true description: Seat quantity for seat-based billing. totals: allOf: - $ref: '#/components/schemas/CommerceTotalsResponse' nullable: true description: Totals for this subscription item. CommerceSubscriptionNextPayment: type: object additionalProperties: false required: - date - amount properties: date: type: integer format: int64 description: Unix timestamp (milliseconds) of the next payment date. amount: $ref: '#/components/schemas/CommerceMoneyResponse' description: The amount of the next payment. CommerceSubscription: type: object additionalProperties: false required: - object - id - instance_id - status - payer_id - created_at - updated_at - active_at - past_due_at - subscription_items properties: object: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - commerce_subscription id: type: string description: Unique identifier for the commerce subscription. instance_id: type: string description: The ID of the instance this subscription belongs to. status: type: string description: The current status of the subscription. enum: - active - past_due - canceled - ended - abandoned - incomplete payer_id: type: string description: The ID of the payer for this subscription. created_at: type: integer format: int64 description: Unix timestamp (milliseconds) of creation. updated_at: type: integer format: int64 description: Unix timestamp (milliseconds) of last update. active_at: type: integer format: int64 nullable: true description: Unix timestamp (milliseconds) when the subscription became active. past_due_at: type: integer format: int64 nullable: true description: Unix timestamp (milliseconds) when the subscription became past due. subscription_items: type: array items: $ref: '#/components/schemas/CommerceSubscriptionItem' description: Array of subscription items in this subscription. next_payment: $ref: '#/components/schemas/CommerceSubscriptionNextPayment' description: Information about the next scheduled payment. eligible_for_free_trial: type: boolean description: Whether the payer is eligible for a free trial. CommerceCreditBalanceResponse: type: object additionalProperties: false required: - object - balance properties: object: type: string description: String representing the object's type. Always "commerce_credit_balance". balance: allOf: - $ref: '#/components/schemas/CommerceMoneyResponse' nullable: true description: The current credit balance. Null when the payer has never had credits. AdjustCreditBalanceRequest: type: object additionalProperties: false required: - amount - action - idempotency_key properties: amount: type: integer format: int64 description: The credit amount in cents. Must be greater than zero. action: type: string enum: - increase - decrease description: Whether to increase or decrease the credit balance. currency: type: string description: The currency code (e.g. "USD"). Defaults to USD if not provided. idempotency_key: type: string description: A unique key to ensure the adjustment is applied only once. Repeated requests with the same key return the original ledger entry. note: type: string description: An optional note to attach to the ledger entry. CommerceCreditLedgerResponse: type: object additionalProperties: false required: - object - id - payer_id - amount - currency - source_type - source_id - created_at properties: object: type: string description: String representing the object's type. Always "commerce_credit_ledger". id: type: string description: Unique identifier for the ledger entry. payer_id: type: string description: The ID of the payer whose balance was adjusted. amount: type: integer format: int64 description: The signed credit amount. Positive for increases, negative for decreases. currency: type: string description: The currency code of the credit adjustment. source_type: type: string description: The type of source that originated the adjustment (e.g. "grant"). source_id: type: string description: The ID of the source that originated the adjustment. note: type: string nullable: true description: An optional note attached to the ledger entry. created_at: type: string format: date-time description: Timestamp when the ledger entry was created. OAuthAccessToken: type: array items: type: object additionalProperties: false properties: object: type: string enum: - oauth_access_token external_account_id: type: string description: External account ID provider_user_id: type: string description: The unique ID of the user in the external provider's system token: type: string description: The access token expires_at: type: integer format: int64 nullable: true description: Unix timestamp of the access token expiration. provider: type: string description: The ID of the provider public_metadata: type: object additionalProperties: true 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. id_token: type: string description: The ID token retrieved from the OIDC provider. Only present for OIDC-compliant OAuth 2.0 providers when available. token_secret: type: string description: The token secret. Only present for OAuth 1.0 tokens. required: - object - external_account_id - provider_user_id - token - expires_at - provider - public_metadata - label 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 OrganizationInvitationPublicUserData: description: An organization inviter's public user data type: object additionalProperties: false nullable: true properties: user_id: type: string nullable: false first_name: type: string nullable: true last_name: type: string nullable: true image_url: type: string has_image: type: boolean identifier: type: string required: - user_id - first_name - last_name - image_url - has_image - identifier OrganizationInvitationPublicOrganizationData: type: object additionalProperties: false properties: id: type: string name: type: string slug: type: string image_url: type: string has_image: type: boolean required: - id - name - slug - has_image OrganizationInvitationWithPublicOrganizationData: description: An organization invitation with public organization data populated type: object allOf: - properties: object: type: string description: 'String representing the object''s type. Objects of the same type share the same value. ' enum: - organization_invitation id: type: string email_address: type: string role: type: string role_name: type: string organization_id: type: string inviter_id: type: string nullable: true public_inviter_data: $ref: '#/components/schemas/OrganizationInvitationPublicUserData' status: type: string public_metadata: type: object additionalProperties: true private_metadata: type: object additionalProperties: true url: type: string nullable: true expires_at: type: integer format: int64 nullable: true description: Unix timestamp of expiration. created_at: type: integer format: int64 description: Unix timestamp of creation. updated_at: type: integer format: int64 description: Unix timestamp of last update. - properties: public_organization_data: $ref: '#/components/schemas/OrganizationInvitationPublicOrganizationData' required: - object - id - email_address - role - role_name - public_metadata - url - expires_at - created_at - updated_at - inviter_id - public_inviter_data OrganizationInvitationsWithPublicOrganizationData: type: object additionalProperties: false properties: data: type: array items: $ref: '#/components/schemas/OrganizationInvitationWithPublicOrganizationData' total_count: type: integer format: int64 description: 'Total number of organization invitations ' required: - data - total_count Invitation: type: object additionalProperties: false properties: object: type: string enum: - invitation id: type: string email_address: type: string format: email public_metadata: type: object additionalProperties: true revoked: type: boolean example: false status: type: string enum: - pending - accepted - revoked - expired example: pending url: type: string expires_at: type: integer format: int64 nullable: true description: 'Unix timestamp of expiration. ' 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 - public_metadata - 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 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 - user_id - actor - status - created_at - updated_at CNameTarget: type: object additionalProperties: false properties: host: type: string value: type: string required: description: 'Denotes whether this CNAME target is required to be set in order for the domain to be considered deployed. ' type: boolean required: - host - value - required Domain: type: object properties: object: type: string enum: - domain id: type: string name: type: string is_satellite: type: boolean frontend_api_url: type: string accounts_portal_url: type: string nullable: true description: 'Null for satellite domains. ' proxy_url: type: string nullable: true development_origin: type: string cname_targets: type: array items: $ref: '#/components/schemas/CNameTarget' nullable: true required: - object - id - name - is_satellite - frontend_api_url - development_origin Domains: type: object additionalProperties: false properties: data: type: array items: $ref: '#/components/schemas/Domain' total_count: type: integer format: int64 description: 'Total number of domains ' required: - data - total_count Instance: type: object properties: object: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - instance id: type: string environment_type: type: string example: development allowed_origins: type: array nullable: true items: type: string example: - http://localhost:3000 - https://some-domain required: - object - id - environment_type - allowed_origins 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 allowlist_blocklist_disabled_on_sign_in: type: boolean block_email_subaddresses: type: boolean block_disposable_email_domains: type: boolean required: - object - allowlist - blocklist - allowlist_blocklist_disabled_on_sign_in - block_email_subaddresses - block_disposable_email_domains InstanceProtect: type: object properties: object: type: string enum: - instance_protect rules_enabled: type: boolean specter_enabled: type: boolean required: - object - rules_enabled - specter_enabled InstanceCommunication: type: object description: Per-instance SMS communication settings, including the SMS country blocklist. properties: object: type: string enum: - instance_communication blocked_country_codes: type: array description: ISO 3166-1 alpha-2 country codes that are blocked for SMS delivery on this instance. Codes that aren't recognized are silently dropped. items: type: string required: - object - blocked_country_codes OAuthApplicationSettings: type: object properties: object: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - oauth_application_settings dynamic_oauth_client_registration: type: boolean description: Whether dynamic OAuth client registration is enabled for the instance (RFC 7591). oauth_jwt_access_tokens: type: boolean description: Whether OAuth JWT access tokens are enabled for the instance (disabled indicates opaque access tokens). required: - object - dynamic_oauth_client_registration - oauth_jwt_access_tokens OrganizationSettings: 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: - organization_settings enabled: type: boolean max_allowed_memberships: type: integer max_allowed_roles: type: integer max_role_sets_allowed: type: integer max_allowed_domains: type: integer max_allowed_permissions: deprecated: true description: max_allowed_permissions is now a no-op, as permissions are now unlimited type: integer creator_role: type: string description: The role key that a user will be assigned after creating an organization. admin_delete_enabled: type: boolean description: The default for whether an admin can delete an organization with the Frontend API. domains_enabled: type: boolean slug_disabled: type: boolean domains_enrollment_modes: type: array items: type: string enum: - manual_invitation - automatic_invitation - automatic_suggestion domains_default_role: type: string description: The role key that it will be used in order to create an organization invitation or suggestion. initial_role_set_key: type: string nullable: true description: The role set key that it will be used to create new organizations. required: - object - enabled - max_allowed_memberships - max_allowed_roles - max_allowed_domains - creator_role - admin_delete_enabled - domains_enabled - domains_enrollment_modes - domains_default_role 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 - custom_signing_key - signing_algorithm - created_at - updated_at MachineWithoutScopedMachines: type: object required: - object - id - name - instance_id - created_at - updated_at properties: object: type: string enum: - machine id: type: string description: Unique identifier for the machine. name: type: string description: The name of the machine. maxLength: 255 minLength: 1 instance_id: type: string description: The ID of the instance this machine belongs to. created_at: type: integer format: int64 description: Unix timestamp of creation. updated_at: type: integer format: int64 description: Unix timestamp of last update. default_token_ttl: type: integer description: The default time-to-live (TTL) in seconds for tokens created by this machine. minimum: 1 default: 3600 Machine: allOf: - $ref: '#/components/schemas/MachineWithoutScopedMachines' - type: object required: - scoped_machines properties: scoped_machines: type: array items: $ref: '#/components/schemas/MachineWithoutScopedMachines' description: Array of machines this machine has access to. MachineScope: type: object required: - object - from_machine_id - to_machine_id - created_at properties: object: type: string enum: - machine_scope from_machine_id: type: string description: The ID of the machine that has access to the target machine. to_machine_id: type: string description: The ID of the machine that is being accessed. created_at: type: integer format: int64 description: Unix timestamp of creation. 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 has_image: type: boolean required: - image_url - has_image OrganizationInvitation: description: An organization invitation 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: - organization_invitation id: type: string email_address: type: string role: type: string role_name: type: string organization_id: type: string inviter_id: type: string nullable: true public_inviter_data: $ref: '#/components/schemas/OrganizationInvitationPublicUserData' status: type: string public_metadata: type: object additionalProperties: true private_metadata: type: object additionalProperties: true url: type: string nullable: true expires_at: type: integer format: int64 nullable: true description: Unix timestamp of expiration. 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 - role - role_name - public_metadata - url - expires_at - created_at - updated_at - inviter_id - public_inviter_data 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 Permission: type: object properties: object: type: string enum: - permission id: type: string name: type: string key: type: string description: type: string type: 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 - key - description - type - created_at - updated_at Role: type: object properties: object: type: string enum: - role id: type: string name: type: string key: type: string description: type: string nullable: true is_creator_eligible: type: boolean description: Whether this role is eligible to be an organization creator role permissions: type: array items: $ref: '#/components/schemas/Permission' created_at: type: integer format: int64 description: 'Unix timestamp of creation. ' updated_at: type: integer format: int64 description: 'Unix timestamp of last update. ' additionalProperties: false required: - object - id - name - key - description - is_creator_eligible - permissions - created_at - updated_at Roles: type: object additionalProperties: false properties: data: type: array items: $ref: '#/components/schemas/Role' total_count: type: integer format: int64 description: 'Total number of roles ' required: - data - total_count OrganizationDomainVerification: description: The verification object from an organization domain type: object properties: status: type: string description: Status of the verification. It can be `unverified` or `verified` enum: - unverified - verified strategy: type: string description: Name of the strategy used to verify the domain attempts: type: integer description: How many attempts have been made to verify the domain nullable: true expire_at: type: integer nullable: true format: int64 description: Unix timestamp of when the verification will expire required: - status - strategy - attempts - expire_at OrganizationDomain: description: An organization domain type: object properties: object: type: string description: 'String representing the object''s type. Objects of the same type share the same value. Always `organization_domain` ' enum: - organization_domain id: type: string description: Unique identifier for the organization domain organization_id: type: string description: Unique identifier for the organization name: type: string description: Name of the organization domain enrollment_mode: type: string description: Mode of enrollment for the domain enum: - manual_invitation - automatic_invitation - automatic_suggestion affiliation_email_address: type: string nullable: true description: Affiliation email address for the domain, if available. verification: type: object nullable: true allOf: - $ref: '#/components/schemas/OrganizationDomainVerification' description: Verification details for the domain total_pending_invitations: type: integer format: int32 description: Total number of pending invitations associated with this domain total_pending_suggestions: type: integer format: int32 description: Total number of pending suggestions associated with this domain public_organization_data: type: object nullable: true allOf: - $ref: '#/components/schemas/OrganizationInvitationPublicOrganizationData' description: Public organization data associated with this domain created_at: type: integer format: int64 description: Unix timestamp when the domain was created updated_at: type: integer format: int64 description: Unix timestamp of the last update to the domain required: - object - id - organization_id - name - enrollment_mode - affiliation_email_address - verification - total_pending_invitations - total_pending_suggestions - created_at - updated_at OrganizationDomains: type: object additionalProperties: false properties: data: type: array items: $ref: '#/components/schemas/OrganizationDomain' total_count: type: integer format: int64 description: 'Total number of organization domains ' required: - data - total_count ProxyCheck: type: object additionalProperties: false properties: object: type: string enum: - proxy_check id: type: string domain_id: type: string last_run_at: type: integer format: int64 nullable: true description: 'Unix timestamp of last run. ' proxy_url: type: string successful: type: boolean 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 - domain_id - last_run_at - proxy_url - successful - created_at - updated_at 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 SignUpVerification: type: object nullable: true additionalProperties: true properties: next_action: type: string enum: - needs_prepare - needs_attempt - '' supported_strategies: type: array items: type: string SignUpVerifications: type: object additionalProperties: false properties: email_address: $ref: '#/components/schemas/SignUpVerification' phone_number: $ref: '#/components/schemas/SignUpVerification' web3_wallet: $ref: '#/components/schemas/SignUpVerification' external_account: type: object nullable: true required: - email_address - phone_number - web3_wallet - external_account 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: $ref: '#/components/schemas/SignUpVerifications' 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 additionalProperties: true public_metadata: type: object additionalProperties: true 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 format: int64 description: 'Unix timestamp at which the user abandoned the sign up attempt. ' example: 1700690400000 legal_accepted_at: type: integer format: int64 nullable: true description: 'Unix timestamp at which the user accepted the legal requirements. ' example: 1700690400000 locale: type: string nullable: true description: The user locale preference for the sign-up specified as a BCP-47 language tag. example: en-US external_account: type: object deprecated: true required: - object - id - status - required_fields - optional_fields - missing_fields - unverified_fields - verifications - username - email_address - phone_number - web3_wallet - password_enabled - first_name - last_name - custom_action - external_id - created_session_id - created_user_id - abandon_at - legal_accepted_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 client_uri: type: string nullable: true client_image_url: type: string nullable: true dynamically_registered: type: boolean consent_screen_enabled: type: boolean pkce_required: type: boolean public: type: boolean scopes: type: string redirect_uris: type: array items: type: string callback_url: type: string deprecated: true description: 'Deprecated: Use redirect_uris instead. ' authorize_url: type: string token_fetch_url: type: string user_info_url: type: string discovery_url: type: string token_introspection_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 - dynamically_registered - consent_screen_enabled - pkce_required - public - client_id - client_uri - client_image_url - scopes - redirect_uris - callback_url - authorize_url - token_fetch_url - user_info_url - discovery_url - token_introspection_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 description: 'Empty if public client. ' SAMLConnectionAttributeMapping: type: object additionalProperties: false properties: user_id: type: string email_address: type: string first_name: type: string last_name: type: string required: - user_id - email_address - first_name - last_name SAMLConnection: type: object properties: object: type: string enum: - saml_connection id: type: string name: type: string domain: type: string deprecated: true domains: type: array items: type: string idp_entity_id: type: string nullable: true idp_sso_url: type: string nullable: true idp_certificate: type: string nullable: true idp_metadata_url: type: string nullable: true idp_metadata: type: string nullable: true acs_url: type: string sp_entity_id: type: string sp_metadata_url: type: string organization_id: type: string nullable: true attribute_mapping: $ref: '#/components/schemas/SAMLConnectionAttributeMapping' active: type: boolean provider: type: string user_count: type: integer sync_user_attributes: type: boolean allow_subdomains: type: boolean allow_idp_initiated: type: boolean disable_additional_identifications: type: boolean allow_organization_account_linking: type: boolean force_authn: type: boolean description: Enable or deactivate ForceAuthn enterprise_connection_id: 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 - name - idp_entity_id - idp_sso_url - idp_certificate - acs_url - sp_entity_id - sp_metadata_url - active - provider - user_count - sync_user_attributes - allow_subdomains - allow_idp_initiated - disable_additional_identifications - allow_organization_account_linking - authenticatable - force_authn - created_at - updated_at anyOf: - required: - domain - required: - domains SAMLConnections: type: object additionalProperties: false properties: data: type: array items: $ref: '#/components/schemas/SAMLConnection' total_count: type: integer format: int64 description: 'Total number of SAML Connections ' required: - data - total_count EnterpriseConnection: type: object required: - id - name - provider - active - domains - authenticatable - created_at - updated_at properties: id: type: string description: The enterprise connection ID name: type: string description: The display name of the connection provider: type: string logo_public_url: type: string nullable: true active: type: boolean description: Whether the enterprise connection is active domains: type: array items: type: string description: Domains associated with the enterprise connection organization_id: type: string description: Organization ID when the connection is linked to an organization nullable: true sync_user_attributes: type: boolean description: Controls whether to update the user's attributes on each sign-in disable_additional_identifications: type: boolean description: When true, users cannot add additional identifications when using this connection allow_organization_account_linking: type: boolean description: Whether this connection supports account linking via organization membership custom_attributes: type: array description: Custom attributes to map from the IdP to the user's profile via SSO or SCIM provisioning items: type: object additionalProperties: false required: - name - key properties: name: type: string description: Display name for the custom attribute key: type: string description: Key used to store the attribute in the user's public/private/unsafe metadata sso_path: type: string description: Path to extract the attribute value from SSO claims (SAML assertions or OIDC claims) scim_path: type: string description: GJSON path to extract the attribute value from SCIM user resources saml_connection: type: object nullable: true description: Present when the enterprise connection uses SAML properties: id: type: string description: SAML connection ID name: type: string description: SAML connection display name idp_entity_id: type: string description: IdP entity ID (optional, when connection details are loaded) nullable: true idp_sso_url: type: string description: IdP SSO URL (optional, when connection details are loaded) nullable: true idp_metadata_url: type: string description: IdP metadata URL (optional, when connection details are loaded) nullable: true acs_url: type: string description: Assertion Consumer Service URL nullable: true sp_entity_id: type: string description: Service Provider entity ID nullable: true sp_metadata_url: type: string description: Service Provider metadata URL nullable: true active: type: boolean description: Whether the SAML connection is active allow_idp_initiated: type: boolean description: Whether IdP-initiated SSO is allowed allow_subdomains: type: boolean description: Whether subdomains are allowed for domain matching force_authn: type: boolean description: Whether to force re-authentication oauth_config: type: object nullable: true description: Present when the enterprise connection uses OIDC or EASIE properties: id: type: string description: OAuth config ID name: type: string description: Custom OIDC provider display name provider_key: type: string description: OAuth provider key (e.g. oidc_custom, oidc_ghe_*, oidc_gitlab_ent_*) client_id: type: string description: OAuth client ID nullable: true discovery_url: type: string description: OIDC discovery URL nullable: true auth_url: type: string description: OAuth authorization endpoint URL (present when configured or resolved from discovery) nullable: true token_url: type: string description: OAuth token endpoint URL (present when configured or resolved from discovery) nullable: true user_info_url: type: string description: OIDC userinfo endpoint URL (present when configured or resolved from discovery) nullable: true requires_pkce: type: boolean description: Whether PKCE is required for this OAuth client logo_public_url: type: string description: Logo URL for the provider nullable: true created_at: type: integer format: int64 description: Unix timestamp in milliseconds when the config was created updated_at: type: integer format: int64 description: Unix timestamp in milliseconds when the config was last updated created_at: type: integer format: int64 description: Unix timestamp in milliseconds when the connection was created updated_at: type: integer format: int64 description: Unix timestamp in milliseconds when the connection was last updated EnterpriseConnections: type: object additionalProperties: false properties: data: type: array items: $ref: '#/components/schemas/EnterpriseConnection' total_count: type: integer format: int64 description: Total number of enterprise connections required: - data - total_count TestingToken: type: object properties: object: type: string enum: - testing_token token: type: string description: The actual token. This value is meant to be passed in the `__clerk_testing_token` query parameter with requests to the Frontend API. example: 1713877200-c_2J2MvPu9PnXcuhbPZNao0LOXqK9A7YrnBn0HmIWxy expires_at: type: integer format: int64 description: 'Unix timestamp of the token''s expiration time. ' example: 1713880800 required: - object - token - expires_at AgentTask: type: object additionalProperties: false properties: object: type: string enum: - agent_task agent_id: type: string description: 'A stable identifier for the agent, unique per agent_name within an instance. ' agent_task_id: type: string description: 'A unique identifier for this agent task. ' task_id: type: string deprecated: true description: 'A unique identifier for this agent task. Deprecated: use agent_task_id instead. ' url: type: string description: 'The URL that, when visited, creates a session for the user. Only present in the response to a create request. ' required: - object - agent_id - agent_task_id - task_id WaitlistEntry: type: object additionalProperties: false properties: object: type: string enum: - waitlist_entry id: type: string email_address: type: string format: email status: type: string enum: - pending - invited - rejected - completed example: pending is_locked: type: boolean description: 'Indicates if the waitlist entry is locked. Locked entries are being processed in a batch action and are unavailable for other actions. ' created_at: type: integer format: int64 description: 'Unix timestamp of creation. ' updated_at: type: integer format: int64 description: 'Unix timestamp of last update. ' invitation: type: object nullable: true allOf: - $ref: '#/components/schemas/Invitation' required: - object - id - email_address - status - created_at - updated_at PaginatedCommercePlanResponse: type: object additionalProperties: false required: - data - total_count properties: data: type: array items: $ref: '#/components/schemas/CommercePlan' description: Array of plans. total_count: type: integer format: int64 description: Total number of plans. BillingPriceResponse: type: object additionalProperties: false required: - object - id - plan_id - instance_id - currency - currency_symbol - amount - annual_monthly_amount - fee - annual_monthly_fee - is_default - created_at properties: object: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - commerce_price id: type: string description: Unique identifier for the price. plan_id: type: string description: Unique identifier for the associated plan. instance_id: type: string description: Unique identifier for the instance. currency: type: string description: The currency code (e.g., "USD"). currency_symbol: type: string description: The currency symbol (e.g., "$"). amount: type: integer format: int64 description: The amount in cents for the price. annual_monthly_amount: type: integer format: int64 description: The monthly amount in cents when billed annually. fee: allOf: - $ref: '#/components/schemas/CommerceMoneyResponse' nullable: true annual_monthly_fee: allOf: - $ref: '#/components/schemas/CommerceMoneyResponse' nullable: true description: type: string nullable: true description: The description of the price. is_default: type: boolean description: Whether this price is the default price for its plan. created_at: type: integer format: int64 description: Unix timestamp (milliseconds) of creation. PaginatedBillingPriceResponse: type: object additionalProperties: false required: - data - total_count properties: data: type: array items: $ref: '#/components/schemas/BillingPriceResponse' description: Array of prices. total_count: type: integer format: int64 description: Total number of prices. CreateBillingPriceRequest: type: object additionalProperties: false required: - plan_id - amount properties: plan_id: type: string description: The ID of the plan this price belongs to. currency: type: string description: The currency code (e.g., "USD"). Defaults to USD. default: USD amount: type: integer format: int64 nullable: true description: The monthly amount in cents. Must be at least $1 (100 cents) if not null. annual_monthly_amount: type: integer format: int64 nullable: true description: The monthly amount in cents when billed annually. Must be at least $1 (100 cents) if not null. description: type: string description: An optional description for this custom price. PaginatedCommerceSubscriptionItemResponse: type: object additionalProperties: false required: - data - total_count properties: data: type: array items: $ref: '#/components/schemas/CommerceSubscriptionItem' description: Array of subscription items. total_count: type: integer format: int64 description: Total number of subscription items. ExtendFreeTrialRequest: type: object additionalProperties: false required: - extend_to properties: extend_to: type: string format: date-time description: 'RFC3339 timestamp to extend the free trial to. Must be in the future and not more than 365 days from now.' example: '2026-01-08T00:00:00Z' schemas-FeatureResponse: type: object additionalProperties: false required: - object - id - name - description - slug - avatar_url properties: object: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - feature id: type: string description: Unique identifier for the feature. name: type: string description: The name of the feature. description: type: string description: The description of the feature. slug: type: string description: The URL-friendly slug for the feature. avatar_url: type: string description: The URL of the feature's avatar image. schemas-CommercePlan: type: object additionalProperties: false required: - object - id - name - fee - annual_monthly_fee - annual_fee - amount - amount_formatted - annual_monthly_amount - annual_monthly_amount_formatted - annual_amount - annual_amount_formatted - currency_symbol - currency - description - product_id - is_default - is_recurring - publicly_visible - has_base_fee - payer_type - for_payer_type - slug - avatar_url - features properties: object: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - commerce_plan id: type: string description: Unique identifier for the commerce plan. name: type: string description: The name of the commerce plan. fee: allOf: - $ref: '#/components/schemas/CommerceMoneyResponse' nullable: true annual_monthly_fee: allOf: - $ref: '#/components/schemas/CommerceMoneyResponse' nullable: true annual_fee: allOf: - $ref: '#/components/schemas/CommerceMoneyResponse' nullable: true amount: type: integer format: int64 description: The amount in cents for the plan. amount_formatted: type: string description: The formatted amount as a string (e.g., "$49.99"). annual_monthly_amount: type: integer format: int64 description: The monthly amount in cents when billed annually. annual_monthly_amount_formatted: type: string description: The formatted annual monthly amount as a string. annual_amount: type: integer format: int64 description: The total annual amount in cents. annual_amount_formatted: type: string description: The formatted annual amount as a string. currency_symbol: type: string description: The currency symbol (e.g., "$"). currency: type: string description: The currency code (e.g., "USD"). description: type: string description: The description of the commerce plan. product_id: type: string description: The ID of the product this plan belongs to. is_default: type: boolean description: Whether this is the default plan. is_recurring: type: boolean description: Whether this is a recurring plan. publicly_visible: type: boolean description: Whether this plan is publicly visible. has_base_fee: type: boolean description: Whether this plan has a base fee. payer_type: type: array items: type: string description: The types of payers that can use this plan. for_payer_type: type: string description: The payer type this plan is designed for. slug: type: string description: The URL-friendly slug for the plan. avatar_url: type: string description: The URL of the plan's avatar image. period: type: string description: The billing period for the plan. interval: type: integer format: int64 description: The billing interval. features: type: array items: $ref: '#/components/schemas/schemas-FeatureResponse' description: The features included in this plan. free_trial_enabled: type: boolean description: Whether free trial is enabled for this plan. free_trial_days: type: integer format: int64 nullable: true description: Number of free trial days for this plan. CommercePaymentSourceResponse: type: object additionalProperties: false required: - object - id - payer_id - payment_method - gateway - gateway_external_id - last4 - status - wallet_type - card_type - created_at - updated_at properties: object: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - commerce_source id: type: string description: Unique identifier for the payment source. payer_id: type: string description: Unique identifier for the payer. payment_method: type: string description: The payment method type. enum: - card - apple_pay - google_pay is_default: type: boolean nullable: true description: Whether this is the default payment source for the payer. gateway: type: string description: The payment gateway. gateway_external_id: type: string description: External ID in the payment gateway. gateway_external_account_id: type: string nullable: true description: External account ID in the payment gateway. last4: type: string description: Last 4 digits of the card (for card payment sources). status: type: string description: Status of the payment source. enum: - active - disconnected wallet_type: type: string description: Type of wallet (if applicable). card_type: type: string description: Type of card (if applicable). expiry_year: type: integer description: Card expiration year (for card payment sources). expiry_month: type: integer description: Card expiration month (for card payment sources). created_at: type: integer format: int64 description: Unix timestamp (in milliseconds) when the payment source was created. updated_at: type: integer format: int64 description: Unix timestamp (in milliseconds) when the payment source was last updated. is_removable: type: boolean nullable: true description: Whether this payment source can be removed. schemas-CommercePayerResponse: type: object additionalProperties: false required: - object - id - instance_id - first_name - last_name - email - image_url - created_at - updated_at properties: object: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - commerce_payer id: type: string description: Unique identifier for the payer. instance_id: type: string description: Unique identifier for the Clerk instance. user_id: type: string description: User ID for user-type payers. first_name: type: string description: First name of the payer. last_name: type: string description: Last name of the payer. email: type: string description: Email address of the payer. organization_id: type: string description: Organization ID for org-type payers. organization_name: type: string description: Organization name for org-type payers. image_url: type: string description: URL of the payer's image/avatar. credits_balance: $ref: '#/components/schemas/CommerceMoneyResponse' description: Current credits balance for the payer. created_at: type: integer format: int64 description: Unix timestamp (in milliseconds) when the payer was created. updated_at: type: integer format: int64 description: Unix timestamp (in milliseconds) when the payer was last updated. schemas-CommerceSubscriptionItem: type: object additionalProperties: false required: - object - id - instance_id - status - plan_id - plan - plan_period - payment_source_id - payer_id - is_free_trial - proration_date - created_at - updated_at properties: object: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - commerce_subscription_item id: type: string description: Unique identifier for the subscription item. instance_id: type: string description: Unique identifier for the Clerk instance. status: type: string description: Current status of the subscription item. enum: - active - ended - past_due - upcoming - incomplete - abandoned credit: allOf: - $ref: '#/components/schemas/CommerceSubscriptionCreditResponse' nullable: true description: Credit information (only available in PaymentAttempt events). plan_id: type: string description: Unique identifier for the associated plan. price_id: type: string description: Unique identifier for the associated price plan: allOf: - $ref: '#/components/schemas/schemas-CommercePlan' nullable: true description: The associated commerce plan. plan_period: type: string description: The billing period for this subscription. enum: - month - annual payment_source_id: type: string description: Unique identifier for the payment source. payment_source: allOf: - $ref: '#/components/schemas/CommercePaymentSourceResponse' nullable: true description: The payment source associated with this subscription. lifetime_paid: allOf: - $ref: '#/components/schemas/CommerceMoneyResponse' nullable: true description: Total amount paid over the lifetime of this subscription. amount: allOf: - $ref: '#/components/schemas/CommerceMoneyResponse' nullable: true description: Current amount for this subscription. next_invoice: allOf: - $ref: '#/components/schemas/CommerceSubscriptionItemNextPaymentResponse' nullable: true description: Information about the next invoice. next_payment: allOf: - $ref: '#/components/schemas/CommerceSubscriptionItemNextPaymentResponse' nullable: true description: Information about the next payment. payer_id: type: string description: Unique identifier for the payer. payer: allOf: - $ref: '#/components/schemas/schemas-CommercePayerResponse' nullable: true description: The payer associated with this subscription. is_free_trial: type: boolean description: Whether this subscription is currently on a free trial. period_start: type: integer format: int64 nullable: true description: Unix timestamp (in milliseconds) when the current period started. period_end: type: integer format: int64 nullable: true description: Unix timestamp (in milliseconds) when the current period ends. proration_date: type: string description: Date used for proration calculations. canceled_at: type: integer format: int64 nullable: true description: Unix timestamp (in milliseconds) when the subscription was canceled. past_due_at: type: integer format: int64 nullable: true description: Unix timestamp (in milliseconds) when the subscription became past due. ended_at: type: integer format: int64 nullable: true description: Unix timestamp (in milliseconds) when the subscription ended. created_at: type: integer format: int64 description: Unix timestamp (in milliseconds) when the subscription was created. updated_at: type: integer format: int64 description: Unix timestamp (in milliseconds) when the subscription was last updated. PriceTransitionRequest: type: object additionalProperties: false required: - from_price_id - to_price_id properties: from_price_id: type: string description: The current price ID of the subscription item. to_price_id: type: string description: The target price ID to transition to. CommercePriceTransitionDetails: type: object additionalProperties: false required: - previous_plan - previous_price - effective_at - effective_mode - charged_immediately - previous_subscription_item_status - previous_subscription_item_id properties: previous_plan: $ref: '#/components/schemas/schemas-CommercePlan' previous_price: $ref: '#/components/schemas/BillingPriceResponse' effective_at: type: integer format: int64 description: Unix timestamp (milliseconds) when the new price takes effect. effective_mode: type: string description: When the new price takes effect. enum: - immediate - end_of_period next_billing_date: type: integer format: int64 nullable: true description: Unix timestamp (milliseconds) for the next billing date. charged_immediately: type: boolean description: Whether an immediate charge was made. immediate_charge: allOf: - $ref: '#/components/schemas/CommerceMoneyResponse' nullable: true description: Amount charged immediately, if any. previous_subscription_item_status: type: string description: The status of the previous subscription item after transition. enum: - canceled - ended - abandoned previous_subscription_item_id: type: string description: The ID of the previous subscription item. CommercePriceTransitionResponse: type: object additionalProperties: false required: - object - subscription_item - transition properties: object: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - commerce_price_transition subscription_item: $ref: '#/components/schemas/schemas-CommerceSubscriptionItem' transition: $ref: '#/components/schemas/CommercePriceTransitionDetails' BillingPaymentAttempt: type: object additionalProperties: false required: - object - id - payment_id - instance_id - charge_type - payee_id - payee - payer_id - payer - amount - payment_method_id - payment_method - statement_id - gateway_external_id - gateway_external_url - status - paid_at - failed_at - created_at - updated_at properties: object: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - commerce_payment id: type: string description: Unique identifier for the payment attempt. payment_id: type: string description: Unique identifier for the associated payment. instance_id: type: string description: The ID of the instance this payment attempt belongs to. charge_type: type: string description: Type of charge for this payment attempt. payee_id: type: string description: Unique identifier for the payee. payee: type: object description: The payee associated with this payment attempt. payer_id: type: string description: Unique identifier for the payer. payer: $ref: '#/components/schemas/CommercePayerResponse' description: The payer associated with this payment attempt. subscription_item_id: type: string description: Unique identifier for the associated subscription item. subscription_item: type: object description: The subscription item associated with this payment attempt. amount: $ref: '#/components/schemas/CommerceMoneyResponse' description: The amount for this payment attempt. totals: allOf: - $ref: '#/components/schemas/CommerceTotalsResponse' nullable: true description: Totals breakdown for this payment attempt. payment_method_id: type: string description: Unique identifier for the payment method. payment_method: $ref: '#/components/schemas/CommercePaymentMethodResponse' description: The payment method used for this payment attempt. statement_id: type: string description: Unique identifier for the associated statement. gateway_external_id: type: string description: External identifier from the payment gateway. nullable: true gateway_external_url: type: string nullable: true description: External URL from the payment gateway. status: type: string description: The current status of the payment attempt. enum: - pending - paid - failed paid_at: type: integer format: int64 nullable: true description: Unix timestamp (in milliseconds) when the payment was completed. failed_at: type: integer format: int64 nullable: true description: Unix timestamp (in milliseconds) when the payment failed to be processed. created_at: type: integer format: int64 description: Unix timestamp (in milliseconds) when the payment attempt was created. updated_at: type: integer format: int64 description: Unix timestamp (in milliseconds) when the payment attempt was last updated. BillingStatement: type: object additionalProperties: false required: - object - id - instance_id - timestamp - payer - status - totals - groups properties: object: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - commerce_statement id: type: string description: Unique identifier for the billing statement. instance_id: type: string description: The ID of the instance this statement belongs to. timestamp: type: integer format: int64 description: Unix timestamp (in milliseconds) when the statement was created. payer: $ref: '#/components/schemas/CommercePayerResponse' description: The payer associated with this statement. status: type: string description: The current status of the statement. enum: - open - closed totals: type: object description: Totals for the statement. required: - grand_total - subtotal - base_fee - tax_total properties: grand_total: $ref: '#/components/schemas/CommerceMoneyResponse' description: The grand total amount for the statement. subtotal: $ref: '#/components/schemas/CommerceMoneyResponse' description: The subtotal amount for the statement (base fee + unit price totals). base_fee: $ref: '#/components/schemas/CommerceMoneyResponse' description: The base plan fee before unit pricing. tax_total: $ref: '#/components/schemas/CommerceMoneyResponse' description: The tax total amount for the statement. groups: type: array description: Array of statement groups. items: type: object description: A statement group. required: - object - timestamp - items properties: object: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - commerce_statement_group timestamp: type: integer format: int64 description: Unix timestamp (in milliseconds) of the date the group's payment attempts were created items: type: array items: $ref: '#/components/schemas/BillingPaymentAttempt' description: The payment attempts included in the group PaginatedBillingStatementResponse: type: object additionalProperties: false required: - data - total_count properties: data: type: array items: $ref: '#/components/schemas/BillingStatement' description: Array of billing statements. total_count: type: integer format: int64 description: Total number of billing statements. PaginatedBillingPaymentAttemptResponse: type: object additionalProperties: false required: - data - total_count properties: data: type: array items: $ref: '#/components/schemas/BillingPaymentAttempt' description: Array of billing payment attempts. total_count: type: integer format: int64 description: Total number of billing payment attempts. Permissions: type: object additionalProperties: false properties: data: type: array items: $ref: '#/components/schemas/Permission' total_count: type: integer format: int64 description: 'Total number of permissions ' required: - data - total_count RoleSetItem: type: object description: A role within a role set properties: object: type: string enum: - role_set_item id: type: string description: The unique identifier of the role name: type: string description: The name of the role key: type: string description: The key of the role (e.g., "org:admin", "org:member") description: type: string nullable: true description: Optional description of the role members_count: type: integer format: int64 nullable: true description: The number of members assigned to this role within the role set has_members: type: boolean nullable: true description: Whether this role has any members assigned within the role set created_at: type: integer format: int64 description: Unix timestamp of role creation updated_at: type: integer format: int64 description: Unix timestamp of last role update additionalProperties: false required: - object - id - name - key - description - created_at - updated_at RoleSetMigration: type: object description: Information about an ongoing role set migration properties: object: type: string enum: - role_set_migration id: type: string description: The unique identifier of the migration organization_id: type: string nullable: true description: The organization ID if the migration is scoped to a specific organization instance_id: type: string description: The instance ID this migration belongs to source_role_set_id: type: string description: The ID of the source role set being migrated from dest_role_set_id: type: string nullable: true description: The ID of the destination role set being migrated to trigger_type: type: string description: What triggered this migration (e.g., "role_set_deletion", "role_removal") status: type: string description: Current status of the migration (e.g., "enqueued", "in_progress", "completed") migrated_members: type: integer description: Number of members that have been migrated so far mappings: type: object nullable: true description: Role key mappings from source to destination roles additionalProperties: type: string started_at: type: integer format: int64 nullable: true description: Unix timestamp when the migration started completed_at: type: integer format: int64 nullable: true description: Unix timestamp when the migration completed created_at: type: integer format: int64 description: Unix timestamp of migration creation updated_at: type: integer format: int64 description: Unix timestamp of last migration update additionalProperties: false required: - object - id - instance_id - source_role_set_id - trigger_type - status - migrated_members - created_at - updated_at RoleSet: type: object description: A role set defines a collection of roles that can be assigned to organization members properties: object: type: string enum: - role_set id: type: string description: The unique identifier of the role set name: type: string description: The name of the role set key: type: string description: A unique key for the role set (e.g., "role_set:default") description: type: string nullable: true description: Optional description of the role set roles: type: array items: $ref: '#/components/schemas/RoleSetItem' description: The list of roles in this role set default_role: allOf: - $ref: '#/components/schemas/RoleSetItem' nullable: true description: The default role assigned to new organization members creator_role: allOf: - $ref: '#/components/schemas/RoleSetItem' nullable: true description: The role assigned to the creator of an organization type: type: string description: The type of the role set ("initial" or "custom") enum: - initial - custom role_set_migration: description: Active migration information, only present when status is "enqueued" or "in_progress" nullable: true allOf: - $ref: '#/components/schemas/RoleSetMigration' created_at: type: integer format: int64 description: Unix timestamp of role set creation updated_at: type: integer format: int64 description: Unix timestamp of last role set update additionalProperties: false required: - object - id - name - key - description - roles - type - created_at - updated_at RoleSets: type: object additionalProperties: false properties: data: type: array items: $ref: '#/components/schemas/RoleSet' total_count: type: integer format: int64 description: Total number of role sets required: - data - total_count ReassignmentMappings: type: object description: Mappings from source role keys to destination role keys for role reassignment additionalProperties: type: string responses: WellKnown.JWKS: description: Get the JSON Web Key Set content: application/json: schema: $ref: '#/components/schemas/JWKS' 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' DeprecatedEndpoint: description: The endpoint is considered deprecated and is pending removal. 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' EmailAddress: description: Success content: application/json: schema: $ref: '#/components/schemas/EmailAddress' AuthorizationInvalid: description: Authorization invalid content: application/json: schema: $ref: '#/components/schemas/ClerkErrors' Conflict: description: Conflict 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' Session: description: Success content: application/json: schema: $ref: '#/components/schemas/Session' Session.Refresh: description: Success content: application/json: schema: $ref: '#/components/schemas/SessionRefresh' 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' CommerceSubscription: description: A commerce subscription. content: application/json: schema: $ref: '#/components/schemas/CommerceSubscription' CommerceCreditBalance: description: A payer's credit balance. content: application/json: schema: $ref: '#/components/schemas/CommerceCreditBalanceResponse' CommerceCreditLedger: description: A credit ledger entry. content: application/json: schema: $ref: '#/components/schemas/CommerceCreditLedgerResponse' OAuthAccessToken: description: Success content: application/json: schema: $ref: '#/components/schemas/OAuthAccessToken' OrganizationMemberships: description: A list of organization memberships content: application/json: schema: $ref: '#/components/schemas/OrganizationMemberships' OrganizationInvitationsWithPublicOrganizationData: description: A list of organization invitations with public organization data content: application/json: schema: $ref: '#/components/schemas/OrganizationInvitationsWithPublicOrganizationData' 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' Invitation.Revoked: description: Success content: application/json: schema: allOf: - $ref: '#/components/schemas/Invitation' - type: object properties: revoked: type: boolean enum: - true example: true status: type: string enum: - revoked example: revoked 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' Domains: description: A list of domains content: application/json: schema: $ref: '#/components/schemas/Domains' Domain: description: A domain content: application/json: schema: $ref: '#/components/schemas/Domain' Instance: description: Success content: application/json: schema: $ref: '#/components/schemas/Instance' InstanceRestrictions: description: Success content: application/json: schema: $ref: '#/components/schemas/InstanceRestrictions' InstanceProtect: description: Success content: application/json: schema: $ref: '#/components/schemas/InstanceProtect' InstanceCommunication: description: Success content: application/json: schema: $ref: '#/components/schemas/InstanceCommunication' InstanceOAuthApplicationSettings: description: Success content: application/json: schema: $ref: '#/components/schemas/OAuthApplicationSettings' 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' Machine.List: description: Success content: application/json: schema: type: object required: - data - total_count properties: data: type: array items: $ref: '#/components/schemas/Machine' total_count: type: integer description: Total number of machines Machine.Created: description: Success content: application/json: schema: allOf: - $ref: '#/components/schemas/Machine' - type: object required: - secret_key properties: secret_key: type: string readOnly: true description: The secret key for the machine, only returned upon creation. Machine: description: Success content: application/json: schema: $ref: '#/components/schemas/Machine' Machine.Deleted: description: Success content: application/json: schema: type: object required: - object - id - deleted properties: object: type: string enum: - machine description: String representing the object's type. id: type: string description: The ID of the deleted machine deleted: type: boolean enum: - true description: Whether the machine was successfully deleted Machine.SecretKey: description: Success content: application/json: schema: type: object required: - object - secret properties: object: type: string enum: - machine_secret_key description: String representing the object's type. secret: type: string readOnly: true description: The secret key for the machine. MachineScope: description: Machine scope created successfully for a machine content: application/json: schema: $ref: '#/components/schemas/MachineScope' MachineScope.Deleted: description: Machine scope deleted successfully for a machine content: application/json: schema: type: object required: - object - from_machine_id - to_machine_id - deleted properties: object: type: string enum: - machine_scope description: String representing the object's type. from_machine_id: type: string description: The ID of the machine that had access to the target machine to_machine_id: type: string description: The ID of the machine that was being accessed deleted: type: boolean enum: - true description: Whether the machine scope was successfully deleted 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' OrganizationInvitations: description: A list of organization invitations content: application/json: schema: $ref: '#/components/schemas/OrganizationInvitations' OrganizationInvitation: description: An organization invitation content: application/json: schema: $ref: '#/components/schemas/OrganizationInvitation' Roles: description: Success content: application/json: schema: $ref: '#/components/schemas/Roles' Role: description: Success content: application/json: schema: $ref: '#/components/schemas/Role' OrganizationMembership: description: Success content: application/json: schema: $ref: '#/components/schemas/OrganizationMembership' OrganizationDomains: description: A list of organization domains content: application/json: schema: $ref: '#/components/schemas/OrganizationDomains' OrganizationDomain: description: An organization domain content: application/json: schema: $ref: '#/components/schemas/OrganizationDomain' ProxyCheck: description: Health check information about a domain's proxy configuration validation attempt. content: application/json: schema: $ref: '#/components/schemas/ProxyCheck' 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' SAMLConnections: description: A list of SAML Connections content: application/json: schema: $ref: '#/components/schemas/SAMLConnections' SAMLConnection: description: A SAML Connection content: application/json: schema: $ref: '#/components/schemas/SAMLConnection' EnterpriseConnections: description: A list of enterprise connections content: application/json: schema: $ref: '#/components/schemas/EnterpriseConnections' EnterpriseConnection: description: An enterprise connection content: application/json: schema: $ref: '#/components/schemas/EnterpriseConnection' TestingToken: description: A Testing Token content: application/json: schema: $ref: '#/components/schemas/TestingToken' AgentTask: description: Success content: application/json: schema: $ref: '#/components/schemas/AgentTask' WaitlistEntries: description: List of waitlist entries content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/WaitlistEntry' total_count: type: integer description: Total number of waitlist entries required: - data - total_count WaitlistEntry: description: A Waitlist Entry content: application/json: schema: $ref: '#/components/schemas/WaitlistEntry' WaitlistEntry.List: description: Array of waitlist entries content: application/json: schema: type: array items: $ref: '#/components/schemas/WaitlistEntry' CommercePlan.List: description: A list of commerce plans. content: application/json: schema: $ref: '#/components/schemas/PaginatedCommercePlanResponse' BillingPrice.List: description: A list of billing prices. content: application/json: schema: $ref: '#/components/schemas/PaginatedBillingPriceResponse' BillingPrice: description: A billing price. content: application/json: schema: $ref: '#/components/schemas/BillingPriceResponse' CommerceSubscriptionItem.List: description: A list of commerce subscription items. content: application/json: schema: $ref: '#/components/schemas/PaginatedCommerceSubscriptionItemResponse' CommerceSubscriptionItem: description: A commerce subscription item. content: application/json: schema: $ref: '#/components/schemas/CommerceSubscriptionItem' responses-CommerceSubscriptionItem: description: A commerce subscription item. content: application/json: schema: $ref: '#/components/schemas/schemas-CommerceSubscriptionItem' CommercePriceTransition: description: A commerce price transition. content: application/json: schema: $ref: '#/components/schemas/CommercePriceTransitionResponse' BillingStatement.List: description: A list of billing statements. content: application/json: schema: $ref: '#/components/schemas/PaginatedBillingStatementResponse' BillingStatement: description: A billing statement. content: application/json: schema: $ref: '#/components/schemas/BillingStatement' BillingPaymentAttempt.List: description: A list of billing payment attempts. content: application/json: schema: $ref: '#/components/schemas/PaginatedBillingPaymentAttemptResponse' Permissions: description: Success content: application/json: schema: $ref: '#/components/schemas/Permissions' Permission: description: Success content: application/json: schema: $ref: '#/components/schemas/Permission' RoleSets: description: Success content: application/json: schema: $ref: '#/components/schemas/RoleSets' RoleSet: description: Success content: application/json: schema: $ref: '#/components/schemas/RoleSet' parameters: Paginated: name: paginated in: query description: 'Whether to paginate the results. If true, the results will be paginated. If false, the results will not be paginated.' required: false schema: type: boolean 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`.' required: false schema: type: integer 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: integer default: 0 minimum: 0 x-speakeasy-retries: strategy: backoff backoff: initialInterval: 500 maxInterval: 60000 maxElapsedTime: 3600000 exponent: 1.5 statusCodes: - 5XX retryConnectionErrors: true