openapi: 3.0.3 info: title: Clerk Frontend API version: v1 description: 'The Clerk REST Frontend API, meant to be accessed from a browser or native environment. This is a Form Based API and all the data must be sent and formatted according to the `application/x-www-form-urlencoded` content type. ### 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. `2021-02-05`. For more information, please see [Clerk API Versions](https://clerk.com/docs/backend-requests/versioning/overview). ### Using the Try It Console The `Try It` feature of the docs only works for **Development Instances** when using the `DevBrowser` security scheme. To use it, first generate a dev instance token from the `/v1/dev_browser` endpoint. Please see https://clerk.com/docs for more information.' 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 Team url: https://clerk.com/support termsOfService: https://clerk.com/terms license: name: MIT url: https://github.com/clerk/javascript/blob/main/LICENSE servers: - url: https://{domain}.clerk.accounts.dev variables: domain: default: example-destined-camel-13 description: Your Development Instance Frontend API Domain. security: - {} - DevBrowser: [] - ProductionBrowser: [] - ProductionNativeApp: [] ProductionNativeFlag: [] tags: - name: DevBrowser description: Used to handle dev browsers. - name: DevTools description: Used to configure development instance settings. - name: Well Known description: Well-known endpoints like JWKS, deep linking, and openid-configuration. - name: Health description: Used to get the health status of the API. - name: OAuth2 Identity Provider description: Requests for the OAuth2 authorization flow. - name: OAuth2 Callbacks description: Used to receive callbacks from successful OAuth attempts. - name: SAML description: Used in authentication flows using SAML. - name: Client description: Used to interact with the Client Object. - name: Sessions description: Used to interact with the sessions of a client. - name: Sign Ins description: Used to sign in a user in the current client. - name: Sign Ups description: Used to sign up a new user in the current client. - name: User description: Used to interact with the properties of the current user. - name: Active Sessions description: Used to interact with the sessions of the current user. - name: Email Addresses description: Used to interact with the email addresses of the logged in user. - name: Phone Numbers description: Used to interact with the phone numbers of the logged in user. - name: Web3 Wallets description: Used to interact with the web3 wallets of the logged in user. - name: Passkeys description: Used to interact with the passkeys of the logged in user. - name: External Accounts description: Used to interact with the external accounts of the current user. - name: TOTP description: Used to interact with One Time Password authenticators of the current user. - name: Backup Codes description: Used to interact with the two factor authentication backup codes of the current user. - name: Organizations Memberships description: Used to interact with the current user's organization memberships, invitations and suggestions. - name: Organization description: Used to interact with an organization and its properties. The current user must be an administrator to access them. - name: Organization Creation Defaults description: Used to get suggested defaults when creating a new organization. - name: Invitations description: Used to interact with the invitations of an organization. The current user must be an administrator to access them. - name: Members description: Used to interact with the members of an organization. The current user must be an administrator to access them. - name: Membership Requests description: Used to interact with the members of an organization. The current user must be an administrator to access them. - name: Domains description: Used to interact with the members of an organization. The current user must be an administrator to access them. - name: Environment description: Used to get and update the current Environment - name: Waitlist description: Used to interact with the waitlist. - name: API Keys description: Endpoints for managing API Keys - name: Enterprise Connections description: Endpoints for managing enterprise connections. - name: Plans description: Used to interact with plans that users and organizations can purchase. - name: Subscriptions description: Used to interact with subscriptions belonging to users and organizations. - name: Subscription Items description: Used to interact with subscription items belonging to users and organizations. - name: Checkouts description: Used to interact with the checkout flow. - name: Payment Methods description: Used to interact with payment methods belonging to users and organizations. - name: Statements description: Used to interact with billing statements for users and organizations. - name: Payment Attempts description: Used to interact with payment attempts for users and organizations. paths: /.well-known/assetlinks.json: get: summary: Get Android Asset Links description: Get Android asset links for universal/deep linking operationId: getAndroidAssetLinks security: [] tags: - Well Known responses: '200': $ref: '#/components/responses/WellKnown.Assetlinks' /.well-known/jwks.json: get: summary: JWKS description: Retrieve the JSON Web Key Set of the instance operationId: getJWKS security: [] tags: - Well Known responses: '200': $ref: '#/components/responses/WellKnown.JWKS' '500': $ref: '#/components/responses/ClerkErrors' /.well-known/apple-app-site-association: get: summary: Apple App Site Association description: Retrieve the Apple App Site Association file of the instance operationId: getAppleAppSiteAssociation security: [] tags: - Well Known responses: '200': $ref: '#/components/responses/WellKnown.AppleAppSiteAssociation' '500': $ref: '#/components/responses/ClerkErrors' /.well-known/openid-configuration: get: summary: Basic OpenID Configuration Payload description: Get a basic OpenID configuration payload operationId: getOpenIDConfiguration security: [] tags: - Well Known responses: '200': $ref: '#/components/responses/WellKnown.OpenIDConfiguration' /.well-known/oauth-authorization-server: get: summary: OAuth 2.0 Authorization Server Metadata description: Get the OAuth 2.0 Authorization Server Metadata according to RFC 8414 operationId: getOAuth2AuthorizationServerMetadata security: [] tags: - Well Known responses: '200': $ref: '#/components/responses/WellKnown.OAuth2AuthorizationServerMetadata' /oauth/authorize: get: summary: Request OAuth2 Authorization description: Request OAuth2 authorization. If successful, receive authorization grant via redirect. operationId: requestOAuthAuthorize security: [] tags: - OAuth2 Identity Provider parameters: - name: response_type in: query required: true description: The authorization flow type. Must be `code` for authorization code flow. schema: type: string enum: - code - name: client_id in: query required: true description: The OAuth2 client ID of the OAuth application. schema: type: string - name: redirect_uri in: query required: false description: The URI to redirect to after authorization. Must be registered for the OAuth application. schema: type: string format: uri - name: scope in: query required: false style: spaceDelimited explode: false description: Space-separated list of scopes being requested. Available scopes are `email`, `profile`, `openid`, `public_metadata`, and `private_metadata`. Defaults to `profile email` if not provided. schema: type: array items: type: string enum: - email - profile - openid - offline_access - public_metadata - private_metadata - name: state in: query required: false description: An opaque value used to maintain state between the request and callback (minimum 8 characters). Required to prevent CSRF attacks unless PKCE parameters (`code_challenge` and `code_challenge_method`) are provided. schema: type: string minLength: 8 - name: prompt in: query required: false style: spaceDelimited explode: false description: Space-separated list of prompts. Supported values are `none` (no user interaction), `login` (force re-authentication), and `consent` (force consent screen). schema: type: array items: type: string enum: - none - login - consent - name: code_challenge in: query required: false description: The code challenge for PKCE (Proof Key for Code Exchange). Required for public clients. schema: type: string - name: code_challenge_method in: query required: false description: The method used to generate the code challenge. Must be `S256`. schema: type: string enum: - S256 - name: response_mode in: query required: false description: The method used to return authorization response parameters. Supported values are `query` (parameters in URL query string) and `form_post` (parameters in POST body). schema: type: string enum: - query - form_post - name: nonce in: query required: false description: String value used to associate a client session with an ID Token and to mitigate replay attacks. Used in OpenID Connect flows. schema: type: string responses: '200': description: Success for 'form_post' response mode '302': description: Redirect, no body. '303': description: Redirect, no body. '400': description: Bad request error, for example a request parameter is invalid. '401': description: Unauthorized error, for example the provided client is invalid. '403': description: Forbidden error, for example you are trying to use a satellite domain post: summary: Request OAuth2 Authorization description: Request OAuth2 authorization. If successful, receive authorization grant via redirect. operationId: requestOAuthAuthorizePOST security: [] tags: - OAuth2 Identity Provider requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: response_type: type: string description: The authorization flow type. Must be `code` for authorization code flow. enum: - code client_id: type: string description: The OAuth2 client ID of the OAuth application. redirect_uri: type: string format: uri nullable: true description: The URI to redirect to after authorization. Must be registered for the OAuth application. scope: type: string nullable: true description: Space-separated list of scopes being requested. Available scopes are `email`, `profile`, `openid`, `public_metadata`, and `private_metadata`. Defaults to `profile email` if not provided. Multiple values should be space-delimited (e.g., "email profile openid"). state: type: string nullable: true description: An opaque value used to maintain state between the request and callback (minimum 8 characters). Required to prevent CSRF attacks unless PKCE parameters (`code_challenge` and `code_challenge_method`) are provided. minLength: 8 prompt: type: string nullable: true description: Space-separated list of prompts. Supported values are `none` (no user interaction), `login` (force re-authentication), and `consent` (force consent screen). Multiple values should be space-delimited (e.g., "login consent"). code_challenge: type: string nullable: true description: The code challenge for PKCE (Proof Key for Code Exchange). Required for public clients. code_challenge_method: type: string nullable: true description: The method used to generate the code challenge. Must be `S256`. enum: - S256 response_mode: type: string nullable: true description: The method used to return authorization response parameters. Supported values are `query` (parameters in URL query string) and `form_post` (parameters in POST body). enum: - query - form_post nonce: type: string nullable: true description: String value used to associate a client session with an ID Token and to mitigate replay attacks. Used in OpenID Connect flows. required: - response_type - client_id responses: '200': description: Success for 'form_post' response mode '302': description: Redirect, no body. '303': description: Redirect, no body. '400': description: Bad request error, for example a request parameter is invalid. '401': description: Unauthorized error, for example the provided client is invalid. '403': description: Forbidden error, for example you are trying to use a satellite domain /oauth/internal-consent: {} /oauth/register: post: summary: Register OAuth 2.0 Client description: "Registers a new OAuth 2.0 client with the authorization server according to RFC 7591\n(OAuth 2.0 Dynamic Client Registration Protocol).\n\nThis endpoint allows clients to dynamically register by submitting client metadata.\nUpon successful registration, the authorization server assigns a unique client identifier\nand optionally a client secret (for confidential clients).\n\n**Authentication:** This endpoint does not require authentication as it is used for\ninitial client registration. However, the endpoint is disabled by default and must\nbe enabled in the Instance settings.\n\n**Client Types:**\n- **Confidential clients** receive both a `client_id` and `client_secret`\n- **Public clients** (using `token_endpoint_auth_method: none`) receive only a `client_id`\n\n**Key Points:**\n- All dynamically registered clients must use the consent screen (cannot be disabled)\n- PKCE is not required for dynamically registered clients\n- The `redirect_uris` field is required and must\ \ contain at least one valid redirect URI\n- If `client_name` is not provided, the `client_id` will be used as the display name\n- If `scope` is not provided, default scopes will be assigned\n- The `token_endpoint_auth_method` values `client_secret_basic` and `client_secret_post` are\n treated equivalently in the current implementation; both methods can be used at the\n token endpoint\n\nSee [RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591) for complete specification details." operationId: registerOAuthClient security: [] tags: - OAuth2 Identity Provider requestBody: description: 'Client metadata as defined in RFC 7591 Section 2. The client metadata includes information about the client such as its name, redirect URIs, and authentication method.' required: true content: application/json: schema: $ref: '#/components/schemas/OAuth.DynamicClientRegistrationRequest' examples: confidentialClient: summary: Confidential Client Registration description: Register a confidential client that will authenticate with client_secret_basic value: client_name: My Confidential App client_uri: https://example.com logo_uri: https://example.com/logo.png redirect_uris: - https://example.com/oauth/callback token_endpoint_auth_method: client_secret_basic scope: openid email profile publicClient: summary: Public Client Registration description: Register a public client (no client secret) value: client_name: My Mobile App client_uri: https://example.com redirect_uris: - myapp://oauth/callback token_endpoint_auth_method: none scope: openid email profile minimalClient: summary: Minimal Client Registration description: Register a client with only required fields value: redirect_uris: - https://example.com/callback responses: '201': $ref: '#/components/responses/OAuth.DynamicClientRegistration' '400': $ref: '#/components/responses/OAuth.DynamicClientRegistrationError' '422': description: 'Unprocessable entity error. The dynamic client registration feature may not be enabled for this instance.' '500': description: 'Internal server error. The authorization server encountered an unexpected condition that prevented it from fulfilling the registration request.' /oauth/token: post: summary: Get OAuth2 Token description: "Exchange an authorization grant for OAuth2 tokens (access token, refresh token, and optionally ID token).\n\nThis endpoint implements the OAuth 2.0 Token Endpoint (RFC 6749) and OpenID Connect token endpoint.\nIt supports two grant types: `authorization_code` and `refresh_token`.\n\n#### Grant Types\n\n- **`authorization_code`**: Exchange an authorization code for tokens\n- **`refresh_token`**: Refresh an access token using a refresh token\n\n#### Authentication\n\n- **Confidential clients**: Must authenticate using one of the following methods:\n - HTTP Basic Authentication: `Authorization: Basic base64(client_id:client_secret)`\n - Client credentials in request body: Include `client_id` and `client_secret` in form fields\n - *Note: Both methods (`client_secret_basic` and `client_secret_post`) are treated equivalently*\n- **Public clients** (PKCE flow): No client secret required. Must provide `client_id` and `code_verifier` in request body.\n\n#### PKCE (Proof Key\ \ for Code Exchange)\n\nPublic clients and clients that cannot securely store a client secret must use PKCE (RFC 7636).\nWhen using PKCE:\n- Include `code_challenge` and `code_challenge_method` in the authorization request\n- Include `code_verifier` in the token request (instead of `client_secret`)\n\n#### Scopes\n\nAvailable scopes:\n- `openid` - Enables OpenID Connect features, returns an `id_token` in the response\n- `email` - User's email address\n- `profile` - Basic profile information (name, username, picture, etc.)\n- `public_metadata` - Clerk custom scope for public metadata\n- `private_metadata` - Clerk custom scope for private metadata\n\nDefault scopes (if not specified): `email profile`\n\n#### Token Lifespans\n\n- **Access token**: 1 day (86400 seconds)\n- **Refresh token**: 10 years\n- **ID token**: 1 day (86400 seconds)\n- **Authorization code**: 10 minutes (must be exchanged within this time)\n\n#### OpenID Connect\n\nWhen the `openid` scope is included in the authorization\ \ request, the token response will include\nan `id_token` field containing a signed JWT with user identity information per the OpenID Connect specification.\nThe `id_token` will be refreshed along with the access token when using the `refresh_token` grant type." operationId: getOAuthToken security: - ClientCredentials: [] - {} tags: - OAuth2 Identity Provider requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: - grant_type properties: grant_type: type: string description: 'The grant type being used. - `authorization_code`: Exchange an authorization code for tokens - `refresh_token`: Refresh an access token' enum: - authorization_code - refresh_token code: type: string nullable: true description: 'The authorization code received from the authorization endpoint. **Required when `grant_type=authorization_code`**.' redirect_uri: type: string nullable: true description: 'The redirect URI used in the authorization request. Must match exactly. **Required when `grant_type=authorization_code`**.' code_verifier: type: string nullable: true description: 'The PKCE code verifier that corresponds to the `code_challenge` sent in the authorization request. **Required for public clients using PKCE with `grant_type=authorization_code`**. Confidential clients using `client_secret` should not include this parameter.' client_id: type: string nullable: true description: 'The OAuth 2.0 client identifier. **Required for public clients** (those not using HTTP Basic Authentication). For confidential clients, can be provided here or via HTTP Basic Authentication.' client_secret: type: string nullable: true description: 'The OAuth 2.0 client secret. **Required for confidential clients** (unless using HTTP Basic Authentication). Public clients using PKCE should not include this parameter.' refresh_token: type: string nullable: true description: 'The refresh token issued to the client. **Required when `grant_type=refresh_token`**.' scope: type: string nullable: true description: 'Space-separated list of scopes for the access token. **Optional when `grant_type=refresh_token`**. If provided, the requested scope must not exceed the scope originally granted. If omitted, the same scope as originally granted will be used.' examples: authorizationCodeConfidential: summary: Authorization Code - Confidential Client description: Exchange an authorization code for tokens using a confidential client with client secret value: grant_type: authorization_code code: clk_code_abc123xyz redirect_uri: https://example.com/oauth/callback client_id: client_abc123 client_secret: secret_xyz789 authorizationCodePKCE: summary: Authorization Code - Public Client with PKCE description: Exchange an authorization code for tokens using PKCE (public client, no client secret) value: grant_type: authorization_code code: clk_code_abc123xyz redirect_uri: https://example.com/oauth/callback client_id: client_abc123 code_verifier: dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk refreshToken: summary: Refresh Token description: Refresh an access token using a refresh token value: grant_type: refresh_token refresh_token: clk_refresh_abc123xyz client_id: client_abc123 client_secret: secret_xyz789 responses: '200': $ref: '#/components/responses/OAuth.Token' '400': $ref: '#/components/responses/OAuth.TokenError400' '401': $ref: '#/components/responses/OAuth.TokenError401' '403': description: Forbidden error, for example you are trying to use a satellite domain /oauth/userinfo: get: summary: Get User Info After OAuth2 Flow description: Get user info in exchange for a valid OAuth2 access token. operationId: getOAuthUserInfo security: [] tags: - OAuth2 Identity Provider responses: '200': $ref: '#/components/responses/OAuth.UserInfo' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' post: summary: Get User Info After OAuth2 Flow description: Get user info in exchange for a valid OAuth2 access token. operationId: getOAuthUserInfoPOST security: [] tags: - OAuth2 Identity Provider responses: '200': $ref: '#/components/responses/OAuth.UserInfo' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' /oauth/token_info: post: summary: Get Information for an Access or Refresh Token description: Get information for an access or refresh token operationId: getOAuthTokenInfo security: [] tags: - OAuth2 Identity Provider requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: token: type: string description: The value of the access or the refresh token token_type_hint: type: string description: A hint about the type of the token submitted for introspection. Can be one of the following `access_token` and `refresh_token` nullable: true scope: type: string description: The granted scopes for the token to check against nullable: true required: - token responses: '200': $ref: '#/components/responses/OAuth.TokenInfo' '401': description: Unauthorized error, for example the provided client is invalid. '422': description: You are currently using the legacy OAuth 2.0 provider, please migrate to the new one via Clerk Dashboard. /oauth/token/revoke: post: summary: Revoke OAuth2 Token description: 'Revoke OAuth2 token by token. #### Authentication - **Confidential clients**: Must authenticate using HTTP Basic Authentication with Client ID as username and Client Secret as password in the Authorization header.' operationId: revokeOAuthToken security: - ClientCredentials: [] tags: - OAuth2 Identity Provider requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: token: type: string description: The token to revoke. nullable: false token_type_hint: type: string description: A hint about the type of the token to be revoked. nullable: true enum: - access_token - refresh_token responses: '200': description: Success, no content. '400': $ref: '#/components/responses/OAuth.TokenError400' '401': $ref: '#/components/responses/OAuth.TokenError401' /v1/me/oauth/consent/{client_id}: get: summary: Get Consent Information description: 'Returns the scopes for a given OAuth Application Client ID. An optional `scope` query parameter can restrict the returned scopes to only those requested. The OAuth application must have consent screen enabled. ' operationId: getOAuthConsent security: - {} - DevBrowser: [] tags: - OAuth2 Identity Provider parameters: - in: path name: client_id required: true schema: type: string description: The OAuth Application Client ID to get consent information for. - in: query name: scope required: false schema: type: string description: Optional space-separated list of scopes to restrict the response to only those requested. responses: '200': $ref: '#/components/responses/OAuth.ConsentInfo' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' post: summary: Submit OAuth2 Consent Decision description: 'Submits the user''s consent decision for an OAuth2 authorization request. This endpoint allows building custom consent portals as a replacement for the default account-portal-rendered consent screen. The OAuth application must have the consent screen enabled. On grant, the flow continues just like the standard `/oauth/authorize` endpoint and returns the appropriate redirect. In addition to the fields documented below, the request body must re-submit the standard OAuth2 authorize parameters from the original `/oauth/authorize` request: `response_type`, `redirect_uri`, `scope`, `state`, `nonce`, `code_challenge`, and `code_challenge_method`. These are forwarded as-is to the authorize flow. ' operationId: submitOAuthConsent security: - {} - DevBrowser: [] tags: - OAuth2 Identity Provider parameters: - in: path name: client_id required: true schema: type: string description: The OAuth Application Client ID the consent decision applies to. requestBody: content: application/x-www-form-urlencoded: schema: type: object required: - consented properties: consented: type: boolean description: 'The user''s consent decision. `true` grants the requested scopes and continues the authorization flow; any other value is treated as a denial and returns an `access_denied` error in the redirect. ' organization_id: type: string nullable: true description: 'Optional. The organization to scope the issued token to. The authenticated user must be a member of this organization. If omitted, the user''s currently active organization is used. ' responses: '200': description: Success for 'form_post' response mode '302': description: Redirect, no body. '303': description: Redirect, no body. '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/me/organization_creation_defaults: get: operationId: getOrganizationCreationDefaults tags: - Organization Creation Defaults summary: Get Organization Creation Defaults description: 'Get suggested organization name and other defaults for creating a new organization. Returns suggestions based on the user''s email domain or configured naming templates. ' responses: '200': description: Organization creation defaults content: application/json: schema: type: object properties: response: type: object properties: form: type: object nullable: true properties: name: type: string nullable: true description: Suggested organization name logo: type: string nullable: true description: Suggested organization logo URL description: Suggested form values for creating an organization advisory: type: object nullable: true properties: type: type: string enum: - warning - error - info description: Type of advisory message message: type: string description: Advisory message text description: Advisory message if applicable (e.g., organization already exists) client: $ref: '#/components/schemas/Client.Client' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' /v1/account_portal: get: summary: Get Account Portal description: Get users account portal operationId: getAccountPortal responses: '200': $ref: '#/components/responses/Client.AccountPortal' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' /v1/environment: get: summary: Get Environment description: Get the current environment. The environment contains information about the settings and features enabled for the current instance. operationId: getEnvironment security: - {} - DevBrowser: [] tags: - Environment responses: '200': $ref: '#/components/responses/Client.Environment' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' patch: summary: Update Environment description: Update environment using request origin operationId: updateEnvironment security: - {} - DevBrowser: [] tags: - Environment parameters: - in: header name: Origin description: Origin of the request required: true schema: type: string responses: '200': $ref: '#/components/responses/Client.Environment' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' /v1/saml/metadata/{saml_connection_id}.xml: get: summary: SAML Metadata description: The Service Provider's SAML metadata operationId: samlMetadata security: - {} - DevBrowser: [] tags: - SAML parameters: - in: path name: saml_connection_id required: true schema: type: string description: The ID of the SAML Connection responses: '200': description: OK '400': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' /v1/saml/acs/{saml_connection_id}: post: summary: SAML ACS description: 'The SAML Assertion Consumer Service (ACS) endpoint, which processes SAML Responses by the IdP. ' operationId: acs security: - {} - DevBrowser: [] tags: - SAML parameters: - in: path name: saml_connection_id required: true schema: type: string description: The ID of the SAML Connection responses: '302': description: OK '303': description: OK '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' /v1/health: get: summary: Get Health description: Get Health security: - {} - DevBrowser: [] tags: - Health operationId: getHealth responses: '200': description: OK content: application/json: schema: type: object properties: status: type: string enum: - healthy required: - status '503': description: Service is unavailable content: application/json: schema: type: object properties: status: type: string enum: - unhealthy message: type: string required: - status - message /v1/proxy-health: get: summary: Get Proxy Health description: 'Use this endpoint to check the validity of a proxy configuration for a domain. Pass the instance ID and domain ID as query parameters.' operationId: getProxyHealth parameters: - in: query name: domain_id description: The ID of the domain required: true schema: type: string - in: header name: Clerk-Proxy-Url description: The URL of the proxy required: true schema: type: string - in: header name: Clerk-Secret-Key description: The secret key of the proxy required: true schema: type: string - in: header name: X-Forwarded-For description: The IP address of the client required: true schema: type: string responses: '200': description: Configuration is valid content: application/json: schema: oneOf: - type: object properties: status: type: string enum: - healthy x_forwarded_for: type: string required: - status - x_forwarded_for - type: object properties: status: type: string enum: - unhealthy message: type: string required: - status - message '400': $ref: '#/components/responses/ClerkErrors' '503': description: Configuration is invalid or service is unavailable content: application/json: schema: type: object properties: status: type: string enum: - unhealthy message: type: string required: - status - message /v1/client: get: summary: Get Current Client description: Returns the current client that is present either in the browser cookies or authorization header. tags: - Client operationId: getClient security: - {} - DevBrowser: [] responses: '200': $ref: '#/components/responses/Client.Client' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' put: summary: Create New Client description: Creates a new Client and sets it either in the response cookies or the response authorization header. security: - {} - DevBrowser: [] tags: - Client operationId: putClient responses: '200': $ref: '#/components/responses/Client.Client' '307': description: Redirect, no body. post: summary: Create New Client description: Creates a new Client and sets it either in the response cookies or the response authorization header. security: - {} - DevBrowser: [] operationId: postClient tags: - Client responses: '200': $ref: '#/components/responses/Client.Client' '307': description: Redirect, no body. delete: summary: Delete Client's Sessions description: Ends all Sessions of the Current Client tags: - Client operationId: deleteClientSessions responses: '200': $ref: '#/components/responses/Client.DeleteSession' '307': description: Redirect, no body. '404': $ref: '#/components/responses/ClerkErrors' /v1/client/sign_ins: post: security: - {} summary: Create a New Sign in or Replace the Current One. description: 'Creates or replaces the current Sign in object. In order to authenticate a Sign in in as few requests as possible, you can pass in parameters to this request that can identify and verify the Sign in. Parameter rules: If the strategy equals `phone_code`, `email_code`, `web3_[provider]_signature`, `reset_password_code` or `reset_password_phone_code` then an identifier is required. If the strategy equals `email_link` then an identifier is required and optionally redirect_url can be supplied. If the strategy equals `password` then both an identifier and a password is required. If the strategy equals `oauth_[provider]` or `saml` then a redirect_url is required, and an action_complete_redirect_url is optional. If the strategy equals `oauth_token_[provider]` then at least one of code (grant code) or token (openID token) is required. Passing only the token will probably retrieve minimal information about the user from the OAuth provider. You can pass both code and token for the best results. If the strategy equals `ticket` then ticket is required. If the strategy equals `passkey` then no identifier is provided. If the strategy equals `google_one_tap` then token is required.' tags: - Sign Ins operationId: createSignIn parameters: - in: header name: Origin description: The origin of the request schema: type: string requestBody: required: false content: application/x-www-form-urlencoded: schema: type: object properties: strategy: type: string description: 'Strategy used to sign in. Can be one of `phone_code`, `email_code`, `ticket`, `web3_[provider]_signature` `reset_password_code`, `reset_password_phone_code`, `email_link`, `oauth_[provider]`, `oauth_token_[provider]`, `saml`, `password`, `passkey`, `google_one_tap`' nullable: true identifier: type: string description: The unique identifier of the user. This changes depending on the strategy. nullable: true password: type: string description: The password of the user. Only used with password strategy. nullable: true ticket: type: string description: Ticket to be used for signing in. nullable: true redirect_url: type: string nullable: true action_complete_redirect_url: type: string nullable: true transfer: type: boolean nullable: true code: type: string description: The authorization or grant code for an OAuth exchange. Only used with `oauth_token_[provider]` strategies. nullable: true token: type: string description: The ID token from an OpenID Connect flow. Only used with `oauth_token_[provider]` and `google_one_tap` strategies. nullable: true oidc_login_hint: type: string description: Used with `oauth_[provider]`. The given value will be forwarded to the OIDC `login_hint` parameter of the generated redirect URL. nullable: true oidc_prompt: type: string description: Used with `oauth_[provider]` or `enterprise_sso`. The given value will be forwarded to the OIDC `prompt` parameter of the generated redirect URL. When using shared credentials, this value might be adjusted for security reasons. nullable: true responses: '200': $ref: '#/components/responses/Client.SignIn' '307': description: Redirect, no body. '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '409': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/client/sign_ins/{sign_in_id}: get: summary: Retrieve Sign-in description: 'Returns the sign-in with the given ID. The sign in is returned only if it belongs to the requesting client and is not abandoned.' tags: - Sign Ins operationId: getSignIn parameters: - in: path name: sign_in_id required: true schema: type: string description: The ID of the sign in to be retrieved. responses: '200': $ref: '#/components/responses/Client.SignIn' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' /v1/client/sign_ins/{sign_in_id}/reset_password: post: summary: Reset Password on Sign-in description: Reset password on sign-in. tags: - Sign Ins operationId: resetPassword parameters: - in: path name: sign_in_id required: true schema: type: string description: The ID of the sign in to be retrieved. requestBody: content: application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: password: type: string sign_out_of_other_sessions: type: boolean nullable: true required: - password responses: '200': $ref: '#/components/responses/responses-Client.SignIn' '400': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/client/sign_ins/{sign_in_id}/prepare_first_factor: post: summary: Prepare First Factor Verification description: 'Prepares the verification object for the identified Sign in. This step authenticates that the user is who they say they are. Depending on the strategy, this request will do something different. Parameter actions: If the strategy equals email_code then this request will send an email with an OTP code. If the strategy equals phone_code then this request will send an SMS with an OTP code. If the strategy equals oauth_[provider] then this request generate a URL that the User needs to visit in order to authenticate. If the strategy equals passkey then this request will begin the passkey registration flow. Parameter rules: If the strategy equals `oauth_[provider]` then a redirect_url is required, and an action_complete_redirect_url is optional.' tags: - Sign Ins operationId: prepareSignInFactorOne parameters: - in: path name: sign_in_id required: true schema: type: string description: The ID of the sign in to be retrieved. - in: header name: Origin description: The origin of the request schema: type: string requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: strategy: type: string description: 'The strategy to be prepared for first factor authentication. Can be one of the following `email_code`, `email_link`, `phone_code`, `web3_metamask_signature`, `web3_base_signature`, `web3_coinbase_wallet_signature`, `web3_okx_wallet_signature`, `reset_password_phone_code`, `reset_password_email_code`, `oauth_[provider]`, `saml`, `passkey`, `enterprise_sso`' email_address_id: type: string description: Used with the `email_code`, `reset_password_email_code` and `email_link` strategies. nullable: true phone_number_id: type: string description: Used with the `phone_code` and `reset_password_phone_code` strategies. nullable: true web3_wallet_id: type: string description: Used with the `web3_metamask_signature`, `web3_base_signature`, `web3_coinbase_wallet_signature` and `web3_okx_wallet_signature` strategies. nullable: true passkey_id: type: string description: Used with the `passkey` strategy. nullable: true redirect_url: type: string description: Used with `email_link`, `oauth_[provider]`, and `saml` strategies. nullable: true action_complete_redirect_url: type: string description: Used with `oauth_[provider]` and `saml` strategies. nullable: true oidc_login_hint: type: string description: Used with `oauth_[provider]`. The given value will be forwarded to the OIDC `login_hint` parameter of the generated redirect URL. nullable: true oidc_prompt: type: string description: Used with `oauth_[provider]` or `enterprise_sso`. The given value will be forwarded to the OIDC `prompt` parameter of the generated redirect URL. When using shared credentials this value might be adjusted for security reasons. nullable: true required: - strategy responses: '200': $ref: '#/components/responses/Client.SignIn' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' '429': $ref: '#/components/responses/ClerkErrors' /v1/client/sign_ins/{sign_in_id}/attempt_first_factor: post: summary: Attempt First Factor Verification description: 'Attempt the first verification. Requires the sign in attempt to be identified, and the first factor verification to be prepared, unless you''re using a password. Parameter rules: If the strategy equals `email_code` or `phone_code` then a code is required. If the strategy equals `password` then a password is required.' tags: - Sign Ins operationId: attemptSignInFactorOne parameters: - in: path name: sign_in_id required: true schema: type: string description: The ID of the sign in. - in: header name: Origin description: The origin of the request schema: type: string requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: strategy: type: string description: 'The strategy to be used for first factor authentication. Can be one of the following `email_code`, `email_link`, `password`, `phone_code`, `web3_metamask_signature`, `web3_base_signature`, `web3_coinbase_wallet_signature`, `web3_okx_wallet_signature`, `reset_password_phone_code`, `reset_password_email_code`, `passkey`, `google_one_tap`' code: type: string description: The code that was sent to the email. Used with the `email_code`, `phone_code`, and `email_link` strategies. nullable: true password: type: string description: Used with the `password` and `reset_password_phone_code` strategies. nullable: true signature: type: string description: Used with the `web3_metamask_signature`, `web3_base_signature`, `web3_coinbase_wallet_signature` and `web3_okx_wallet_signature` strategies. nullable: true token: type: string description: The ID token from an OpenID Connect flow. Only used with `oauth_token_[provider]` and `google_one_tap` strategies. nullable: true ticket: type: string deprecated: true nullable: true public_key_credential: type: string description: Used with the `passkey` strategy. nullable: true required: - strategy responses: '200': $ref: '#/components/responses/Client.SignIn' '307': description: Redirect, no body. '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' '429': $ref: '#/components/responses/ClerkErrors' /v1/client/sign_ins/{sign_in_id}/prepare_second_factor: post: summary: Prepare Second Factor Verification description: 'Prepare the second verification. Requires the sign in attempt `status` to be equal to `needs_second_factor` or `needs_client_trust`.' tags: - Sign Ins operationId: prepareSignInFactorTwo parameters: - in: path name: sign_in_id required: true schema: type: string description: The ID of the sign in. requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: strategy: type: string description: The strategy to be prepared for second factor authentication. nullable: true enum: - phone_code - email_code - email_link phone_number_id: type: string description: Used with the `phone_code` strategy. nullable: true email_address_id: type: string description: Used with the `email_code` and `email_link` strategies. nullable: true redirect_url: type: string description: Used with the `email_link` strategy. The redirect URL after email link verification. nullable: true responses: '200': $ref: '#/components/responses/Client.SignIn' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/client/sign_ins/{sign_in_id}/attempt_second_factor: post: summary: Attempt Second Factor Verification description: 'Attempt the second verification. Requires the sign in attempt `status` to be equal to `needs_second_factor` or `needs_client_trust`, and for the preparation step to have been called.' tags: - Sign Ins operationId: attemptSignInFactorTwo parameters: - in: path name: sign_in_id required: true schema: type: string description: The ID of the sign in. requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: strategy: type: string description: The strategy to be attempted for second factor authentication. enum: - email_code - phone_code - totp - backup_code code: type: string description: Used with the `phone_code`, `totp` and `backup_code` strategies. responses: '200': $ref: '#/components/responses/Client.SignIn' '307': description: Redirect, no body. '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/client/sign_ins/{sign_in_id}/protect_check: {} /v1/client/sign_ups: post: summary: Create Sign-up description: Creates or replaces the sign-up on the current Client object. tags: - Sign Ups operationId: createSignUps parameters: - in: header name: Origin description: The origin of the request schema: type: string requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: transfer: type: boolean nullable: true password: type: string nullable: true first_name: type: string nullable: true last_name: type: string nullable: true username: type: string nullable: true email_address: type: string nullable: true phone_number: type: string nullable: true email_address_or_phone_number: type: string nullable: true unsafe_metadata: type: string nullable: true strategy: type: string description: 'Strategy used to sign up. Can be one of `email_code`, `email_link`, `enterprise_sso`, `google_one_tap`, `oauth_[provider]`, `oauth_token_[provider]`, `phone_code`, `saml`, `ticket`, `web3_[provider]_signature`' nullable: true action_complete_redirect_url: type: string nullable: true redirect_url: type: string nullable: true ticket: type: string nullable: true web3_wallet: type: string nullable: true token: type: string description: The ID token from an OpenID Connect flow. Only used with `oauth_token_[provider]` and `google_one_tap` strategies. nullable: true code: type: string description: The authorization or grant code for an OAuth exchange. Only used with `oauth_token_[provider]` strategies. nullable: true captcha_token: type: string nullable: true captcha_error: type: string nullable: true captcha_widget_type: type: string nullable: true legal_accepted: type: boolean nullable: true description: Has the value `true` if the user has accepted the legal requirements. oidc_login_hint: type: string description: Used with `oauth_[provider]`. The given value will be forwarded to the OIDC `login_hint` parameter of the generated redirect URL. nullable: true oidc_prompt: type: string description: Used with `oauth_[provider]` or `enterprise_sso`. The given value will be forwarded to the OIDC `prompt` parameter of the generated redirect URL. When using shared credentials this value might be adjusted for security reasons. nullable: true responses: '200': $ref: '#/components/responses/Client.SignUp' '307': description: Redirect, no body. '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '409': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/client/sign_ups/{sign_up_id}: get: summary: Get Sign-up description: Returns the sign-up by ID. Must be associated with the current Client object. tags: - Sign Ups operationId: getSignUps parameters: - in: path name: sign_up_id required: true schema: type: string description: The sign up unique identifier. responses: '200': $ref: '#/components/responses/Client.SignUp' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' patch: summary: Update Sign-up description: Updates the sign-up object specified by ID, with the supplied parameters. tags: - Sign Ups operationId: updateSignUps parameters: - in: path name: sign_up_id required: true schema: type: string description: The sign up unique identifier. - in: header name: Origin description: The origin of the request schema: type: string requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: password: type: string nullable: true first_name: type: string nullable: true last_name: type: string nullable: true username: type: string nullable: true email_address: type: string nullable: true phone_number: type: string nullable: true email_address_or_phone_number: type: string nullable: true unsafe_metadata: type: string nullable: true strategy: type: string description: 'Strategy used to sign up. Can be one of `email_code`, `email_link`, `enterprise_sso`, `google_one_tap`, `oauth_[provider]`, `oauth_token_[provider]`, `phone_code`, `saml`, `ticket`, `web3_[provider]_signature`' nullable: true redirect_url: type: string nullable: true action_complete_redirect_url: type: string nullable: true ticket: type: string nullable: true web3_wallet: type: string nullable: true token: type: string description: The ID token from an OpenID Connect flow. Only used with `oauth_token_[provider]` and `google_one_tap` strategies. nullable: true code: type: string description: The authorization or grant code for an OAuth exchange. Only used with `oauth_token_[provider]` strategies. nullable: true legal_accepted: type: boolean nullable: true description: 'Has the value `true` if the user has accepted the legal requirements. ' oidc_login_hint: type: string description: Used with `oauth_[provider]`. The given value will be forwarded to the OIDC `login_hint` parameter of the generated redirect URL. nullable: true oidc_prompt: type: string description: Used with `oauth_[provider]` or `enterprise_sso`. The given value will be forwarded to the OIDC `prompt` parameter of the generated redirect URL. When using shared credentials this value might be adjusted for security reasons. nullable: true responses: '200': $ref: '#/components/responses/Client.SignUp' '307': description: Redirect, no body. '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/client/sign_ups/{sign_up_id}/prepare_verification: post: summary: Prepare Sign-up Identification Verification description: 'Prepares verification for the sign-up specified by `{id}`. Depending on the given strategy, the API will prepare the verification for the current sign-up. In particular, * for `email_code`, the API will send a verification email to the email address currently load up in the sign-up * for `phone_code`, the API will send a verification SMS to the phone number currently load up in the sign-up ' tags: - Sign Ups operationId: prepareSignUpsVerification parameters: - in: path name: sign_up_id required: true schema: type: string description: The sign up unique identifier. - in: header name: Origin description: The origin of the request schema: type: string requestBody: content: application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: strategy: type: string description: 'The verification strategy - email_code - email_link - phone_code - web3_metamask_signature - web3_base_signature - web3_coinbase_wallet_signature - web3_okx_wallet_signature - saml - oauth' redirect_url: type: string nullable: true action_complete_redirect_url: type: string nullable: true oidc_login_hint: type: string description: Used with `oauth_[provider]`. The given value will be forwarded to the OIDC `login_hint` parameter of the generated redirect URL. nullable: true oidc_prompt: type: string description: Used with `oauth_[provider]` or `enterprise_sso`. The given value will be forwarded to the OIDC `prompt` parameter of the generated redirect URL. When using shared credentials this value might be adjusted for security reasons. nullable: true responses: '200': $ref: '#/components/responses/Client.SignUp' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' '429': $ref: '#/components/responses/ClerkErrors' /v1/client/sign_ups/{sign_up_id}/attempt_verification: post: summary: Attempt Sign-up Identification Verification description: Attempts to verify the identification that corresponds to the given strategy using the given verification code. tags: - Sign Ups operationId: attemptSignUpsVerification parameters: - in: path name: sign_up_id required: true schema: type: string description: The sign up unique identifier. - in: header name: Origin description: The origin of the request schema: type: string requestBody: content: application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: strategy: type: string description: The verification strategy enum: - email_code - email_link - phone_code - web3_metamask_signature - web3_base_signature - web3_coinbase_wallet_signature - web3_okx_wallet_signature - web3_solana_signature - google_one_tap code: nullable: true type: string description: The verification code signature: nullable: true type: string description: The verification web3 signature token: type: string description: The ID token from an OpenID Connect flow. Only used with `oauth_token_[provider]` and `google_one_tap` strategies. nullable: true responses: '200': $ref: '#/components/responses/Client.SignUp' '307': description: Redirect, no body. '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '409': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' '429': $ref: '#/components/responses/ClerkErrors' /v1/client/sync: get: summary: Sync Clients Across Multiple Domains description: Start the syncing process between a satellite and primary domain. operationId: syncClient parameters: - in: query name: link_domain schema: type: string description: The satellite domain which should be synced with its primary. - in: query name: redirect_url schema: type: string description: The URL to redirect to after the syncing process has been completed. responses: '307': description: Redirect '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/client/link: get: summary: Link Clients Across Multiple Domains description: Complete a syncing process between a satellite and primary domains by linking their clients. operationId: linkClient parameters: - in: query name: __clerk_token schema: type: string description: The token generated from a sync request. responses: '307': description: Redirect '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/client/handshake: get: summary: Generate and Return a New Session Token for a Given Client. description: When the authentication status cannot be determined from the current session token, we initiate a handshake to refresh the token and send it back to the application. Called in server environments. tags: - Client operationId: handshakeClient parameters: - in: header name: Clerk-Proxy-Url description: The URL of the proxy schema: type: string - in: header name: Clerk-Secret-Key description: The secret key of the proxy schema: type: string - in: query name: redirect_url schema: type: string description: The URL to redirect back to after the handshake - in: query name: format allowEmptyValue: false required: false schema: type: string enum: - nonce - token default: token description: The supported format of the handshake payload. - in: query name: organization_id schema: type: string allowEmptyValue: true description: 'The organization ID or slug to attempt to set as active for the session. If this param is present but has no value, the personal account will be set as active. If the organization cannot be set as active (because it does not exist, or the user is not a member), the active organization for the session will not change. ' - in: query name: satellite_fapi description: The Frontend API of the satellite domain schema: type: string responses: '307': description: Redirect '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' '500': $ref: '#/components/responses/ClerkErrors' /v1/agents/tasks: get: x-speakeasy-group: agentTasks x-speakeasy-name-override: create summary: Create Session from Agent Task description: 'Creates a new session directly from an agent task without requiring navigation to the sign-in page. Agent tasks are single-use tokens created via the Backend API that bypass MFA requirements. The endpoint returns a redirect with a handshake cookie containing all session cookies, enabling cookie sync to the app domain in a single step. This is useful for browser automation tools (Puppeteer, Playwright) that need cookies on the application domain. ' tags: - Client operationId: createAgentTask security: - {} - DevBrowser: [] parameters: - in: query name: ticket required: true schema: type: string description: The agent task ticket value obtained from the Backend API. responses: '307': description: "Redirect to the `redirect_url` specified when the agent task was created.\n\nBefore redirecting, the URL is validated:\n- Must be a valid absolute URL with an `https` scheme in production.\n In development instances, `http` is also permitted.\n- The URL's domain must belong to one of the instance's associated domains\n (primary or satellite).\n\nIn production, the handshake payload is set as a cookie.\nIn development, the handshake payload is passed as a query parameter.\n" '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' '500': $ref: '#/components/responses/ClerkErrors' /v1/dev_browser: post: summary: Create a Dev Browser Token description: 'Generate a Dev Browser API token. This is used to authenticate Development Instances with the `DevBrowser` scheme. It must be set before making any request to a dev instance, even for endpoints that are public.' operationId: createDevBrowser security: [] tags: - DevBrowser responses: '200': description: A DevBrowser was created. '400': description: The hostname is invalid. /v1/dev_browser/set_first_party_cookie: post: summary: Post Dev Browser Init Set Cookie description: post dev_browser/set_first_party_cookie operationId: postDevBrowserInitSetCookie responses: '200': description: A cookie for the dev browser was set. /v1/dev_browser/init: get: summary: Initialize Dev Browser for Development and Staging Instances description: get dev_browser/init operationId: getDevBrowserInit parameters: - in: query name: origin description: The origin of the request schema: type: string responses: '200': description: Successfully initialized the dev browser. '400': $ref: '#/components/responses/ClerkErrors' '500': $ref: '#/components/responses/ClerkErrors' /v1/dev_tools/enable_environment_setting: {} /v1/oauth_callback: get: operationId: getOauthCallback summary: OAuth Callback description: The endpoint where the OAuth providers redirect to after a successful authentication attempt. tags: - OAuth2 Callbacks parameters: - in: query name: scope schema: type: string description: returned scopes from OAuth provider. - in: query name: code schema: type: string description: returned exchange code from OAuth provider. - in: query name: state schema: type: string description: returned state from OAuth provider. - in: query name: error schema: type: string description: returned error state from OAuth provider, if applicable responses: '200': description: '[AuthV2] HTML-based redirection in dev instances' '299': description: FAKE SUCCESS '301': description: Redirect '303': description: Redirect '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' post: operationId: postOauthCallback summary: OAuth Post Callback description: Converts a POST to a GET, because if it's a POST coming from an external account. This is necessary because some providers (e.g. Apple) issue a POST instead of a GET request. tags: - OAuth2 Callbacks requestBody: content: application/x-www-form-urlencoded: schema: type: object additionalProperties: true properties: code: description: returned exchange code from OAuth provider. type: string scope: description: returned scopes from OAuth provider. type: string nullable: true state: description: returned state from OAuth provider. type: string error: description: returned error state from OAuth provider, if applicable type: string nullable: true responses: '303': description: Redirect to GET /v1/oauth_callback with same parameters /v1/clear-site-data: get: summary: Set the Clear-Site-Data Header description: Clear browsing data (cookies, storage, cache) associated with the requesting website operationId: clearSiteData responses: '200': description: The Clear-Site-Data header was set with wildcard value. /v1/client/sessions: delete: summary: Remove Client's Sessions description: Removes all the sessions of the current client without removing the __client cookie tags: - Sessions operationId: removeClientSessionsAndRetainCookie responses: '200': $ref: '#/components/responses/Client.DeleteSession' '401': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' /v1/client/sessions/{session_id}: get: operationId: getSession summary: Get Session description: Returns the session with the given id tags: - Sessions parameters: - in: path name: session_id required: true schema: type: string description: The user session ID. responses: '200': $ref: '#/components/responses/Client.Session' '401': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' /v1/client/sessions/{session_id}/touch: post: operationId: touchSession summary: Touch Session description: 'Specify the active session for the client. When force organization selection is enabled and `active_organization_id` is sent as null or empty string, the session will keep the previous active organization and will not attempt to switch to a personal account.' tags: - Sessions parameters: - in: path name: session_id required: true schema: type: string description: The user session ID. requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: active_organization_id: type: string description: 'The ID or slug of the organization to activate. When force organization selection is enabled and this value is sent as null or empty string, the session will keep the previous active organization and will not attempt to switch to a personal account.' nullable: true intent: type: string description: Indicates why the touch request was triggered. enum: - focus - select_session - select_org nullable: true responses: '200': $ref: '#/components/responses/Client.TouchSession' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/client/sessions/{session_id}/end: post: operationId: endSession summary: End Session description: Marks the given session as ended. tags: - Sessions parameters: - in: path name: session_id required: true schema: type: string description: The user session ID. responses: '200': $ref: '#/components/responses/Client.Session' '400': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' /v1/client/sessions/{session_id}/remove: post: operationId: removeSession summary: Remove Session description: Delete the given session. tags: - Sessions parameters: - in: path name: session_id required: true schema: type: string description: The user session ID. responses: '200': $ref: '#/components/responses/Client.Session' '400': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' /v1/me/sessions/active: get: summary: Get Active Sessions description: Returns all active session for user, including activity information. tags: - Active Sessions operationId: getSessions parameters: - in: query name: _clerk_session_id schema: type: string description: The session_id associated with the requesting user. responses: '200': $ref: '#/components/responses/Client.ActiveSessions' '401': $ref: '#/components/responses/ClerkErrors' /v1/me/sessions/{session_id}/revoke: post: summary: Revoke Given Session description: Revokes given session. tags: - Active Sessions operationId: revokeSession parameters: - in: query name: _clerk_session_id schema: type: string description: The session_id associated with the requesting user. - in: path name: session_id required: true schema: type: string description: The session ID to be revoked. responses: '200': $ref: '#/components/responses/Client.Session' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' /v1/client/sessions/{session_id}/tokens: post: summary: Create Session Token description: 'Create a session JWT for the authenticated requested user. When force organization selection is enabled and `organization_id` is sent as null or empty string, the token will be created with the previous active organization and will not attempt to switch to a personal account.' operationId: createSessionToken tags: - Sessions parameters: - in: path name: session_id required: true schema: type: string description: The user session ID. requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: organization_id: type: string description: 'The organization ID to associate with the token. The user must be a member of the organization. If present but empty, the personal account will be set as active. If absent, the previous active organization for the session will be used. When force organization selection is enabled and this value is sent as null or empty string, the token will be created with the previous active organization and will not attempt to switch to a personal account.' nullable: true responses: '200': description: OK content: application/json: schema: type: object properties: jwt: type: string '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' /v1/client/sessions/{session_id}/tokens/{template_name}: post: summary: Create Session Token with JWT Template description: Create a session JWT for the authenticated requested user. operationId: createSessionTokenWithTemplate tags: - Sessions parameters: - in: path name: session_id required: true schema: type: string description: The user session ID. - in: path name: template_name required: true schema: type: string description: the template name responses: '200': description: OK content: application/json: schema: type: object properties: jwt: type: string '401': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' /v1/client/sessions/{session_id}/verify: post: summary: Start a New Session Reverification description: 'Start a new session reverification flow by providing a verification level. If the requested level equals ''secondFactor'' or ''multiFactor'' and the associated user doesn''t have any available second factor, then we fall back to ''firstFactor''' tags: - Sessions operationId: startSessionReverification parameters: - in: path name: session_id required: true schema: type: string description: the user session ID. requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: level: type: string description: The level of authentication that the user needs to go through enum: - first_factor - second_factor - multi_factor required: - level responses: '200': $ref: '#/components/responses/Client.SessionReverification' '401': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/client/sessions/{session_id}/verify/prepare_first_factor: post: summary: Prepare Session Reverification First Factor description: 'Prepare the first factor verification. Depending on the strategy, this request will do something different. Parameter actions: If the strategy equals email_code then this request will send an email with an OTP code. If the strategy equals phone_code then this request will send an SMS with an OTP code.' tags: - Sessions operationId: prepareSessionReverificationFirstFactor parameters: - in: header name: Origin description: The origin of the request schema: type: string - in: path name: session_id required: true schema: type: string description: the user session ID. requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: strategy: type: string description: The strategy to be prepared for first factor authentication. enum: - email_code - phone_code - passkey - enterprise_sso email_address_id: type: string description: Used with the `email_code` strategy. nullable: true phone_number_id: type: string description: Used with the `phone_code` strategy. nullable: true responses: '200': $ref: '#/components/responses/Client.SessionReverification' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/client/sessions/{session_id}/verify/attempt_first_factor: post: summary: Attempt Session Reverification First Factor description: 'Attempt the first factor verification. Requires the first factor verification to be prepared, unless you''re using a password. Parameter rules: If the strategy equals `email_code` then a code is required. If the strategy equals `password` then a password is required.' tags: - Sessions operationId: attemptSessionReverificationFirstFactor parameters: - in: header name: Origin description: The origin of the request schema: type: string - in: path name: session_id required: true schema: type: string description: the user session ID. requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: strategy: type: string description: The strategy to be used for first factor authentication. enum: - email_code - password - phone_code - passkey code: type: string description: The code that was sent to the email. Used with the `email_code` and `phone_code` strategies. nullable: true password: type: string description: Used with the `password` strategy. nullable: true public_key_credential: type: string description: Used with the `passkey` strategy. nullable: true required: - strategy responses: '200': $ref: '#/components/responses/Client.SessionReverification' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/client/sessions/{session_id}/verify/prepare_second_factor: post: summary: Prepare Session Reverification Second Factor description: 'Prepare the second factor verification. Requires the `status` to be equal to `needs_second_factor`.' tags: - Sessions operationId: prepareSessionReverificationSecondFactor parameters: - in: path name: session_id required: true schema: type: string description: the user session ID. requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: strategy: type: string description: The strategy to be prepared for second factor authentication. nullable: true enum: - phone_code phone_number_id: type: string description: Used with the `phone_code` strategy. nullable: true responses: '200': $ref: '#/components/responses/Client.SessionReverification' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/client/sessions/{session_id}/verify/attempt_second_factor: post: summary: Attempt Session Reverification Second Factor description: 'Attempt the second factor verification. Requires the `status` to be equal to `needs_second_factor` and for the preparation step to have been called.' tags: - Sessions operationId: attemptSessionReverificationSecondFactor parameters: - in: path name: session_id required: true schema: type: string description: the user session ID. requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: strategy: type: string description: The strategy to be attempted for second factor authentication. enum: - phone_code - totp - backup_code code: type: string description: Used with the `phone_code`, `totp` and `backup_code` strategies. responses: '200': $ref: '#/components/responses/Client.SessionReverification' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/me/sessions: get: summary: Get Sessions description: Get all the sessions of the current user. tags: - Active Sessions operationId: getUsersSessions parameters: - in: query name: _clerk_session_id schema: type: string description: The session_id associated with the requesting user. responses: '200': $ref: '#/components/responses/Server.Sessions' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' /v1/me/enterprise_connections: {} /v1/me/enterprise_connections/{enterprise_connection_id}: {} /v1/me/enterprise_connections/{enterprise_connection_id}/test_runs: {} /v1/enterprise_connections/{enterpriseConnectionID}/init_test_run: {} /v1/enterprise_connections/{enterpriseConnectionID}/test_runs/{testRunID}: {} /v1/me/email_addresses: get: operationId: getEmailAddresses summary: Get Email Addresses description: Retrieve all the email addresses associated with the current user. tags: - Email Addresses parameters: - in: query name: _clerk_session_id schema: type: string description: The session_id associated with the requesting user. responses: '200': $ref: '#/components/responses/Server.UserEmailAddresses' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' post: summary: Create Email Address description: Add an email address to the current user. The address then needs to be verified using the `prepare_verification` and `attempt_verification` endpoints. operationId: createEmailAddresses tags: - Email Addresses parameters: - in: query name: _clerk_session_id schema: type: string description: The session_id associated with the requesting user. requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: email_address: type: string description: The email address to be added to the user. required: - email_address responses: '200': $ref: '#/components/responses/Client.ClientWrappedEmailAddress' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/me/email_addresses/{email_id}/attempt_verification: post: operationId: verifyEmailAddress description: Attempt to verify an email address that was previously created. summary: Attempt Email Address Verification tags: - Email Addresses parameters: - in: path required: true name: email_id schema: type: string description: The email_id. - in: query name: _clerk_session_id schema: type: string description: The session_id associated with the requesting user. requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: code: type: string description: The code that was previously sent to the email address. required: - code responses: '200': $ref: '#/components/responses/Client.ClientWrappedEmailAddress' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/me/email_addresses/{email_id}/prepare_verification: post: description: 'Depending on the given strategy, the API will prepare the verification for the email address. In particular, * for `email_code`, the API will send a verification email to the address containing a code. * for `email_link`, the API will send a verification email to the address containing a link to the verification attempt endpoint. * for `enterprise_sso`, the API will send an external redirect URL to the browser containing a link to the SSO verification endpoint.' summary: Prepare Email Address Verification tags: - Email Addresses operationId: sendVerificationEmail parameters: - in: path name: email_id required: true schema: type: string description: The email_id. - in: query name: _clerk_session_id schema: type: string description: The session_id associated with the requesting user. requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: strategy: type: string description: The strategy to be prepared for email verification. enum: - email_code - email_link - enterprise_sso redirect_url: type: string description: Used with the `email_link` strategy. nullable: true action_complete_redirect_url: type: string description: Used with `oauth_[provider]` and `saml` strategies. nullable: true required: - strategy responses: '200': $ref: '#/components/responses/Client.ClientWrappedEmailAddress' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/me/email_addresses/{email_id}: get: summary: Get Email Address description: Retrieve an email address by ID. tags: - Email Addresses operationId: getEmailAddress parameters: - in: path name: email_id required: true schema: type: string description: The email_id. - in: query name: _clerk_session_id schema: type: string description: The session_id associated with the requesting user. responses: '200': $ref: '#/components/responses/Client.ClientWrappedEmailAddress' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' delete: summary: Delete Email Address description: Delete an email address by ID. tags: - Email Addresses operationId: DeleteEmailAddress parameters: - in: path name: email_id required: true schema: type: string description: The email_id. - in: query name: _clerk_session_id schema: type: string description: The session_id associated with the requesting user. responses: '200': $ref: '#/components/responses/Client.ClientWrappedDeletedObject' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' /v1/me/phone_numbers: get: summary: Get Phone Numbers description: Retrieve all phone numbers associated with the current user. operationId: getPhoneNumbers tags: - Phone Numbers parameters: - in: query name: _clerk_session_id schema: type: string description: The session_id associated with the requesting user. responses: '200': $ref: '#/components/responses/Server.UserPhoneNumbers' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' post: summary: Create Phone Number description: Add a phone number to the current user. The phone number then needs to be verified using the sms `prepare_verification` and `attempt_verification` endpoints. tags: - Phone Numbers operationId: postPhoneNumbers parameters: - in: query name: _clerk_session_id schema: type: string description: The session_id associated with the requesting user. requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: phone_number: type: string description: The phone number to be added to the user. reserved_for_second_factor: type: boolean description: Whether the phone number is reserved for multi-factor authentication. nullable: true required: - phone_number responses: '200': $ref: '#/components/responses/Client.ClientWrappedPhoneNumber' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/me/phone_numbers/{phone_number_id}/attempt_verification: post: summary: Attempt Phone Number Verification description: Attempt to verify the given phone number using the code sent during the `prepare_verification` step. tags: - Phone Numbers operationId: verifyPhoneNumber parameters: - in: path required: true name: phone_number_id schema: type: string description: The phone_number_id. - in: query name: _clerk_session_id schema: type: string description: The session_id associated with the requesting user. requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: code: type: string description: Strategy used to verify the phone number. required: - code responses: '200': $ref: '#/components/responses/Client.ClientWrappedPhoneNumber' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' '429': $ref: '#/components/responses/ClerkErrors' /v1/me/phone_numbers/{phone_number_id}/prepare_verification: post: summary: Prepare Phone Number Verification description: Sends an SMS to the phone number with the code needed to verify it. tags: - Phone Numbers operationId: sendVerificationSMS parameters: - in: path required: true name: phone_number_id schema: type: string description: The phone_number_id. - in: query name: _clerk_session_id schema: type: string description: The session_id associated with the requesting user. requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: strategy: type: string description: Strategy used to verify the phone number. enum: - phone_code required: - strategy responses: '200': $ref: '#/components/responses/Client.ClientWrappedPhoneNumber' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '429': $ref: '#/components/responses/ClerkErrors' /v1/me/phone_numbers/{phone_number_id}: get: summary: Retrieve Phone Number description: Retrieve all properties for the given phone number. tags: - Phone Numbers operationId: ReadPhoneNumber parameters: - in: path required: true name: phone_number_id schema: type: string description: The phone_number_id. - in: query name: _clerk_session_id schema: type: string description: The session_id associated with the requesting user. responses: '200': $ref: '#/components/responses/Client.ClientWrappedPhoneNumber' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' patch: summary: Update Phone Number description: Update the properties of the given phone number. tags: - Phone Numbers operationId: UpdatePhoneNumber parameters: - in: path required: true name: phone_number_id schema: type: string description: The phone_number_id. - in: query name: _clerk_session_id schema: type: string description: The session_id associated with the requesting user. requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: reserved_for_second_factor: type: boolean description: Whether the phone number is reserved for multi-factor authentication. nullable: true default_second_factor: type: boolean description: Marks the phone number as the default that will be used in multi-factor authentication. nullable: true responses: '200': $ref: '#/components/responses/Client.ClientWrappedPhoneNumber' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' delete: summary: Delete Phone Number description: Deletes the phone number with the given ID. operationId: DeletePhoneNumber tags: - Phone Numbers parameters: - in: path required: true name: phone_number_id schema: type: string description: The phone_number_id. - in: query name: _clerk_session_id schema: type: string description: The session_id associated with the requesting user. responses: '200': $ref: '#/components/responses/Client.DeletedPhoneNumber' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' /v1/me/web3_wallets: get: summary: Get All Web3 Wallets description: Retrieve all web3 wallets associated with the current user. operationId: getWeb3Wallets tags: - Web3 Wallets parameters: - in: query name: _clerk_session_id schema: type: string description: The session_id associated with the requesting user. responses: '200': $ref: '#/components/responses/Server.UserWeb3Wallets' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' post: summary: Create Web3 Wallet description: Create a new web3 wallet. operationId: postWeb3Wallets tags: - Web3 Wallets parameters: - in: query name: _clerk_session_id schema: type: string description: The session_id associated with the requesting user. requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: web3_wallet: type: string description: The web3 wallet to be added to the user. required: - web3_wallet responses: '200': $ref: '#/components/responses/Client.ClientWrappedWeb3Wallet' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/me/web3_wallets/{web3_wallet_id}: get: summary: Get Web3 Wallet description: Retrieve all properties associated with a specific web3 wallet. operationId: readWeb3Wallet tags: - Web3 Wallets parameters: - in: path required: true name: web3_wallet_id schema: type: string description: The web3 wallet ID. responses: '200': $ref: '#/components/responses/Client.ClientWrappedWeb3Wallet' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' delete: summary: Delete Web3 Wallet description: Delete a web3 wallet by ID. operationId: deleteWeb3Wallet tags: - Web3 Wallets parameters: - in: path required: true name: web3_wallet_id schema: type: string description: The web3 wallet ID. responses: '200': $ref: '#/components/responses/Client.DeletedPhoneNumber' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' /v1/me/web3_wallets/{web3_wallet_id}/prepare_verification: post: summary: Prepare Web3 Wallet Verification description: Prepares verification for the provided web3 wallet. operationId: prepareWeb3WalletVerification tags: - Web3 Wallets parameters: - in: path required: true name: web3_wallet_id description: The web3 wallet ID. schema: type: string - in: header name: Origin description: The origin of the request. schema: type: string requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: strategy: type: string description: The strategy used to verify the web3 wallet. pattern: ^web3_\w+_signature$ redirect_url: type: string description: The redirect URL to redirect the user to after verification. nullable: true required: - strategy responses: '200': $ref: '#/components/responses/Client.ClientWrappedWeb3Wallet' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/me/web3_wallets/{web3_wallet_id}/attempt_verification: post: summary: Attempt Web3 Wallet Verification description: Attempts to verify the provided web3 wallet. operationId: attemptWeb3WalletVerification tags: - Web3 Wallets parameters: - in: path required: true name: web3_wallet_id schema: type: string description: The web3 wallet ID. - in: header name: Origin description: The origin of the request. schema: type: string requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: signature: type: string description: The signature that was generated from your Web3 Wallet to sign the message required: - signature responses: '200': $ref: '#/components/responses/Client.ClientWrappedWeb3Wallet' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/me/passkeys: post: summary: Create Passkey description: Create a new passkey. operationId: postPasskey tags: - Passkeys parameters: - in: query name: _clerk_session_id description: The session_id associated with the requesting user. schema: type: string - in: header name: Origin description: The origin of the request. schema: type: string - in: header name: X-Original-Host description: The original host of the request. schema: type: string responses: '200': $ref: '#/components/responses/Client.ClientWrappedPasskey' '403': $ref: '#/components/responses/ClerkErrors' /v1/me/passkeys/{passkey_id}: get: summary: Get Passkey description: Retrieve all properties associated with a specific passkey. operationId: readPasskey tags: - Passkeys parameters: - in: path required: true name: passkey_id schema: type: string description: The passkey identification ID. responses: '200': $ref: '#/components/responses/Client.ClientWrappedPasskey' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' patch: summary: Update Passkey description: Update properties of a specific passkey. operationId: patchPasskey tags: - Passkeys parameters: - in: path required: true name: passkey_id schema: type: string description: The passkey identification ID. requestBody: content: application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: name: type: string nullable: true description: The name of the passkey. responses: '200': $ref: '#/components/responses/Client.ClientWrappedPasskey' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' delete: summary: Delete Passkey description: Delete a passkey by ID. operationId: deletePasskey tags: - Passkeys parameters: - in: path required: true name: passkey_id schema: type: string description: The passkey identification ID. responses: '200': $ref: '#/components/responses/Client.DeletedPasskey' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' /v1/me/passkeys/{passkey_id}/attempt_verification: post: summary: Attempt Passkey Verification description: Attempts to verify the provided passkey. operationId: attemptPasskeyVerification tags: - Passkeys parameters: - in: path required: true name: passkey_id schema: type: string description: The passkey identification ID. - in: header name: Origin description: The origin of the request. schema: type: string requestBody: content: application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: strategy: type: string description: The strategy used to connect the external account. nullable: true enum: - passkey public_key_credential: type: string description: The public key credential of the passkey. nullable: true responses: '200': $ref: '#/components/responses/Client.ClientWrappedPasskey' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/me/external_accounts: post: summary: Connect OAuth Accounts description: Connect a new External Account from the OAuth providers enabled. tags: - External Accounts operationId: postOAuthAccounts parameters: - in: header name: Origin description: The origin of the request. schema: type: string requestBody: content: application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: strategy: type: string description: 'The OAuth strategy that the external account provider supports. Optional when `enterprise_connection_id` is provided. Can be one of `oauth_[provider]` or `oauth_token_[provider]`. The `oauth_[provider]` strategy can be used for regular OAuth flows with redirects and a `redirect_url` parameter is also required. The `oauth_token_[provider]` strategy can be used for native flows, along with a `token` or `code` parameter.' pattern: ^oauth_(?:(?:token_)|(?:custom_))?[a-z0-9_]+$ enterprise_connection_id: type: string description: The ID of an enterprise connection to link. When provided, strategy is not required. nullable: true redirect_url: type: string nullable: true action_complete_redirect_url: type: string nullable: true additional_scope: type: string nullable: true code: type: string description: The authorization or grant code that an OAuth provider returns during authentication. Can be used with `oauth_token_[provider]` strategies. nullable: true token: type: string description: The ID token that an OpenID Connect provider returns during authentication. Can be used with `oauth_token_[provider]` strategies. nullable: true oidc_login_hint: type: string description: Used with `oauth_[provider]`. The given value will be forwarded to the OIDC `login_hint` parameter of the generated redirect URL. nullable: true oidc_prompt: type: string description: Used with `oauth_[provider]` or `enterprise_sso`. The given value will be forwarded to the OIDC `prompt` parameter of the generated redirect URL. When using shared credentials this value might be adjusted for security reasons. nullable: true responses: '200': $ref: '#/components/responses/Client.ClientWrappedExternalAccount' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' '500': $ref: '#/components/responses/ClerkErrors' /v1/me/external_accounts/{external_account_id}/reauthorize: patch: summary: Reauthorize External Account operationId: reauthorizeExternalAccount description: Reauthorize an external account by ID. tags: - External Accounts parameters: - name: external_account_id in: path description: External account ID required: true schema: type: string requestBody: content: application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: additional_scope: type: array items: type: string nullable: true redirect_url: type: string action_complete_redirect_url: type: string nullable: true oidc_login_hint: type: string description: Used with `oauth_[provider]`. The given value will be forwarded to the OIDC `login_hint` parameter of the generated redirect URL. nullable: true oidc_prompt: type: string description: Used with `oauth_[provider]` or `enterprise_sso`. The given value will be forwarded to the OIDC `prompt` parameter of the generated redirect URL. When using shared credentials this value might be adjusted for security reasons. nullable: true required: - redirect_url responses: '200': $ref: '#/components/responses/Client.ClientWrappedExternalAccount' '400': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/me/external_accounts/{external_account_id}: delete: summary: Delete External Account operationId: deleteExternalAccount description: Delete an external account by ID. tags: - External Accounts parameters: - name: external_account_id in: path description: External account ID required: true schema: type: string responses: '200': $ref: '#/components/responses/Client.DeletedExternalAccount' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' /v1/me/external_accounts/{external_account_id}/tokens: delete: summary: Revoke OAuth Tokens operationId: revokeExternalAccountTokens description: Revoke the OAuth access and refresh token of an external account by ID, if supported by the provider. tags: - External Accounts parameters: - name: external_account_id in: path description: External account ID required: true schema: type: string responses: '200': $ref: '#/components/responses/Client.ClientWrappedUser' '400': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' /v1/me/totp: post: summary: Create TOTP description: Initializes TOTP by generating a new secret. This then needs to be added to an authenticator app and verified. A user can have only one TOTP secret and this endpoint will return an error if it is already present. tags: - TOTP operationId: postTOTP responses: '200': $ref: '#/components/responses/Client.ClientWrappedTOTP' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '500': $ref: '#/components/responses/ClerkErrors' delete: summary: Delete TOTP description: Deletes the current TOTP secret. This will invalidate all authenticators that where previously added. tags: - TOTP operationId: deleteTOTP responses: '200': $ref: '#/components/responses/Client.DeletedTOTP' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '500': $ref: '#/components/responses/ClerkErrors' /v1/me/totp/attempt_verification: post: summary: Attempt TOTP Verification description: Attempts to verify the TOTP secret previously created using a code from an authenticator. tags: - TOTP operationId: verifyTOTP requestBody: content: application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: code: type: string nullable: false responses: '200': $ref: '#/components/responses/Client.ClientWrappedTOTP' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' '500': $ref: '#/components/responses/ClerkErrors' /v1/me/backup_codes: post: summary: Create Backup Codes description: 'Create two factor authentication backup codes for the current user. A two factor authentication method must be enabled for the environment. Otherwise the endpoint will return an error.' tags: - Backup Codes operationId: createBackupCodes responses: '200': $ref: '#/components/responses/Client.ClientWrappedBackupCodes' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '500': $ref: '#/components/responses/ClerkErrors' /v1/me: get: summary: Get User description: Returns all attributes of the current user. tags: - User operationId: getUser responses: '200': $ref: '#/components/responses/Client.ClientWrappedUser' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' patch: summary: Update User description: Update the current user with the given attributes. tags: - User operationId: patchUser requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: username: nullable: true type: string first_name: nullable: true type: string last_name: nullable: true type: string primary_email_address_id: type: string nullable: true primary_phone_number_id: nullable: true type: string primary_web3_wallet_id: nullable: true type: string unsafe_metadata: nullable: true type: string description: A stringified JSON containing the unsafe metadata of the current user. responses: '200': $ref: '#/components/responses/Client.ClientWrappedUser' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' delete: summary: Delete User description: Delete the current user. tags: - User operationId: deleteUser responses: '200': $ref: '#/components/responses/Client.ClientWrappedDeletedObject' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '500': $ref: '#/components/responses/ClerkErrors' /v1/me/metadata: patch: summary: Merge and Update the Current User's Metadata description: 'Update the current user''s metadata attributes by merging existing values with the provided parameters. This endpoint behaves differently than the *Update 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`. Only `unsafe_metadata` can be updated through the Frontend API. `public_metadata` and `private_metadata` must be modified through the Backend API.' tags: - User operationId: patchUserMetadata requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: - unsafe_metadata properties: unsafe_metadata: type: string description: 'A stringified JSON object containing the unsafe metadata patch to merge into the current user''s `unsafe_metadata`. Existing keys are deep-merged; keys at any level with `null` values are removed.' responses: '200': $ref: '#/components/responses/Client.ClientWrappedUser' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/me/tokens: post: description: Create a JWT for the requested user. operationId: createServiceToken tags: - User parameters: - in: query name: _clerk_session_id description: The session_id associated with the requesting user. schema: type: string requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: service: type: string required: - service responses: '200': $ref: '#/components/responses/Token' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/me/profile_image: post: summary: Update Profile Image description: Update the current user's profile image. tags: - User operationId: updateProfileImage requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary application/octet-stream: schema: format: base64 responses: '200': $ref: '#/components/responses/Client.ClientWrappedImage' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' delete: summary: Delete Profile Image description: Remove the current user's profile image. operationId: deleteProfileImage tags: - User responses: '200': $ref: '#/components/responses/Client.ClientWrappedDeletedObject' '401': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' /v1/me/change_password: post: summary: Update Password description: Update the current user's password. operationId: changePassword tags: - User requestBody: content: application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: current_password: type: string nullable: true new_password: type: string sign_out_of_other_sessions: type: boolean nullable: true responses: '200': $ref: '#/components/responses/responses-Client.ClientWrappedUser' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/me/remove_password: post: summary: Delete Password description: Removes the current user's password. operationId: removePassword tags: - User requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: current_password: type: string responses: '200': $ref: '#/components/responses/responses-Client.ClientWrappedUser' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/me/billing/subscription: get: operationId: GetUserMainBillingSubscription x-speakeasy-group: billing x-speakeasy-name-override: getUserMainSubscription tags: - Subscriptions summary: Get User's Main Billing Subscription description: Returns the main billing subscription for the current user. responses: '200': $ref: '#/components/responses/Client.BillingSubscription' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' /v1/me/billing/subscription_items: get: operationId: GetUserBillingSubscriptionItems x-speakeasy-group: billing x-speakeasy-name-override: listUserSubscriptionItems tags: - Subscription Items summary: List User's Subscription Items description: Returns a list of subscription items for the current user. parameters: - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' - $ref: '#/components/parameters/Paginated' responses: '200': $ref: '#/components/responses/Client.BillingSubscriptionItemList' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' /v1/me/billing/subscription_items/{subscriptionItemID}: delete: operationId: DeleteUserBillingSubscriptionItem x-speakeasy-group: billing x-speakeasy-name-override: cancelUserSubscriptionItem tags: - Subscription Items summary: Cancel User's Subscription Item description: Cancels a subscription item for the current user. parameters: - name: subscriptionItemID in: path description: The ID of the subscription item to cancel required: true schema: type: string responses: '200': $ref: '#/components/responses/Client.BillingSubscriptionItem' '204': description: Subscription item canceled successfully '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' /v1/me/billing/payment_methods: get: operationId: GetUserPaymentMethods x-speakeasy-group: billing x-speakeasy-name-override: listUserPaymentMethods tags: - Payment Methods summary: List User Payment Methods description: Returns a list of all payment methods for the current user. parameters: - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' - $ref: '#/components/parameters/Paginated' responses: '200': $ref: '#/components/responses/Client.BillingPaymentMethodList' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' post: operationId: CreateUserPaymentMethod x-speakeasy-group: billing x-speakeasy-name-override: createUserPaymentMethod tags: - Payment Methods summary: Create User Payment Method description: Creates a new payment method for the current user. requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: gateway: type: string description: Payment gateway to use payment_token: type: string nullable: true description: Payment token for the method org_id: type: string nullable: true description: Organization ID (optional) required: - gateway - payment_token responses: '200': $ref: '#/components/responses/Client.BillingPaymentMethod' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '422': $ref: '#/components/responses/UnprocessableEntity' /v1/me/billing/payment_methods/initialize: post: operationId: InitializeUserPaymentMethod x-speakeasy-group: billing x-speakeasy-name-override: initializeUserPaymentMethod tags: - Payment Methods summary: Initialize User Payment Method description: Initializes a payment method setup process for the current user. responses: '200': $ref: '#/components/responses/Client.BillingPaymentMethodInitialize' '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' /v1/me/billing/payment_methods/{paymentMethodID}: delete: operationId: DeleteUserPaymentMethod x-speakeasy-group: billing x-speakeasy-name-override: deleteUserPaymentMethod tags: - Payment Methods summary: Delete User Payment Method description: Deletes a specific payment method for the current user. parameters: - name: paymentMethodID in: path description: The ID of the payment method to delete required: true schema: type: string responses: '200': $ref: '#/components/responses/Client.BillingPaymentMethod' '204': description: Payment method deleted successfully '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' /v1/me/billing/checkouts: post: operationId: CreateUserBillingCheckout x-speakeasy-group: billing x-speakeasy-name-override: createUserCheckout tags: - Checkouts summary: Create Billing Checkout description: Creates a new billing checkout for the current user. requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: plan_id: type: string description: The ID of the plan to checkout plan_period: type: string enum: - month - annual description: The billing period for the plan default: month org_id: type: string nullable: true description: Organization ID (if creating org checkout) payment_method_id: type: string nullable: true description: Payment method ID to use required: - plan_id - plan_period responses: '200': $ref: '#/components/responses/Client.BillingCheckout' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/ClerkErrors' '409': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/UnprocessableEntity' /v1/me/billing/checkouts/{checkoutID}: get: operationId: GetUserBillingCheckout x-speakeasy-group: billing x-speakeasy-name-override: getUserCheckout tags: - Checkouts summary: Get Billing Checkout description: Returns a billing checkout for the current user. parameters: - name: checkoutID in: path description: The ID of the checkout required: true schema: type: string responses: '200': $ref: '#/components/responses/Client.BillingCheckout' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' /v1/me/billing/checkouts/{checkoutID}/confirm: patch: operationId: ConfirmUserBillingCheckout x-speakeasy-group: billing x-speakeasy-name-override: confirmUserCheckout tags: - Checkouts summary: Confirm Billing Checkout description: Confirms a billing checkout for the current user. parameters: - name: checkoutID in: path description: The ID of the checkout to confirm required: true schema: type: string requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: payment_method_id: type: string nullable: true description: The ID of the payment method to use for this checkout gateway: type: string nullable: true description: The payment gateway to use (e.g., stripe) payment_token: type: string nullable: true description: A payment token for processing the payment use_test_card: type: boolean nullable: true description: Whether to use a test card for payment processing responses: '200': $ref: '#/components/responses/Client.BillingCheckout' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' '409': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/UnprocessableEntity' /v1/me/billing/payment_attempts: get: operationId: GetUserPaymentAttempts x-speakeasy-group: billing x-speakeasy-name-override: listUserPaymentAttempts tags: - Payment Attempts summary: List User Payment Attempts description: Returns a list of payment attempts for the current user. parameters: - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' - $ref: '#/components/parameters/Paginated' responses: '200': $ref: '#/components/responses/Client.BillingPaymentAttemptList' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' /v1/me/billing/payment_attempts/{paymentAttemptID}: get: operationId: GetUserPaymentAttempt x-speakeasy-group: billing x-speakeasy-name-override: getUserPaymentAttempt tags: - Payment Attempts summary: Get User Payment Attempt description: Returns details of a specific payment attempt for the current user. parameters: - name: paymentAttemptID in: path description: The ID of the payment attempt to retrieve required: true schema: type: string responses: '200': $ref: '#/components/responses/Client.BillingPaymentAttempt' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' /v1/me/billing/payers/default_payment_method: put: operationId: SetUserDefaultPaymentMethod x-speakeasy-group: billing x-speakeasy-name-override: setUserDefaultPaymentMethod tags: - Payment Methods summary: Set User Default Payment Method description: Sets the default payment method for the current user. responses: '200': $ref: '#/components/responses/Client.BillingPaymentMethod' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '422': $ref: '#/components/responses/UnprocessableEntity' /v1/me/billing/statements: get: operationId: GetUserStatements x-speakeasy-group: billing x-speakeasy-name-override: listUserStatements tags: - Statements summary: List User Statements description: Returns a list of billing statements for the current user. parameters: - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' - $ref: '#/components/parameters/Paginated' responses: '200': $ref: '#/components/responses/Client.BillingStatementList' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' /v1/me/billing/statements/{statementID}: get: operationId: GetUserStatement x-speakeasy-group: billing x-speakeasy-name-override: getUserStatement tags: - Statements summary: Get User Statement description: Returns details of a specific billing statement for the current user. parameters: - name: statementID in: path description: The ID of the statement to retrieve required: true schema: type: string responses: '200': $ref: '#/components/responses/Client.BillingStatement' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' /v1/organizations/{organizationID}/billing/checkouts: post: operationId: CreateOrganizationBillingCheckout x-speakeasy-group: billing x-speakeasy-name-override: createOrganizationCheckout tags: - Checkouts summary: Create Organization Billing Checkout description: Creates a new billing checkout for the organization. parameters: - name: organizationID in: path description: The ID of the organization required: true schema: type: string requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: plan_id: type: string description: The ID of the plan to checkout plan_period: type: string enum: - month - annual description: The billing period for the plan default: month payment_method_id: type: string nullable: true description: Payment method ID to use required: - plan_id - plan_period responses: '200': $ref: '#/components/responses/Client.BillingCheckout' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '409': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/UnprocessableEntity' /v1/organizations/{organizationID}/billing/checkouts/{checkoutID}: get: operationId: GetOrganizationBillingCheckout x-speakeasy-group: billing x-speakeasy-name-override: getOrganizationCheckout tags: - Checkouts summary: Get Organization Billing Checkout description: Returns a billing checkout for the organization. parameters: - name: organizationID in: path description: The ID of the organization required: true schema: type: string - name: checkoutID in: path description: The ID of the checkout required: true schema: type: string responses: '200': $ref: '#/components/responses/Client.BillingCheckout' '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' /v1/organizations/{organizationID}/billing/checkouts/{checkoutID}/confirm: patch: operationId: ConfirmOrganizationBillingCheckout x-speakeasy-group: billing x-speakeasy-name-override: confirmOrganizationCheckout tags: - Checkouts summary: Confirm Organization Billing Checkout description: Confirms a billing checkout for the organization. parameters: - name: organizationID in: path description: The ID of the organization required: true schema: type: string - name: checkoutID in: path description: The ID of the checkout to confirm required: true schema: type: string requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: payment_method_id: type: string nullable: true description: The ID of the payment method to use for this checkout gateway: type: string nullable: true description: The payment gateway to use (e.g., stripe) payment_token: type: string nullable: true description: A payment token for processing the payment use_test_card: type: boolean nullable: true description: Whether to use a test card for payment processing responses: '200': $ref: '#/components/responses/Client.BillingCheckout' '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' /v1/organizations/{organizationID}/billing/payment_methods: get: operationId: GetOrganizationPaymentMethods x-speakeasy-group: billing x-speakeasy-name-override: getOrganizationPaymentMethods tags: - Payment Methods summary: List Organization Payment Methods description: Lists all payment methods for the organization. parameters: - name: organizationID in: path description: The ID of the organization required: true schema: type: string responses: '200': $ref: '#/components/responses/Client.BillingPaymentMethodList' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' post: operationId: CreateOrganizationPaymentMethod x-speakeasy-group: billing x-speakeasy-name-override: createOrganizationPaymentMethod tags: - Payment Methods summary: Create Organization Payment Method description: Creates a new payment method for the organization. parameters: - name: organizationID in: path description: The ID of the organization required: true schema: type: string requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: payment_token: type: string description: The payment token for the payment method gateway: type: string description: The payment gateway to use enum: - stripe required: - payment_token - gateway application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: payment_token: type: string description: The payment token for the payment method gateway: type: string description: The payment gateway to use enum: - stripe required: - payment_token - gateway responses: '200': $ref: '#/components/responses/Client.BillingGenericObject' '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' /v1/organizations/{organizationID}/billing/payment_methods/initialize: post: operationId: InitializeOrganizationPaymentMethod x-speakeasy-group: billing x-speakeasy-name-override: initializeOrganizationPaymentMethod tags: - Payment Methods summary: Initialize Organization Payment Method description: Initializes a payment method for the organization. parameters: - name: organizationID in: path description: The ID of the organization required: true schema: type: string responses: '200': $ref: '#/components/responses/Client.BillingPaymentMethodInitialize' '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' /v1/organizations/{organizationID}/billing/payment_methods/{paymentMethodID}: delete: operationId: DeleteOrganizationPaymentMethod x-speakeasy-group: billing x-speakeasy-name-override: deleteOrganizationPaymentMethod tags: - Payment Methods summary: Delete Organization Payment Method description: Deletes a payment method for the organization. parameters: - name: organizationID in: path description: The ID of the organization required: true schema: type: string - name: paymentMethodID in: path description: The ID of the payment method to delete required: true schema: type: string responses: '200': $ref: '#/components/responses/Client.BillingGenericObject' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' /v1/organizations/{organizationID}/billing/statements: get: operationId: GetOrganizationStatements x-speakeasy-group: billing x-speakeasy-name-override: getOrganizationStatements tags: - Statements summary: List Organization Statements description: Lists all statements for the organization. parameters: - name: organizationID in: path description: The ID of the organization required: true schema: type: string responses: '200': $ref: '#/components/responses/Client.BillingGenericArray' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' /v1/organizations/{organizationID}/billing/statements/{statementID}: get: operationId: GetOrganizationStatement x-speakeasy-group: billing x-speakeasy-name-override: getOrganizationStatement tags: - Statements summary: Get Organization Statement description: Gets a specific statement for the organization. parameters: - name: organizationID in: path description: The ID of the organization required: true schema: type: string - name: statementID in: path description: The ID of the statement to retrieve required: true schema: type: string responses: '200': $ref: '#/components/responses/Client.BillingGenericObject' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' /v1/organizations/{organizationID}/billing/payers/default_payment_method: put: operationId: SetOrganizationDefaultPaymentMethod x-speakeasy-group: billing x-speakeasy-name-override: setOrganizationDefaultPaymentMethod tags: - Payment Methods summary: Set Organization Default Payment Method description: Sets the default payment method for the organization. parameters: - name: organizationID in: path description: The ID of the organization required: true schema: type: string requestBody: required: true content: application/json: schema: type: object additionalProperties: false properties: payment_method_id: type: string description: The ID of the payment method to set as default required: - payment_method_id application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: payment_method_id: type: string description: The ID of the payment method to set as default required: - payment_method_id responses: '200': $ref: '#/components/responses/Client.BillingGenericObject' '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' /v1/organizations/{organizationID}/billing/subscription: get: operationId: GetOrganizationBillingSubscription x-speakeasy-group: billing x-speakeasy-name-override: getOrganizationSubscription tags: - Subscriptions summary: Get Organization's Billing Subscription description: Returns the billing subscription for the organization. parameters: - name: organizationID in: path description: The ID of the organization required: true schema: type: string responses: '200': $ref: '#/components/responses/Client.BillingSubscription' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' /v1/organizations/{organizationID}/billing/subscription_items: get: operationId: GetOrganizationBillingSubscriptionItems x-speakeasy-group: billing x-speakeasy-name-override: listOrganizationSubscriptionItems tags: - Subscription Items summary: List Organization's Subscription Items description: Returns a list of subscription items for the organization. parameters: - name: organizationID in: path description: The ID of the organization required: true schema: type: string responses: '200': $ref: '#/components/responses/Client.BillingSubscriptionItemList' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' /v1/organizations/{organizationID}/billing/subscription_items/{subscriptionItemID}: delete: operationId: DeleteOrganizationBillingSubscriptionItem x-speakeasy-group: billing x-speakeasy-name-override: cancelOrganizationSubscriptionItem tags: - Subscription Items summary: Cancel Organization's Subscription Item description: Cancels a subscription item for the organization. parameters: - name: organizationID in: path description: The ID of the organization required: true schema: type: string - name: subscriptionItemID in: path description: The ID of the subscription item to cancel required: true schema: type: string responses: '200': $ref: '#/components/responses/Client.BillingSubscriptionItem' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' /v1/billing/plans: get: operationId: GetBillingPlanList x-speakeasy-group: billing x-speakeasy-name-override: listPlans tags: - Plans summary: List Billing Plans description: Returns a list of all publicly visible billing plans. parameters: - in: query name: payer_type description: Filter plans by payer type required: false schema: type: string enum: - user - org responses: '200': $ref: '#/components/responses/BillingPlanList' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/UnprocessableEntity' /v1/billing/plans/{planIdOrSlug}: get: operationId: GetBillingPlan x-speakeasy-group: billing x-speakeasy-name-override: getPlan tags: - Plans summary: Get a Billing Plan description: Returns a billing plan by ID or slug. parameters: - name: planIdOrSlug in: path description: The ID or slug of the plan required: true schema: type: string responses: '200': $ref: '#/components/responses/BillingPlan' '400': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ResourceNotFound' '422': $ref: '#/components/responses/UnprocessableEntity' /v1/me/organization_memberships: get: summary: Get Organization Memberships description: Get a list of the organization memberships of the current user. operationId: getOrganizationMemberships tags: - Organizations Memberships parameters: - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' - $ref: '#/components/parameters/Paginated' responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganizationMemberships' '401': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/me/organization_memberships/{organization_id}: delete: summary: Delete Organization Membership description: Delete the membership of the given organization. operationId: deleteOrganizationMemberships tags: - Organizations Memberships parameters: - in: path name: organization_id required: true schema: type: string description: The ID of the organization for which the membership will be deleted responses: '200': $ref: '#/components/responses/Client.ClientWrappedDeletedObject' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/me/organization_invitations: get: summary: Get Current User's Organization Invitations description: Get a list of the organization invitations of the current user. operationId: getUsersOrganizationInvitations tags: - Organizations Memberships parameters: - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' - in: query name: status schema: type: string description: The status of the organization invitations to filter by responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganizationInvitationsUserContext' '401': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/me/organization_invitations/{invitation_id}/accept: post: summary: Accept Organization Invitation description: Accept an organization invitation for the current user. operationId: acceptOrganizationInvitation tags: - Organizations Memberships parameters: - in: path name: invitation_id required: true schema: type: string description: The ID of the organization invitation to accept responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganizationInvitationUserContext' '401': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/me/organization_suggestions: get: summary: Get Organization Suggestions description: Get a list of the organization suggestions of the current user. operationId: getOrganizationSuggestions tags: - Organizations Memberships parameters: - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' - in: query name: status schema: type: string responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganizationSuggestions' '401': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/me/organization_suggestions/{suggestion_id}/accept: post: summary: Accept Organization Suggestion description: Accept an organization suggestion for the current user. operationId: acceptOrganizationSuggestion tags: - Organizations Memberships parameters: - in: path name: suggestion_id required: true schema: type: string description: The ID of the organization suggestion to accept responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganizationSuggestion' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/organizations: post: summary: Create Organization description: Create an organization and add the current user as admin. operationId: createOrganization tags: - Organization requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: name: type: string description: 'The organization name. May not contain URLs or HTML.' slug: type: string description: The organization slug nullable: true responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganization' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/organizations/{organization_id}: get: summary: Get Organization description: Retrieve all properties of an organization that the current user is member of. tags: - Organization operationId: getOrganization parameters: - in: path required: true name: organization_id schema: type: string description: The organization ID. responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganization' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' patch: summary: Update Organization description: 'Update the given properties of an organization. The current user must be an admin in the organization.' operationId: updateOrganization tags: - Organization parameters: - in: path name: organization_id required: true schema: type: string description: The ID of the organization to update requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: name: type: string description: 'The organization name. May not contain URLs or HTML.' nullable: true slug: type: string description: The organization slug nullable: true responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganization' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' delete: summary: Delete Organization description: 'Delete the given organization. The current user must be an admin in the organization.' operationId: deleteOrganization tags: - Organization parameters: - in: path name: organization_id required: true schema: type: string description: The ID of the organization to delete responses: '200': $ref: '#/components/responses/Client.ClientWrappedDeletedObject' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/organizations/{organization_id}/logo: put: summary: Update Organization Logo description: 'Update the organization logo. The current user must be an admin in the organization.' operationId: updateOrganizationLogo tags: - Organization parameters: - in: path name: organization_id required: true schema: type: string description: The ID of the organization. requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary application/octet-stream: schema: format: base64 responses: '200': $ref: '#/components/responses/responses-Client.ClientWrappedOrganization' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '413': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' delete: summary: Delete Organization Logo description: 'Delete the organization logo. The current user must be an admin in the organization.' operationId: deleteOrganizationLogo tags: - Organization parameters: - in: path name: organization_id required: true schema: type: string description: The ID of the organization. responses: '200': $ref: '#/components/responses/Client.ClientWrappedDeletedObject' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' /v1/organizations/{organization_id}/invitations: post: summary: Create Organization Invitation description: 'Create an invitation for a user to join an organization. The current user must have permissions to manage the members of the organization.' operationId: createOrganizationInvitations tags: - Invitations parameters: - in: path name: organization_id required: true schema: type: string description: The ID of the organization for which the invitation will be created. requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: email_address: type: string description: The email address the invitation will be sent to. nullable: false role: type: string description: 'The role that will be assigned to the user after joining. This can be one of the predefined roles (`org:admin`, `org:basic_member`) or a custom role.' nullable: false required: - email_address - role responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganizationInvitation' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' get: summary: Get All Organization Invitations description: 'Retrieve all invitations for an organization. The current user must have permissions to manage the members of the organization.' operationId: getOrganizationInvitations tags: - Invitations parameters: - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' - in: path name: organization_id required: true schema: type: string description: The ID of the organization for which the invitation will be retrieved. - in: query name: status required: false schema: type: string enum: - pending - accepted - revoked - expired - invalid - completed responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganizationInvitations' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/organizations/{organization_id}/invitations/bulk: post: summary: Bulk Create Organization Invitations description: 'Create an invitation for a user to join an organization. The current user must have permissions to manage the members of the organization.' operationId: bulkCreateOrganizationInvitations tags: - Invitations parameters: - in: path name: organization_id required: true schema: type: string description: The ID of the organization for which the invitations will be created. requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: email_address: type: array description: An array of email addresses the invitations will be sent to. nullable: false items: type: string role: type: string description: 'The role that will be assigned to each of the users after joining. This can be one of the predefined roles (`org:admin`, `org:basic_member`) or a custom role.' nullable: false required: - email_address - role responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganizationInvitations' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/organizations/{organization_id}/invitations/pending: get: summary: Get All Pending Organization Invitations deprecated: true description: 'Get a list of pending invitations for an organization. This endpoint is deprecated. Instead use the `/v1/organizations/{organization_id}/invitations` with a query parameter of `status=pending`.' operationId: getAllPendingOrganizationInvitations tags: - Invitations parameters: - in: path name: organization_id required: true schema: type: string description: The ID of the organization for which the invitations will be retrieved. responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganizationInvitations' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/organizations/{organization_id}/invitations/{invitation_id}/revoke: post: summary: Revoke Pending Organization Invitation description: 'Revoke a pending organization invitation. The current user must have permissions to manage the members of the organization.' operationId: revokePendingOrganizationInvitation tags: - Invitations parameters: - in: path name: organization_id required: true schema: type: string description: The ID of the organization for which the invitations will be retrieved. - in: path name: invitation_id required: true schema: type: string description: The ID of the invitation to revoke. responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganizationInvitation' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' /v1/organizations/{organization_id}/memberships: post: summary: Create Organization Membership description: 'Create a new organization membership. The current user must have permissions to manage the members of the organization.' tags: - Members operationId: CreateOrganizationMembership parameters: - in: path required: true name: organization_id schema: type: string description: The organization ID. requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: user_id: type: string description: The ID of the user to be added as a member. nullable: true role: type: string description: 'The role that will be assigned to the user after joining. This can be one of the predefined roles (`org:admin`, `org:basic_member`) or a custom role defined.' nullable: true required: - user_id - role responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganizationMembership' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' get: summary: Get All Organization Members description: 'Retrieve all members of an organization. The current user must have permissions to manage the members of the organization.' operationId: ListOrganizationMemberships tags: - Members parameters: - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' - $ref: '#/components/parameters/Paginated' - in: path required: true name: organization_id schema: type: string description: The organization ID. - in: query required: false name: query schema: type: string description: 'Returns members that match the given query. For possible matches, we check for any of the user''s identifier, usernames, 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.' - in: query required: false name: role description: Filter by roles. This can be one of the predefined roles (`org:admin`, `org:basic_member`) or a custom role defined. schema: type: string responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganizationMemberships' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/organizations/{organization_id}/memberships/{user_id}: patch: summary: Update Organization Membership description: 'Update the attributes of an organization membership for a specific user. The current user must have permissions to manage the members of the organization.' tags: - Members operationId: UpdateOrganizationMembership parameters: - in: path required: true name: organization_id schema: type: string description: The organization ID. - in: path required: true name: user_id schema: type: string description: The member ID. requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: role: type: string description: 'The new role that will be assigned to the member. This can be one of the predefined roles (`org:admin`, `org:basic_member`) or a custom role defined.' nullable: false responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganizationMembership' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' delete: summary: Remove Organization Member description: 'Remove a member from an organization. The current user must have permissions to manage the members of the organization.' operationId: removeOrganizationMember tags: - Members parameters: - in: path required: true name: organization_id schema: type: string description: The organization ID. - in: path required: true name: user_id schema: type: string description: The member ID. responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganizationMembership' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/organizations/{organization_id}/domains: post: summary: Create Organization Domain description: 'Create a new organization domain. The current user must have permissions to manage the domains of the organization.' tags: - Domains operationId: CreateOrganizationDomain parameters: - in: path required: true name: organization_id schema: type: string description: The organization ID. requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: name: type: string description: The name of the new domain nullable: false required: - name responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganizationDomain' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' get: summary: Get All Organization Domains description: 'Retrieves a list of all the domains in an organization The current user must have permissions to manage the domains of the organization.' tags: - Domains operationId: ListOrganizationDomains parameters: - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' - in: path name: organization_id description: The organization ID. required: true schema: type: string - in: query name: verified description: Filter by whether a domain is verified required: false schema: type: boolean - in: query name: enrollment_mode description: Filter by enrollment mode required: false schema: type: string responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganizationDomains' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/organizations/{organization_id}/domains/{domain_id}: get: summary: Get Organization Domain description: 'Retrieve all properties for a domain of an organization. The current user must have permissions to manage the domains of the organization.' tags: - Domains operationId: GetOrganizationDomain parameters: - in: path required: true name: organization_id schema: type: string description: The organization ID. - in: path required: true name: domain_id schema: type: string description: The domain ID. responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganizationDomain' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' delete: summary: Delete Organization Domain description: 'Remove a domain from an organization. The current user must have permissions to manage the domains of the organization.' tags: - Domains operationId: deleteOrganizationDomain parameters: - in: path required: true name: organization_id schema: type: string description: The organization ID. - in: path required: true name: domain_id schema: type: string description: The domain ID. responses: '200': $ref: '#/components/responses/Client.DeletedOrganizationDomain' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/organizations/{organization_id}/domains/{domain_id}/update_enrollment_mode: post: summary: Update Organization Enrollment Mode description: 'Update the enrollment mode for an organization domain. This can be either `automatic_invitation` or `automatic_suggestion`. The current user must have permissions to manage the domains of the organization.' tags: - Domains operationId: UpdateOrganizationDomainEnrollmentMode parameters: - in: path required: true name: organization_id schema: type: string description: The organization ID. - in: path required: true name: domain_id schema: type: string description: The domain ID. requestBody: content: application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: enrollment_mode: type: string nullable: false delete_pending: type: boolean nullable: true required: - enrollment_mode responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganizationDomain' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/organizations/{organization_id}/domains/{domain_id}/prepare_affiliation_verification: post: summary: Prepare Organization Domain Affiliation Verification description: 'Prepares affiliation verification for an organization domain. The current user must have permissions to manage the domains of the organization.' tags: - Domains operationId: prepareOrganizationDomainVerification parameters: - in: path required: true name: organization_id schema: type: string description: The organization ID. - in: path required: true name: domain_id schema: type: string description: The domain ID. requestBody: content: application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: affiliation_email_address: type: string nullable: false required: - affiliation_email_address responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganizationDomain' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/organizations/{organization_id}/domains/{domain_id}/attempt_affiliation_verification: post: summary: Attempt Organization Domain Affiliation Verification description: 'Attempts affiliation verification for organization domain The current user must have permissions to manage the domains of the organization.' tags: - Domains operationId: attemptOrganizationDomainVerification parameters: - in: path required: true name: organization_id schema: type: string description: The organization ID. - in: path required: true name: domain_id schema: type: string description: The domain ID. requestBody: content: application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: code: type: string description: The code that was sent to the email address. nullable: false required: - code responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganizationDomain' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/organizations/{organization_id}/membership_requests: get: summary: Get Organization Membership Requests description: 'Retrieve a list of all membership requests of an organization. The current user must have permissions to manage the members of the organization.' tags: - Membership Requests operationId: listOrganizationMembershipRequests parameters: - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' - in: path required: true name: organization_id schema: type: string description: The organization ID. - in: query required: false name: status schema: type: string responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganizationMembershipRequests' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/organizations/{organization_id}/membership_requests/{request_id}/accept: post: summary: Accept Organization Membership Request description: 'Accepts an organization membership request. The current user must have permissions to manage the members of the organization.' tags: - Membership Requests operationId: acceptOrganizationMembershipRequest parameters: - in: path required: true name: organization_id schema: type: string description: The organization ID. - in: path required: true name: request_id schema: type: string description: The request ID. responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganizationMembershipRequest' '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/organizations/{organization_id}/membership_requests/{request_id}/reject: post: summary: Reject Organization Membership Request description: 'Rejects an organization membership request The current user must have permissions to manage the members of the organization.' tags: - Membership Requests operationId: rejectOrganizationMembershipRequest parameters: - in: path required: true name: organization_id schema: type: string description: The organization ID. - in: path required: true name: request_id schema: type: string description: The request ID. responses: '200': $ref: '#/components/responses/Client.ClientWrappedOrganizationMembershipRequest' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/organizations/{organization_id}/roles: get: summary: Get Organization Roles description: Retrieve a list of all roles of an organization. tags: - Roles operationId: ListOrganizationRoles parameters: - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' - in: path required: true name: organization_id schema: type: string description: The organization ID. responses: '200': $ref: '#/components/responses/Client.ClientWrappedRoles' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' /v1/redirect: get: summary: Redirect to a Validated URL description: Validates and redirects to a safe URL. If no URL is provided, redirects to a default URL. tags: - Redirect operationId: redirectToUrl parameters: - name: redirect_url in: query description: The URL to redirect to (optional). If empty or not provided, redirects to the default URL. required: false allowEmptyValue: true schema: type: string responses: '307': description: Temporary redirect to the validated URL or default URL headers: Location: description: The URL to redirect to schema: type: string format: uri '400': $ref: '#/components/responses/ClerkErrors' '401': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /v1/tickets/accept: get: summary: Accept Ticket description: 'Parses a ticket JWT and performs the necessary actions depending on the ticket''s source type. Depending on the ticket source type, a successful response can either redirect to a new location with the ticket in the query string, or respond directly with a text/html content type for the response body.' operationId: acceptTicket tags: - Sign Ins parameters: - in: query name: ticket required: true schema: type: string description: The JWT with verification information responses: '200': description: Successful response with a plain text or HTML body. '302': description: Redirect '303': description: Redirect '400': $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' /v1/verify: get: summary: Attempt Email Link Verification description: Attempt to verify a verification with email_link strategy. operationId: verify tags: - Sign Ins parameters: - in: query name: token required: true schema: type: string description: The JWT with verification information responses: '200': description: OK '303': description: Redirect '400': $ref: '#/components/responses/ClerkErrors' /v1/waitlist: post: summary: Join Waitlist description: 'Adds an email address to the waitlist. If the email is already on the waitlist, the request will still succeed, returning the ID of the existing waitlist entry.' operationId: joinWaitlist security: - {} - DevBrowser: [] tags: - Waitlist requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object additionalProperties: false properties: email_address: type: string nullable: false required: - email_address responses: '200': $ref: '#/components/responses/Client.WaitlistEntry' '400': $ref: '#/components/responses/ClerkErrors' '403': $ref: '#/components/responses/ClerkErrors' '422': $ref: '#/components/responses/ClerkErrors' /api_keys: 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)_\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 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)_\w{27}$ seconds_until_expiration: type: number nullable: true minimum: 0 exclusiveMinimum: true required: - name - subject additionalProperties: false responses: '201': description: 201 Created 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 /api_keys/{apiKeyID}: 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: description: type: string nullable: true maxLength: 255 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/{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 components: securitySchemes: ProductionBrowser: type: apiKey in: cookie name: __client description: 'The Client API token sent in the form of a browser cookie. Used to authenticate production browser applications.' DevBrowser: type: apiKey in: query name: __dev_session description: 'A Dev Browser API token sent as a query parameter. Used to authenticate only dev instances. To generate a dev instance API token you must first make a request to `/v1/dev_browser` and copy it from the response.' ProductionNativeApp: type: http scheme: bearer description: 'The Client API token sent in the `Authorization` header. Used to authenticate native applications.' ProductionNativeFlag: type: apiKey in: query name: _is_native description: 'If sent and the value is true, it instructs the server to parse the API token from the `Authorization` header. It should always be set to true when using the `Authorization` header authentication strategy.' ClientCredentials: type: http scheme: basic description: HTTP Basic Authentication using Client ID as username and Client Secret as password. schemas: WellKnown.Assetlinks: type: array additionalProperties: false items: type: object properties: relation: type: array items: type: string enum: - delegate_permission/common.handle_all_urls - delegate_permission/common.get_login_creds target: type: object properties: namespace: type: string package_name: type: string sha256_cert_fingerprints: type: array items: type: string 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' 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 WellKnown.AppleAppSiteAssociation: type: object additionalProperties: false properties: webcredentials: type: object additionalProperties: false properties: apps: type: array items: type: string WellKnown.OpenIDConfiguration: type: object additionalProperties: false properties: issuer: type: string authorization_endpoint: type: string token_endpoint: type: string revocation_endpoint: type: string introspection_endpoint: type: string userinfo_endpoint: type: string jwks_uri: type: string scopes_supported: type: array items: type: string response_types_supported: type: array items: type: string response_modes_supported: type: array items: type: string grant_types_supported: type: array items: type: string subject_types_supported: type: array items: type: string id_token_signing_alg_values_supported: type: array items: type: string token_endpoint_auth_methods_supported: type: array items: type: string claims_supported: type: array items: type: string code_challenge_methods_supported: type: array items: type: string backchannel_logout_supported: type: boolean frontchannel_logout_supported: type: boolean end_session_endpoint: type: string required: - issuer - authorization_endpoint - token_endpoint - revocation_endpoint - introspection_endpoint - userinfo_endpoint - jwks_uri - scopes_supported - response_types_supported - response_modes_supported - grant_types_supported - subject_types_supported - id_token_signing_alg_values_supported - token_endpoint_auth_methods_supported - claims_supported - code_challenge_methods_supported - backchannel_logout_supported - frontchannel_logout_supported WellKnown.OAuth2AuthorizationServerMetadata: type: object additionalProperties: false properties: issuer: type: string authorization_endpoint: type: string token_endpoint: type: string revocation_endpoint: type: string jwks_uri: type: string registration_endpoint: type: string response_types_supported: type: array items: type: string grant_types_supported: type: array items: type: string token_endpoint_auth_methods_supported: type: array items: type: string scopes_supported: type: array items: type: string subject_types_supported: type: array items: type: string id_token_signing_alg_values_supported: type: array items: type: string claims_supported: type: array items: type: string service_documentation: type: string ui_locales_supported: type: array items: type: string op_tos_uri: type: string code_challenge_methods_supported: type: array items: type: string required: - issuer - authorization_endpoint - token_endpoint - revocation_endpoint - jwks_uri - response_types_supported - grant_types_supported - token_endpoint_auth_methods_supported - scopes_supported - subject_types_supported - id_token_signing_alg_values_supported - claims_supported - code_challenge_methods_supported OAuth.DynamicClientRegistrationRequest: type: object additionalProperties: false description: 'Client metadata used to register a new OAuth 2.0 client according to RFC 7591. The authorization server assigns this client a unique client identifier.' properties: redirect_uris: type: array items: type: string format: uri description: 'Array of redirection URI strings for use in redirect-based flows such as the authorization code flow. As required by Section 2 of RFC 6749, clients using flows with redirection must register their redirection URI values.' minItems: 1 token_endpoint_auth_method: type: string enum: - client_secret_basic - client_secret_post - none default: client_secret_basic description: 'Indicator of the requested authentication method for the token endpoint. - `client_secret_basic`: HTTP Basic authentication scheme - `client_secret_post`: Client credentials in the request body - `none`: Public client (no authentication) **Note:** In the current implementation, `client_secret_basic` and `client_secret_post` are treated equivalently. Both methods can be used interchangeably at the token endpoint regardless of which one was specified during registration.' client_name: type: string nullable: true maxLength: 256 description: 'Human-readable string name of the client to be presented to the end-user during authorization.' client_uri: type: string format: uri nullable: true maxLength: 1024 description: URL string of a web page providing information about the client. logo_uri: type: string format: uri nullable: true maxLength: 1024 description: 'URL string that references a logo for the client. If present, the Clerk will display this image to the end-user during approval.' scope: type: string nullable: true maxLength: 1024 description: 'Space-separated list of scope values that the client can use when requesting access tokens. If omitted, the client will be registered with the default set of scopes.' required: - redirect_uris OAuth.DynamicClientRegistrationResponse: type: object additionalProperties: false description: 'Client information response after successful registration according to RFC 7591. Contains the client identifier, client secret (for confidential clients), and other client metadata.' properties: client_id: type: string description: 'Unique client identifier string assigned by the authorization server. The client identifier is not a secret; it is exposed to the resource owner and must not be used alone for client authentication.' client_secret: type: string description: 'Client secret string. This value is used by confidential clients to authenticate to the token endpoint. The client secret is omitted for public clients (when token_endpoint_auth_method is "none").' client_id_issued_at: type: integer format: int64 description: 'Time at which the client identifier was issued. The time is represented as the number of seconds from 1970-01-01T00:00:00Z as measured in UTC.' client_secret_expires_at: type: integer format: int64 description: 'Time at which the client secret will expire or 0 if it will not expire. The time is represented as the number of seconds from 1970-01-01T00:00:00Z as measured in UTC.' client_name: type: string description: 'Human-readable string name of the client to be presented to the end-user during authorization.' client_uri: type: string format: uri description: URL string of a web page providing information about the client. logo_uri: type: string format: uri description: URL string that references a logo for the client. redirect_uris: type: array items: type: string format: uri description: Array of redirection URI strings for use in redirect-based flows. grant_types: type: array items: type: string description: 'Array of OAuth 2.0 grant type strings that the client can use at the token endpoint.' response_types: type: array items: type: string description: 'Array of the OAuth 2.0 response type strings that the client can use at the authorization endpoint.' scope: type: string description: 'Space-separated list of scope values that the client can use when requesting access tokens.' token_endpoint_auth_method: type: string enum: - client_secret_basic - client_secret_post - none description: 'Indicator of the requested authentication method for the token endpoint. This value reflects what was specified during registration.' required: - client_id - client_id_issued_at - client_secret_expires_at - client_name - redirect_uris - grant_types - response_types - scope - token_endpoint_auth_method OAuth.DynamicClientRegistrationError: type: object additionalProperties: false description: 'Error response for OAuth 2.0 Dynamic Client Registration according to RFC 7591. The error response uses OAuth 2.0 error response format.' properties: error: type: string enum: - invalid_redirect_uri - invalid_client_metadata - invalid_software_statement - unapproved_software_statement description: 'Single ASCII error code string indicating the error type. - `invalid_redirect_uri`: The value of one or more redirect_uris is invalid - `invalid_client_metadata`: One or more client metadata fields is invalid - `invalid_software_statement`: The software statement presented is invalid - `unapproved_software_statement`: The software statement is not approved' error_description: type: string description: 'Human-readable ASCII text description of the error used for debugging. This is not meant to be displayed to the end-user.' required: - error OAuth.Token: type: object additionalProperties: false description: 'OAuth 2.0 token response according to RFC 6749 Section 5.1. When using OpenID Connect (with `openid` scope), also includes an `id_token` field.' properties: access_token: type: string description: 'The access token issued by the authorization server. This token can be used to access protected resources on behalf of the user.' token_type: type: string description: The type of token issued. Always "Bearer" for OAuth 2.0. example: Bearer expires_in: type: integer description: 'The lifetime in seconds of the access token. For example, the value "86400" denotes that the access token will expire in 1 day from when the response was generated.' example: 86400 refresh_token: type: string description: 'The refresh token which can be used to obtain new access tokens using the same authorization grant. Refresh tokens have a 10 year lifetime.' scope: type: string description: 'Space-separated list of scopes that were granted for this access token. May differ from requested scopes if the authorization server granted a subset.' example: openid email profile id_token: type: string description: 'JWT ID token containing user identity information (OpenID Connect). Only present when the `openid` scope was granted. This is a signed JWT that can be decoded and verified using the instance''s public keys.' required: - access_token - token_type OAuth.UserInfo: type: object additionalProperties: false properties: object: type: string instance_id: type: string user_id: type: string sub: type: string email: type: string nullable: true email_verified: type: boolean nullable: true family_name: type: string nullable: true given_name: type: string nullable: true name: type: string nullable: true username: type: string nullable: true deprecated: true description: Deprecated. Use `preferred_username` instead. preferred_username: type: string nullable: true picture: type: string nullable: true public_metadata: type: object nullable: true additionalProperties: true private_metadata: type: object nullable: true additionalProperties: true unsafe_metadata: type: object nullable: true additionalProperties: true required: - object - instance_id - user_id - sub OAuth.TokenInfo: type: object additionalProperties: false properties: active: type: boolean description: Boolean indicator of whether or not the presented token is currently active. client_id: type: string description: Client identifier for the OAuth 2.0 client that requested this token. nullable: true iat: type: integer description: Integer timestamp, measured in the number of seconds since January 1 1970 UTC, indicating when this token was originally issued, as defined in JWT [RFC7519]. nullable: true scope: type: string description: A JSON string containing a space-separated list of scopes associated with this token, in the format described in Section 3.3 of OAuth 2.0 [RFC6749]. nullable: true sub: type: string description: Subject of the token, as defined in JWT [RFC7519]. nullable: true required: - active OAuth.ScopeWithDescription: type: object additionalProperties: false properties: scope: type: string description: type: string nullable: true requires_consent: type: boolean description: Whether the scope requires user consent required: - scope - requires_consent OAuth.ConsentInfo: type: object additionalProperties: false properties: oauth_application_name: type: string oauth_application_logo_url: type: string nullable: true description: URL to the OAuth application's logo image oauth_application_url: type: string nullable: true description: URL to the OAuth application's website or homepage client_id: type: string scopes: type: array items: $ref: '#/components/schemas/OAuth.ScopeWithDescription' required: - oauth_application_name - client_id - scopes 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 JWT value. ' required: - object - jwt Client.SessionBase: 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: - session status: type: string enum: - active - revoked - ended - expired - removed - abandoned expire_at: type: integer format: int64 abandon_at: type: integer format: int64 last_active_at: type: integer format: int64 last_active_token: type: object nullable: true allOf: - $ref: '#/components/schemas/Token' actor: type: object nullable: true additionalProperties: true required: - id - object - status - expire_at - abandon_at - last_active_at Stubs.Verification.OTP: type: object properties: object: type: string enum: - verification_otp status: type: string enum: - unverified - verified - failed - expired strategy: type: string enum: - phone_code - email_code - reset_password_email_code - reset_password_phone_code attempts: type: integer nullable: true expire_at: type: integer required: - status - strategy - expire_at Stubs.Verification.Invitation: type: object additionalProperties: false properties: object: type: string enum: - verification_invitation status: type: string enum: - verified strategy: type: string enum: - invitation attempts: type: integer nullable: true expire_at: type: integer nullable: true required: - status - strategy Stubs.Verification.Link: type: object properties: object: type: string enum: - verification_email_link status: type: string enum: - unverified - verified - failed - expired - transferable strategy: type: string enum: - email_link attempts: type: integer nullable: true expire_at: type: integer verified_at_client: type: string required: - status - strategy - expire_at Stubs.Verification.Ticket: type: object properties: object: type: string enum: - verification_ticket status: type: string enum: - unverified - verified - expired strategy: type: string enum: - ticket attempts: type: integer nullable: true expire_at: type: integer nullable: true required: - status - strategy Stubs.Verification.Admin: type: object additionalProperties: false properties: object: type: string enum: - verification_admin status: type: string enum: - verified - unverified - failed - expired strategy: type: string enum: - admin attempts: type: integer nullable: true expire_at: type: integer nullable: true required: - status - strategy Stubs.Verification.FromOauth: type: object properties: object: type: string enum: - verification_from_oauth status: type: string enum: - verified - unverified strategy: type: string enum: - from_oauth_apple - from_oauth_google - from_oauth_mock - from_oauth_custom_mock attempts: type: integer nullable: true expire_at: type: integer nullable: true required: - status - strategy Stubs.Verification.SAML: type: object 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: allOf: - $ref: '#/components/schemas/ClerkError' - type: object nullable: true expire_at: type: integer nullable: true attempts: type: integer nullable: true required: - status - strategy Stubs.Identification.Link: type: object additionalProperties: false properties: type: type: string enum: - oauth_apple - oauth_google - oauth_mock - oauth_custom_mock - saml id: type: string required: - type - id Client.EmailAddress: type: object additionalProperties: false properties: id: type: string object: type: string description: 'String representing the object''s type. Objects of the same type share the same value. ' enum: - email_address email_address: type: string reserved: type: boolean verification: type: object nullable: true oneOf: - $ref: '#/components/schemas/Stubs.Verification.OTP' - $ref: '#/components/schemas/Stubs.Verification.Invitation' - $ref: '#/components/schemas/Stubs.Verification.Link' - $ref: '#/components/schemas/Stubs.Verification.Ticket' - $ref: '#/components/schemas/Stubs.Verification.Admin' - $ref: '#/components/schemas/Stubs.Verification.FromOauth' - $ref: '#/components/schemas/Stubs.Verification.SAML' linked_to: type: array items: $ref: '#/components/schemas/Stubs.Identification.Link' 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: - id - object - email_address - verification - linked_to - reserved - created_at - updated_at Client.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: nullable: true type: object oneOf: - $ref: '#/components/schemas/Stubs.Verification.OTP' - $ref: '#/components/schemas/Stubs.Verification.Admin' linked_to: type: array items: $ref: '#/components/schemas/Stubs.Identification.Link' 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: - id - object - phone_number - verification - linked_to - reserved - created_at - updated_at Stubs.Verification.Web3Signature: type: object 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 attempts: type: integer nullable: true expire_at: type: integer nullable: true nonce: type: string nullable: true message: type: string nullable: true required: - status - strategy Client.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: nullable: true type: object oneOf: - $ref: '#/components/schemas/Stubs.Verification.Web3Signature' - $ref: '#/components/schemas/Stubs.Verification.Admin' created_at: type: integer format: int64 description: 'Unix timestamp of creation ' updated_at: type: integer format: int64 description: 'Unix timestamp of creation ' required: - id - object - web3_wallet - verification - created_at - updated_at Stubs.Verification.Passkey: type: object additionalProperties: false properties: object: type: string enum: - verification_passkey status: type: string enum: - unverified - verified - failed - expired strategy: type: string enum: - passkey attempts: type: integer nullable: true expire_at: type: integer nonce: type: string required: - status - strategy - expire_at Client.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. ' nullable: true verification: nullable: true type: object oneOf: - $ref: '#/components/schemas/Stubs.Verification.Passkey' created_at: type: integer format: int64 description: 'Unix timestamp of creation ' updated_at: type: integer format: int64 description: 'Unix timestamp of update ' required: - id - object - name - verification Client.Organization: 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: - organization name: type: string slug: type: string image_url: type: string has_image: type: boolean members_count: type: integer pending_invitations_count: type: integer max_allowed_memberships: type: integer admin_delete_enabled: type: boolean public_metadata: type: object additionalProperties: true created_at: type: integer format: int64 description: 'Unix timestamp of creation. ' updated_at: type: integer format: int64 description: 'Unix timestamp of last update. ' logo_url: type: string nullable: true deprecated: true description: Deprecated. Use `image_url` instead. required: - object - id - name - slug - has_image - max_allowed_memberships - admin_delete_enabled - public_metadata - created_at - updated_at Client.PublicUserData: type: object additionalProperties: false properties: first_name: type: string nullable: true last_name: type: string nullable: true image_url: type: string nullable: true has_image: type: boolean identifier: type: string profile_image_url: type: string nullable: true deprecated: true description: Use `image_url` instead. user_id: type: string nullable: true username: type: string nullable: true banned: type: boolean required: - first_name - last_name - identifier - has_image Client.OrganizationMembership: 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 public_metadata: type: object additionalProperties: true role: type: string role_name: type: string permissions: type: array nullable: true items: 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. organization: $ref: '#/components/schemas/Client.Organization' public_user_data: type: object nullable: true allOf: - $ref: '#/components/schemas/Client.PublicUserData' required: - object - id - public_metadata - role - role_name - permissions - created_at - updated_at - organization 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 Stubs.SAMLConnection.SAMLAccount: 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 allow_organization_account_linking: 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 Client.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: description: The unique ID of the user in the external provider's system type: string nullable: true enterprise_connection_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/Stubs.Verification.SAML' - $ref: '#/components/schemas/Stubs.Verification.Ticket' saml_connection: type: object nullable: true oneOf: - $ref: '#/components/schemas/Stubs.SAMLConnection.SAMLAccount' required: - id - object - provider - active - email_address - first_name - last_name - provider_user_id - public_metadata - saml_connection - verification Client.User: 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: - user username: nullable: true type: string first_name: nullable: true type: string last_name: nullable: true type: string image_url: type: string has_image: type: boolean primary_email_address_id: nullable: true type: string primary_phone_number_id: nullable: true type: string primary_web3_wallet_id: nullable: true type: string password_enabled: type: boolean two_factor_enabled: type: boolean totp_enabled: type: boolean backup_code_enabled: type: boolean email_addresses: type: array items: $ref: '#/components/schemas/Client.EmailAddress' phone_numbers: type: array items: $ref: '#/components/schemas/Client.PhoneNumber' web3_wallets: type: array items: $ref: '#/components/schemas/Client.Web3Wallet' passkeys: type: array items: $ref: '#/components/schemas/Client.Passkey' organization_memberships: type: array items: $ref: '#/components/schemas/Client.OrganizationMembership' external_accounts: type: array items: $ref: '#/components/schemas/ExternalAccountWithVerification' saml_accounts: type: array items: $ref: '#/components/schemas/Client.SAMLAccount' password_last_updated_at: nullable: true type: integer format: int64 description: Unix timestamp of last update. example: 1700690400000 public_metadata: type: object additionalProperties: true private_metadata: type: object additionalProperties: true unsafe_metadata: type: object additionalProperties: true external_id: nullable: true type: string last_sign_in_at: type: integer format: int64 nullable: true description: Unix timestamp of last sign-in. example: 1700690400000 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 the user has been deprovisioned via SCIM and is restricted from signing in. Only present on instances with SCIM enabled. ' 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. ' example: 300 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. ' created_at: type: integer format: int64 description: Unix timestamp of creation. example: 1700690400000 updated_at: type: integer format: int64 description: Unix timestamp of last update. example: 1700690400000 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. last_active_at: type: integer format: int64 nullable: true description: Unix timestamp of the latest session activity, with day precision. example: 1700690400000 mfa_enabled_at: type: integer format: int64 nullable: true description: Unix timestamp at which the user enabled MFA. example: 1700690400000 mfa_disabled_at: type: integer format: int64 nullable: true description: Unix timestamp at which the user disabled MFA. example: 1700690400000 legal_accepted_at: type: integer format: int64 nullable: true description: Unix timestamp at which the user accepted the legal requirements. example: 1700690400000 profile_image_url: type: string deprecated: true description: Deprecated. Use `image_url` instead. 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 Client.Session: allOf: - $ref: '#/components/schemas/Client.SessionBase' - type: object properties: last_active_organization_id: type: string nullable: true user: $ref: '#/components/schemas/Client.User' public_user_data: type: object nullable: true allOf: - $ref: '#/components/schemas/Client.PublicUserData' factor_verification_age: type: array description: Each item represents the minutes that have passed since the last time a first or second factor were verified. items: type: integer created_at: type: integer format: int64 description: Unix timestamp of creation. example: 1700690400000 updated_at: type: integer format: int64 description: Unix timestamp of last update. example: 1700690400000 required: - last_active_organization_id - public_user_data - factor_verification_age - created_at - updated_at Stubs.SignInFactor: type: object additionalProperties: false properties: strategy: type: string enum: - ticket - password - email_code - email_link - phone_code - web3_metamask_signature - web3_base_signature - web3_coinbase_wallet_signature - web3_okx_wallet_signature - web3_solana_signature - totp - backup_code - oauth_apple - oauth_google - oauth_facebook - oauth_hubspot - oauth_github - oauth_mock - oauth_custom_mock - oauth_token_mock - saml - enterprise_sso - reset_password_email_code - reset_password_phone_code - passkey - google_one_tap safe_identifier: type: string enterprise_connection_id: type: string enterprise_connection_name: type: string email_address_id: type: string phone_number_id: type: string web3_wallet_id: type: string passkey_id: type: string primary: type: boolean nullable: true external_verification_redirect_url: nullable: true type: string default: type: boolean required: - strategy Stubs.Verification.Password: type: object additionalProperties: false properties: object: type: string enum: - verification_password status: type: string enum: - unverified - verified strategy: type: string enum: - password attempts: type: integer nullable: true expire_at: type: integer nullable: true required: - status - strategy Stubs.Verification.Oauth: type: object additionalProperties: false properties: object: type: string enum: - verification_oauth status: type: string enum: - unverified - verified - failed - expired - transferable strategy: type: string pattern: ^oauth_(?:(?:token_)|(?:custom_))?[a-z0-9_]+$ external_verification_redirect_url: nullable: true type: string error: type: object nullable: true allOf: - $ref: '#/components/schemas/ClerkError' expire_at: type: integer attempts: type: integer nullable: true required: - status - strategy - expire_at Stubs.Verification.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 required: - status - strategy Stubs.Verification.TOTP: type: object additionalProperties: false properties: object: type: string enum: - verification_totp status: type: string enum: - unverified - verified strategy: type: string enum: - totp attempts: type: integer nullable: true expire_at: type: integer nullable: true required: - status - strategy Stubs.Verification.BackupCode: type: object additionalProperties: false properties: object: type: string enum: - verification_backup_code status: type: string enum: - unverified - verified strategy: type: string enum: - backup_code attempts: type: integer nullable: true expire_at: type: integer nullable: true required: - status - strategy Client.SignIn: 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: - sign_in_attempt id: type: string status: type: string enum: - abandoned - needs_identifier - needs_first_factor - needs_second_factor - needs_client_trust - needs_new_password - needs_protect_check - complete supported_identifiers: type: array description: List of supported identifiers that can be used to sign in. items: type: string enum: - email_address - phone_number - username - web3_wallet - passkey supported_first_factors: type: array nullable: true items: $ref: '#/components/schemas/Stubs.SignInFactor' supported_second_factors: type: array nullable: true items: $ref: '#/components/schemas/Stubs.SignInFactor' first_factor_verification: type: object nullable: true oneOf: - $ref: '#/components/schemas/Stubs.Verification.Password' - $ref: '#/components/schemas/Stubs.Verification.Oauth' - $ref: '#/components/schemas/Stubs.Verification.OTP' - $ref: '#/components/schemas/Stubs.Verification.Link' - $ref: '#/components/schemas/Stubs.Verification.Web3Signature' - $ref: '#/components/schemas/Stubs.Verification.Ticket' - $ref: '#/components/schemas/Stubs.Verification.SAML' - $ref: '#/components/schemas/Stubs.Verification.Passkey' - $ref: '#/components/schemas/Stubs.Verification.GoogleOneTap' second_factor_verification: type: object nullable: true oneOf: - $ref: '#/components/schemas/Stubs.Verification.OTP' - $ref: '#/components/schemas/Stubs.Verification.TOTP' - $ref: '#/components/schemas/Stubs.Verification.Ticket' - $ref: '#/components/schemas/Stubs.Verification.BackupCode' identifier: nullable: true type: string user_data: type: object additionalProperties: false nullable: true properties: first_name: type: string nullable: true last_name: type: string nullable: true image_url: type: string has_image: type: boolean profile_image_url: type: string nullable: true deprecated: true description: Use `image_url` instead. required: - first_name - last_name - has_image created_session_id: nullable: true type: string abandon_at: type: integer format: int64 description: Unix timestamp at which the sign in will be abandoned. example: 1700690400000 client_trust_state: type: string nullable: true description: 'The trust state of the client for this sign-in attempt. - `pending`: The identifier has not been set yet. - `new`: The user has not had a session on this client before. - `known`: The user has had a session on this client before. ' enum: - pending - new - known required: - object - id - status - supported_identifiers - supported_first_factors - supported_second_factors - first_factor_verification - second_factor_verification - identifier - user_data - created_session_id - abandon_at Stubs.SignUpVerification.AdditionalFields: type: object properties: next_action: type: string enum: - needs_prepare - needs_attempt - '' supported_strategies: type: array items: type: string required: - next_action - supported_strategies Client.SignUp.Verifications: type: object properties: email_address: type: object nullable: true oneOf: - allOf: - $ref: '#/components/schemas/Stubs.Verification.OTP' - $ref: '#/components/schemas/Stubs.SignUpVerification.AdditionalFields' - allOf: - $ref: '#/components/schemas/Stubs.Verification.Link' - $ref: '#/components/schemas/Stubs.SignUpVerification.AdditionalFields' - allOf: - $ref: '#/components/schemas/Stubs.Verification.Ticket' - $ref: '#/components/schemas/Stubs.SignUpVerification.AdditionalFields' - allOf: - $ref: '#/components/schemas/Stubs.Verification.FromOauth' - $ref: '#/components/schemas/Stubs.SignUpVerification.AdditionalFields' - allOf: - $ref: '#/components/schemas/Stubs.Verification.SAML' - $ref: '#/components/schemas/Stubs.SignUpVerification.AdditionalFields' phone_number: type: object nullable: true allOf: - $ref: '#/components/schemas/Stubs.Verification.OTP' - $ref: '#/components/schemas/Stubs.SignUpVerification.AdditionalFields' web3_wallet: type: object nullable: true allOf: - $ref: '#/components/schemas/Stubs.Verification.Web3Signature' - $ref: '#/components/schemas/Stubs.SignUpVerification.AdditionalFields' external_account: type: object nullable: true oneOf: - $ref: '#/components/schemas/Stubs.Verification.Oauth' - $ref: '#/components/schemas/Stubs.Verification.SAML' - $ref: '#/components/schemas/Stubs.Verification.Ticket' - $ref: '#/components/schemas/Stubs.Verification.GoogleOneTap' required: - email_address - phone_number - web3_wallet - external_account Client.SignUp: type: object properties: object: type: string description: 'String representing the object''s type. Objects of the same type share the same value. ' enum: - sign_up_attempt id: type: string description: Unique identifier for this sign up. status: type: string enum: - abandoned - missing_requirements - complete required_fields: type: array items: type: string description: 'List of required fields which need to be supplied to the current sign-up. These fields are mandatory in order for the sign-up to satisfy the attached registration policy and be marked as complete. ' optional_fields: type: array items: type: string description: 'List of optional fields which can be supplied to the current sign-up. These fields are not required and their absence does not prevent the sign-up to be marked as complete. ' missing_fields: type: array items: type: string description: 'List of the missing fields which still need to be supplied to the current sign-up. These fields are mandatory in order for the sign-up to satisfy the attached registration policy and be marked as complete. ' unverified_fields: type: array items: type: string description: 'List of fields which are already supplied to the current sign-up but they need to be verified. Example of such fields are email addresses and phone numbers. ' verifications: description: 'Group for all available verifications. ' allOf: - $ref: '#/components/schemas/Client.SignUp.Verifications' 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: description: 'Custom JSON that callers can use to store arbitrary values that make sense in the context of the current sign up. ' type: object additionalProperties: true public_metadata: description: 'Custom JSON that can be used to store arbitrary values which will end up in the user''s public metadata. This field can only be populated from the application''s BE. At this point, this can be done via invitations. ' 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 sign up will be abandoned. example: 1700690400000 legal_accepted_at: type: integer format: int64 nullable: true description: Unix timestamp at which the user accepted the legal requirements. example: 1700690400000 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 Client.Client: type: object nullable: true 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. sessions: type: array items: $ref: '#/components/schemas/Client.Session' sign_in: type: object nullable: true allOf: - $ref: '#/components/schemas/Client.SignIn' sign_up: type: object nullable: true allOf: - $ref: '#/components/schemas/Client.SignUp' 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. ' cookie_expires_at: nullable: true type: integer format: int64 description: Unix timestamp of the cookie expiration. captcha_bypass: type: boolean description: Whether the client can bypass CAPTCHA. 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 - sessions - sign_in - sign_up - last_active_session_id - last_authentication_strategy - cookie_expires_at - captcha_bypass - created_at - updated_at Client.AccountPortal: type: object additionalProperties: false properties: object: type: string enum: - account_portal allowed: type: boolean enabled: type: boolean internal_linking: type: boolean after_sign_in_url: type: string after_sign_up_url: type: string after_join_waitlist_url: type: string after_create_organization_url: type: string after_leave_organization_url: type: string logo_link_url: type: string customization: type: object properties: appearance: type: string enum: - auto - dark - light nullable: true background_color_dark: type: string nullable: true background_color_light: type: string nullable: true primary_color_dark: type: string nullable: true primary_color_light: type: string nullable: true required: - appearance - background_color_dark - background_color_light - primary_color_dark - primary_color_light required: - object - allowed - enabled - internal_linking - after_sign_in_url - after_sign_up_url - after_join_waitlist_url - after_create_organization_url - after_leave_organization_url - logo_link_url - customization Client.AuthConfig: type: object additionalProperties: false properties: object: type: string enum: - auth_config id: type: string first_name: type: string enum: - 'on' - 'off' - required last_name: type: string enum: - 'on' - 'off' - required email_address: type: string enum: - 'on' - 'off' - required phone_number: type: string enum: - 'on' - 'off' - required username: type: string enum: - 'on' - 'off' - required password: type: string enum: - 'on' - 'off' - required identification_requirements: type: array items: type: array items: type: string identification_strategies: type: array items: type: string first_factors: type: array items: type: string second_factors: type: array items: type: string email_address_verification_strategies: type: array items: type: string single_session_mode: type: boolean enhanced_email_deliverability: type: boolean test_mode: type: boolean cookieless_dev: type: boolean description: Please use `url_based_session_syncing` instead deprecated: true url_based_session_syncing: type: boolean claimed_at: type: integer format: int64 nullable: true reverification: type: boolean required: - object - id - first_name - last_name - email_address - phone_number - username - password - identification_requirements - identification_strategies - first_factors - second_factors - email_address_verification_strategies - single_session_mode - enhanced_email_deliverability - test_mode - url_based_session_syncing - claimed_at - reverification Image: type: object properties: object: type: string description: The object type. Always "image". id: type: string description: Unique identifier for the image. name: type: string description: The file name of the uploaded image. public_url: type: string description: The publicly accessible URL for the image. Client.DisplayConfig: type: object additionalProperties: false properties: object: type: string enum: - display_config id: type: string instance_environment_type: type: string enum: - production - development - staging application_name: type: string theme: type: object preferred_sign_in_strategy: type: string enum: - password - otp logo_image_url: nullable: true type: string favicon_image_url: nullable: true type: string home_url: type: string sign_in_url: type: string sign_up_url: type: string user_profile_url: type: string waitlist_url: type: string after_sign_in_url: type: string after_sign_up_url: type: string after_sign_out_one_url: type: string after_sign_out_all_url: type: string after_switch_session_url: type: string after_join_waitlist_url: type: string organization_profile_url: type: string create_organization_url: type: string after_leave_organization_url: type: string after_create_organization_url: type: string logo_link_url: type: string support_email: type: string nullable: true branded: type: boolean experimental_force_oauth_first: type: boolean clerk_js_version: type: string nullable: true show_devmode_warning: type: boolean google_one_tap_client_id: type: string nullable: true help_url: type: string nullable: true privacy_policy_url: type: string nullable: true terms_url: type: string nullable: true logo_url: nullable: true type: string deprecated: true description: Use `logo_image_url` instead favicon_url: nullable: true type: string deprecated: true description: Use `favicon_image_url` instead logo_image: type: object nullable: true allOf: - $ref: '#/components/schemas/Image' deprecated: true description: Use `logo_image_url` instead favicon_image: type: object nullable: true allOf: - $ref: '#/components/schemas/Image' deprecated: true description: Use `favicon_image_url` instead captcha_public_key: type: string nullable: true captcha_widget_type: type: string nullable: true enum: - smart - invisible captcha_public_key_invisible: type: string nullable: true captcha_provider: type: string nullable: true enum: - turnstile captcha_oauth_bypass: type: array items: type: string captcha_heartbeat: type: boolean nullable: true required: - object - id - instance_environment_type - application_name - theme - preferred_sign_in_strategy - home_url - sign_in_url - sign_up_url - user_profile_url - waitlist_url - after_sign_in_url - after_sign_up_url - after_sign_out_one_url - after_sign_out_all_url - after_switch_session_url - after_join_waitlist_url - organization_profile_url - create_organization_url - after_leave_organization_url - after_create_organization_url - logo_link_url - support_email - branded - experimental_force_oauth_first - clerk_js_version - show_devmode_warning - google_one_tap_client_id - help_url - privacy_policy_url - terms_url - logo_url - favicon_url - logo_image - favicon_image - captcha_public_key - captcha_widget_type - captcha_public_key_invisible - captcha_provider - captcha_oauth_bypass UserSettings.Attribute: type: object additionalProperties: false properties: enabled: type: boolean required: type: boolean used_for_first_factor: type: boolean first_factors: type: array items: type: string used_for_second_factor: type: boolean second_factors: type: array items: type: string verifications: type: array items: type: string verify_at_sign_up: type: boolean immutable: type: boolean required: - enabled - required - used_for_first_factor - first_factors - used_for_second_factor - second_factors - verifications - verify_at_sign_up - immutable UserSettings.Attributes: type: object additionalProperties: false properties: email_address: $ref: '#/components/schemas/UserSettings.Attribute' phone_number: $ref: '#/components/schemas/UserSettings.Attribute' username: $ref: '#/components/schemas/UserSettings.Attribute' web3_wallet: $ref: '#/components/schemas/UserSettings.Attribute' first_name: $ref: '#/components/schemas/UserSettings.Attribute' last_name: $ref: '#/components/schemas/UserSettings.Attribute' password: $ref: '#/components/schemas/UserSettings.Attribute' authenticator_app: $ref: '#/components/schemas/UserSettings.Attribute' ticket: $ref: '#/components/schemas/UserSettings.Attribute' backup_code: $ref: '#/components/schemas/UserSettings.Attribute' passkey: $ref: '#/components/schemas/UserSettings.Attribute' required: - email_address - phone_number - username - web3_wallet - first_name - last_name - password - authenticator_app - ticket - backup_code - passkey UserSettings.Social: type: object additionalProperties: false properties: enabled: type: boolean required: type: boolean authenticatable: type: boolean block_email_subaddresses: type: boolean strategy: type: string not_selectable: type: boolean deprecated: type: boolean name: type: string description: A human readable name for the social provider. example: Google logo_url: type: string nullable: true description: A URL pointing to the logo of the social provider. example: https://img.clerk.com/static/google.png required: - enabled - required - authenticatable - block_email_subaddresses - strategy - not_selectable - deprecated UserSettings.Socials: type: object additionalProperties: false properties: oauth_apple: $ref: '#/components/schemas/UserSettings.Social' oauth_atlassian: $ref: '#/components/schemas/UserSettings.Social' oauth_bitbucket: $ref: '#/components/schemas/UserSettings.Social' oauth_box: $ref: '#/components/schemas/UserSettings.Social' oauth_coinbase: $ref: '#/components/schemas/UserSettings.Social' oauth_custom_mock: $ref: '#/components/schemas/UserSettings.Social' oauth_discord: $ref: '#/components/schemas/UserSettings.Social' oauth_dropbox: $ref: '#/components/schemas/UserSettings.Social' oauth_enstall: $ref: '#/components/schemas/UserSettings.Social' oauth_expressen: $ref: '#/components/schemas/UserSettings.Social' oauth_facebook: $ref: '#/components/schemas/UserSettings.Social' oauth_github: $ref: '#/components/schemas/UserSettings.Social' oauth_gitlab: $ref: '#/components/schemas/UserSettings.Social' oauth_google: $ref: '#/components/schemas/UserSettings.Social' oauth_hubspot: $ref: '#/components/schemas/UserSettings.Social' oauth_huggingface: $ref: '#/components/schemas/UserSettings.Social' oauth_instagram: $ref: '#/components/schemas/UserSettings.Social' oauth_line: $ref: '#/components/schemas/UserSettings.Social' oauth_linear: $ref: '#/components/schemas/UserSettings.Social' oauth_linkedin: $ref: '#/components/schemas/UserSettings.Social' oauth_linkedin_oidc: $ref: '#/components/schemas/UserSettings.Social' oauth_microsoft: $ref: '#/components/schemas/UserSettings.Social' oauth_mock: $ref: '#/components/schemas/UserSettings.Social' oauth_notion: $ref: '#/components/schemas/UserSettings.Social' oauth_slack: $ref: '#/components/schemas/UserSettings.Social' oauth_spotify: $ref: '#/components/schemas/UserSettings.Social' oauth_tiktok: $ref: '#/components/schemas/UserSettings.Social' oauth_twitch: $ref: '#/components/schemas/UserSettings.Social' oauth_twitter: $ref: '#/components/schemas/UserSettings.Social' oauth_x: $ref: '#/components/schemas/UserSettings.Social' oauth_xero: $ref: '#/components/schemas/UserSettings.Social' UserSettings.EnterpriseSSO: type: object additionalProperties: false properties: enabled: type: boolean self_serve_sso: type: boolean description: When true, end-users may manage enterprise connections for this environment. required: - enabled UserSettings.SignIn: type: object additionalProperties: false properties: second_factor: type: object additionalProperties: false properties: required: type: boolean required: - required required: - second_factor UserSettings.SignUp: type: object additionalProperties: false properties: captcha_enabled: type: boolean captcha_widget_type: type: string enum: - smart - invisible custom_action_required: type: boolean progressive: type: boolean mode: type: string enum: - public - restricted - waitlist legal_consent_enabled: type: boolean required: - captcha_enabled - captcha_widget_type - custom_action_required - progressive - mode - legal_consent_enabled UserSettings.Restrictions.Enabled: type: object additionalProperties: false properties: enabled: type: boolean required: - enabled UserSettings.Restrictions: type: object additionalProperties: false properties: allowlist: $ref: '#/components/schemas/UserSettings.Restrictions.Enabled' blocklist: $ref: '#/components/schemas/UserSettings.Restrictions.Enabled' allowlist_blocklist_disabled_on_sign_in: $ref: '#/components/schemas/UserSettings.Restrictions.Enabled' block_email_subaddresses: $ref: '#/components/schemas/UserSettings.Restrictions.Enabled' block_disposable_email_domains: $ref: '#/components/schemas/UserSettings.Restrictions.Enabled' required: - allowlist - blocklist - allowlist_blocklist_disabled_on_sign_in - block_email_subaddresses - block_disposable_email_domains UserSettings.PasswordSettings: type: object additionalProperties: false properties: disable_hibp: type: boolean min_length: type: integer max_length: type: integer require_special_char: type: boolean description: 'Denotes whether given passwords should contain at least one of the following special characters: #%$&_! ' require_numbers: type: boolean require_uppercase: type: boolean require_lowercase: type: boolean show_zxcvbn: type: boolean min_zxcvbn_strength: type: integer minimum: 0 maximum: 4 enforce_hibp_on_sign_in: type: boolean allowed_special_characters: type: string required: - disable_hibp - min_length - max_length - require_special_char - require_numbers - require_uppercase - require_lowercase - show_zxcvbn - min_zxcvbn_strength - enforce_hibp_on_sign_in - allowed_special_characters UserSettings.UsernameSettings: type: object additionalProperties: false properties: min_length: type: integer nullable: true max_length: type: integer nullable: true allow_extended_special_characters: type: boolean allow_numeric_usernames: description: Whether usernames may contain only digits. When enabled, phone-number inputs must be provided in explicit E.164 format. type: boolean required: - min_length - max_length - allow_extended_special_characters - allow_numeric_usernames UserSettings.ActionsSettings: type: object additionalProperties: false properties: delete_self: type: boolean create_organization: type: boolean create_organizations_limit: type: boolean nullable: true required: - delete_self - create_organization - create_organizations_limit UserSettings.AttackProtectionSettings.UserLockout: type: object additionalProperties: false properties: enabled: type: boolean max_attempts: type: integer duration_in_minutes: type: integer required: - enabled - max_attempts - duration_in_minutes UserSettings.AttackProtectionSettings.PII: type: object additionalProperties: false properties: enabled: type: boolean required: - enabled UserSettings.AttackProtectionSettings.EmailLink: type: object additionalProperties: false properties: require_same_client: type: boolean required: - require_same_client UserSettings.AttackProtectionSettings.EnumerationProtection: type: object additionalProperties: false properties: enabled: type: boolean required: - enabled UserSettings.AttackProtectionSettings: type: object additionalProperties: false properties: user_lockout: $ref: '#/components/schemas/UserSettings.AttackProtectionSettings.UserLockout' pii: $ref: '#/components/schemas/UserSettings.AttackProtectionSettings.PII' email_link: $ref: '#/components/schemas/UserSettings.AttackProtectionSettings.EmailLink' enumeration_protection: $ref: '#/components/schemas/UserSettings.AttackProtectionSettings.EnumerationProtection' required: - user_lockout - pii - email_link - enumeration_protection UserSettings.PasskeySettings: type: object additionalProperties: false properties: allow_autofill: type: boolean description: Passkey UI will be shown when user interacts with the text input. default: true show_sign_in_button: type: boolean description: Passkey UI will be shown when user clicks on a button. default: true required: - allow_autofill - show_sign_in_button Client.UserSettings: type: object additionalProperties: false properties: attributes: $ref: '#/components/schemas/UserSettings.Attributes' social: $ref: '#/components/schemas/UserSettings.Socials' saml: $ref: '#/components/schemas/UserSettings.EnterpriseSSO' enterprise_sso: $ref: '#/components/schemas/UserSettings.EnterpriseSSO' sign_in: $ref: '#/components/schemas/UserSettings.SignIn' sign_up: $ref: '#/components/schemas/UserSettings.SignUp' restrictions: $ref: '#/components/schemas/UserSettings.Restrictions' password_settings: $ref: '#/components/schemas/UserSettings.PasswordSettings' username_settings: $ref: '#/components/schemas/UserSettings.UsernameSettings' actions: $ref: '#/components/schemas/UserSettings.ActionsSettings' attack_protection: $ref: '#/components/schemas/UserSettings.AttackProtectionSettings' passkey_settings: $ref: '#/components/schemas/UserSettings.PasskeySettings' required: - attributes - social - saml - enterprise_sso - sign_in - sign_up - restrictions - password_settings - username_settings - actions - attack_protection - passkey_settings OrganizationSettings.ActionsSettings: type: object additionalProperties: false properties: admin_delete: type: boolean required: - admin_delete OrganizationSettings.DomainsSettings: type: object additionalProperties: false properties: enabled: type: boolean enrollment_modes: type: array items: type: string enum: - manual_invitation - automatic_invitation - automatic_suggestion default_role: type: string description: The role key that it will be used in order to create an organization invitation or suggestion. required: - enabled - enrollment_modes - default_role OrganizationSettings.SlugSettings: type: object additionalProperties: false properties: disabled: type: boolean required: - disabled Client.OrganizationSettings: type: object additionalProperties: false properties: enabled: type: boolean max_allowed_memberships: type: integer actions: $ref: '#/components/schemas/OrganizationSettings.ActionsSettings' domains: $ref: '#/components/schemas/OrganizationSettings.DomainsSettings' slug: $ref: '#/components/schemas/OrganizationSettings.SlugSettings' creator_role: type: string description: The role key that a user will be assigned after creating an organization. required: - enabled - max_allowed_memberships - actions - domains - creator_role FraudSettings.NativeSettings: type: object additionalProperties: false properties: device_attestation_mode: type: string enum: - disabled - onboarding - enforced required: - device_attestation_mode Client.FraudSettings: 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: - fraud_settings native: $ref: '#/components/schemas/FraudSettings.NativeSettings' required: - native Client.CommerceSettings: type: object additionalProperties: false properties: billing: type: object additionalProperties: false properties: stripe_publishable_key: type: string nullable: true free_trial_requires_payment_method: type: boolean user: type: object additionalProperties: false properties: enabled: type: boolean has_paid_plans: type: boolean organization: type: object additionalProperties: false properties: enabled: type: boolean has_paid_plans: type: boolean required: - billing Client.ApiKeysSettings: type: object additionalProperties: false properties: enabled: type: boolean description: Indicates whether the API Keys feature is enabled. user_api_keys_enabled: type: boolean description: Indicates whether User API Keys are enabled. orgs_api_keys_enabled: type: boolean description: Indicates whether Organization API Keys are enabled. required: - enabled - user_api_keys_enabled - orgs_api_keys_enabled Client.ProtectConfig.Loader: type: object additionalProperties: false description: Configuration for the Clerk Protect loader. properties: rollout: type: number format: float description: rollout percentage (between 0.0 and 1.0) minimum: 0 maximum: 1 type: type: string target: type: string attributes: type: object additionalProperties: type: string textContent: type: string Client.ProtectConfig: type: object additionalProperties: false properties: loaders: type: array items: $ref: '#/components/schemas/Client.ProtectConfig.Loader' Client.Environment: type: object additionalProperties: false properties: auth_config: $ref: '#/components/schemas/Client.AuthConfig' display_config: $ref: '#/components/schemas/Client.DisplayConfig' user_settings: $ref: '#/components/schemas/Client.UserSettings' organization_settings: $ref: '#/components/schemas/Client.OrganizationSettings' fraud_settings: $ref: '#/components/schemas/Client.FraudSettings' commerce_settings: $ref: '#/components/schemas/Client.CommerceSettings' api_keys_settings: $ref: '#/components/schemas/Client.ApiKeysSettings' protect_config: $ref: '#/components/schemas/Client.ProtectConfig' client_debug_mode: type: boolean partitioned_cookies: type: boolean maintenance_mode: type: boolean Client.SessionTask: type: object properties: key: type: string required: - key schemas-Client.SessionBase: 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: - session status: type: string enum: - active - revoked - ended - expired - removed - abandoned - pending expire_at: type: integer format: int64 abandon_at: type: integer format: int64 last_active_at: type: integer format: int64 last_active_token: type: object nullable: true allOf: - $ref: '#/components/schemas/Token' actor: type: object nullable: true additionalProperties: true tasks: type: array nullable: true items: $ref: '#/components/schemas/Client.SessionTask' required: - id - object - status - expire_at - abandon_at - last_active_at schemas-Client.Session: allOf: - $ref: '#/components/schemas/schemas-Client.SessionBase' - type: object properties: last_active_organization_id: type: string nullable: true user: $ref: '#/components/schemas/Client.User' public_user_data: type: object nullable: true allOf: - $ref: '#/components/schemas/Client.PublicUserData' factor_verification_age: type: array description: Each item represents the minutes that have passed since the last time a first or second factor were verified. items: type: integer created_at: type: integer format: int64 description: Unix timestamp of creation. example: 1700690400000 updated_at: type: integer format: int64 description: Unix timestamp of last update. example: 1700690400000 required: - last_active_organization_id - public_user_data - factor_verification_age - created_at - updated_at schemas-Client.SignIn: 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: - sign_in_attempt id: type: string status: type: string enum: - abandoned - needs_identifier - needs_first_factor - needs_second_factor - needs_client_trust - needs_new_password - needs_protect_check - complete supported_identifiers: type: array description: List of supported identifiers that can be used to sign in. items: type: string enum: - email_address - phone_number - username - web3_wallet - passkey supported_first_factors: type: array nullable: true items: $ref: '#/components/schemas/Stubs.SignInFactor' supported_second_factors: type: array nullable: true items: $ref: '#/components/schemas/Stubs.SignInFactor' first_factor_verification: type: object nullable: true oneOf: - $ref: '#/components/schemas/Stubs.Verification.Password' - $ref: '#/components/schemas/Stubs.Verification.Oauth' - $ref: '#/components/schemas/Stubs.Verification.OTP' - $ref: '#/components/schemas/Stubs.Verification.Link' - $ref: '#/components/schemas/Stubs.Verification.Web3Signature' - $ref: '#/components/schemas/Stubs.Verification.Ticket' - $ref: '#/components/schemas/Stubs.Verification.SAML' - $ref: '#/components/schemas/Stubs.Verification.Passkey' - $ref: '#/components/schemas/Stubs.Verification.GoogleOneTap' second_factor_verification: type: object nullable: true oneOf: - $ref: '#/components/schemas/Stubs.Verification.OTP' - $ref: '#/components/schemas/Stubs.Verification.Link' - $ref: '#/components/schemas/Stubs.Verification.TOTP' - $ref: '#/components/schemas/Stubs.Verification.Ticket' - $ref: '#/components/schemas/Stubs.Verification.BackupCode' identifier: nullable: true type: string user_data: type: object additionalProperties: false nullable: true properties: first_name: type: string nullable: true last_name: type: string nullable: true image_url: type: string has_image: type: boolean profile_image_url: type: string nullable: true deprecated: true description: Use `image_url` instead. required: - first_name - last_name - has_image created_session_id: nullable: true type: string abandon_at: type: integer format: int64 description: Unix timestamp at which the sign in will be abandoned. example: 1700690400000 client_trust_state: type: string nullable: true description: 'The trust state of the client for this sign-in attempt. - `pending`: The identifier has not been set yet. - `new`: The user has not had a session on this client before. - `known`: The user has had a session on this client before. ' enum: - pending - new - known required: - object - id - status - supported_identifiers - supported_first_factors - supported_second_factors - first_factor_verification - second_factor_verification - identifier - user_data - created_session_id - abandon_at schemas-Client.Client: type: object nullable: true 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. sessions: type: array items: $ref: '#/components/schemas/schemas-Client.Session' sign_in: type: object nullable: true allOf: - $ref: '#/components/schemas/schemas-Client.SignIn' sign_up: type: object nullable: true allOf: - $ref: '#/components/schemas/Client.SignUp' 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. ' cookie_expires_at: nullable: true type: integer format: int64 description: Unix timestamp of the cookie expiration. captcha_bypass: type: boolean description: Whether the client can bypass CAPTCHA. 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 - sessions - sign_in - sign_up - last_active_session_id - last_authentication_strategy - cookie_expires_at - captcha_bypass - created_at - updated_at Client.ClientWrappedClient: type: object additionalProperties: false properties: response: type: object nullable: true allOf: - $ref: '#/components/schemas/schemas-Client.Client' client: type: object nullable: true allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.DeleteSession: type: object additionalProperties: false properties: response: type: object nullable: true allOf: - $ref: '#/components/schemas/schemas-Client.Client' client: type: object nullable: true required: - response - client Client.ClientWrappedSignIn: type: object additionalProperties: false properties: response: $ref: '#/components/schemas/schemas-Client.SignIn' client: $ref: '#/components/schemas/schemas-Client.Client' required: - response - client schemas-Client.ClientWrappedSignIn: type: object additionalProperties: false properties: response: $ref: '#/components/schemas/Client.SignIn' client: $ref: '#/components/schemas/Client.Client' required: - response - client Client.ClientWrappedSignUp: type: object additionalProperties: false properties: response: $ref: '#/components/schemas/Client.SignUp' client: $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.ClientWrappedSession: type: object additionalProperties: false properties: response: $ref: '#/components/schemas/schemas-Client.Session' client: $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.TouchWrappedSession: type: object additionalProperties: false properties: response: $ref: '#/components/schemas/schemas-Client.Session' client: allOf: - $ref: '#/components/schemas/schemas-Client.Client' nullable: true required: - response - client Client.SessionActivity: type: object 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 Client.ActiveSession: allOf: - $ref: '#/components/schemas/schemas-Client.SessionBase' - type: object properties: latest_activity: $ref: '#/components/schemas/Client.SessionActivity' Client.ActiveSessions: type: array items: $ref: '#/components/schemas/Client.ActiveSession' Client.SessionReverification: type: object properties: object: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - session_reverification level: type: string description: The level used for the session reverification status: type: string enum: - needs_first_factor - needs_second_factor - complete supported_first_factors: type: array nullable: true items: $ref: '#/components/schemas/Stubs.SignInFactor' supported_second_factors: type: array nullable: true items: $ref: '#/components/schemas/Stubs.SignInFactor' first_factor_verification: type: object nullable: true oneOf: - $ref: '#/components/schemas/Stubs.Verification.Password' - $ref: '#/components/schemas/Stubs.Verification.OTP' - $ref: '#/components/schemas/Stubs.Verification.Passkey' - $ref: '#/components/schemas/Stubs.Verification.SAML' second_factor_verification: type: object nullable: true oneOf: - $ref: '#/components/schemas/Stubs.Verification.OTP' - $ref: '#/components/schemas/Stubs.Verification.TOTP' - $ref: '#/components/schemas/Stubs.Verification.BackupCode' session: type: object oneOf: - $ref: '#/components/schemas/schemas-Client.SessionBase' required: - object - level - status - supported_first_factors - supported_second_factors - first_factor_verification - second_factor_verification - session Client.ClientWrappedSessionReverification: type: object properties: response: $ref: '#/components/schemas/Client.SessionReverification' client: $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Server.Sessions: type: array items: $ref: '#/components/schemas/schemas-Client.Session' Server.UserEmailAddresses: type: array items: $ref: '#/components/schemas/Client.EmailAddress' Client.ClientWrappedEmailAddress: type: object additionalProperties: false properties: response: type: object nullable: false allOf: - $ref: '#/components/schemas/Client.EmailAddress' client: type: object nullable: false allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.DeletedObject: type: object additionalProperties: false properties: id: type: string slug: type: string object: type: string deleted: type: boolean required: - object - deleted Client.ClientWrappedDeletedObject: type: object additionalProperties: false properties: response: $ref: '#/components/schemas/Client.DeletedObject' client: type: object nullable: true allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Server.UserPhoneNumbers: type: array items: $ref: '#/components/schemas/Client.PhoneNumber' Client.ClientWrappedPhoneNumber: type: object additionalProperties: false properties: response: type: object nullable: false allOf: - $ref: '#/components/schemas/Client.PhoneNumber' client: type: object nullable: false allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Server.UserWeb3Wallets: type: array items: $ref: '#/components/schemas/Client.Web3Wallet' Client.ClientWrappedWeb3Wallet: type: object additionalProperties: false properties: response: type: object nullable: false allOf: - $ref: '#/components/schemas/Client.Web3Wallet' client: type: object nullable: false allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.ClientWrappedPasskey: type: object additionalProperties: false properties: response: type: object nullable: false allOf: - $ref: '#/components/schemas/Client.Passkey' client: type: object nullable: false allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.ClientWrappedExternalAccount: type: object additionalProperties: false properties: response: type: object nullable: false allOf: - $ref: '#/components/schemas/ExternalAccountWithVerification' client: type: object nullable: false allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.ClientWrappedUser: type: object additionalProperties: false properties: response: type: object nullable: false allOf: - $ref: '#/components/schemas/Client.User' client: type: object nullable: false allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client TOTP: type: object additionalProperties: true properties: object: type: string enum: - totp id: type: string secret: type: string nullable: true uri: type: string nullable: true verified: type: boolean backup_codes: type: array items: type: string nullable: true created_at: type: integer format: int64 updated_at: type: integer format: int64 required: - object - id - secret - uri - verified - created_at - updated_at Client.ClientWrappedTOTP: type: object additionalProperties: false properties: response: type: object nullable: false allOf: - $ref: '#/components/schemas/TOTP' client: type: object nullable: false allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client BackupCodes: type: object properties: object: type: string enum: - backup_code id: type: string codes: type: array items: type: string description: A list of backup codes created_at: type: integer format: int64 updated_at: type: integer format: int64 required: - object - id - codes - created_at - updated_at Client.ClientWrappedBackupCodes: type: object additionalProperties: false properties: response: type: object nullable: false allOf: - $ref: '#/components/schemas/BackupCodes' client: type: object nullable: false allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.ClientWrappedImage: type: object properties: response: $ref: '#/components/schemas/Image' client: $ref: '#/components/schemas/Client.Client' required: - response - client schemas-Client.ClientWrappedUser: type: object additionalProperties: false properties: response: type: object nullable: false allOf: - $ref: '#/components/schemas/Client.User' client: type: object nullable: false allOf: - $ref: '#/components/schemas/Client.Client' required: - response - client BillingMoneyResponse: type: object additionalProperties: false properties: amount: type: integer format: int64 description: Amount in cents amount_formatted: type: string description: Formatted amount as a string (e.g., "$10.00") currency: type: string description: Currency code (e.g., "USD") currency_symbol: type: string description: Currency symbol (e.g., "$") required: - amount - amount_formatted - currency - currency_symbol BillingSubscriptionCreditResponse: type: object additionalProperties: false properties: amount: $ref: '#/components/schemas/BillingMoneyResponse' description: Credit amount with formatting cycle_days_remaining: type: integer format: int64 description: Number of days remaining in the billing cycle cycle_days_total: type: integer format: int64 description: Total number of days in the billing cycle cycle_remaining_percent: type: number format: double description: Percentage of the billing cycle remaining required: - amount - cycle_days_remaining - cycle_days_total - cycle_remaining_percent BillingProrationCreditDetail: type: object additionalProperties: false properties: amount: $ref: '#/components/schemas/BillingMoneyResponse' description: Credit amount with formatting cycle_days_remaining: type: integer format: int64 description: Number of days remaining in the billing cycle cycle_days_total: type: integer format: int64 description: Total number of days in the billing cycle cycle_remaining_percent: type: number format: double description: Percentage of the billing cycle remaining required: - amount - cycle_days_remaining - cycle_days_total - cycle_remaining_percent BillingPayerCreditResponse: type: object additionalProperties: false properties: remaining_balance: $ref: '#/components/schemas/BillingMoneyResponse' description: The payer's remaining credit balance after credit is applied for this checkout (in cents) applied_amount: $ref: '#/components/schemas/BillingMoneyResponse' description: The amount of payer credit applied to this checkout (in cents) required: - remaining_balance - applied_amount BillingCreditsResponse: type: object additionalProperties: false properties: proration: type: object nullable: true allOf: - $ref: '#/components/schemas/BillingProrationCreditDetail' description: Proration credit details from unused subscription time payer: type: object nullable: true allOf: - $ref: '#/components/schemas/BillingPayerCreditResponse' description: Payer credit details from the payer's credit balance total: $ref: '#/components/schemas/BillingMoneyResponse' description: Total credits applied required: - proration - payer - total BillingFee: type: object additionalProperties: false properties: amount: type: integer format: int64 description: Amount in the smallest currency unit (e.g., cents) minimum: 0 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 BillingPlanUnitPriceTier: 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/BillingMoneyResponse' description: Price charged per block in this tier required: - starts_at_block - fee_per_block BillingPlanUnitPrice: 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/BillingPlanUnitPriceTier' description: Tiered pricing configuration for this unit required: - name - block_size - tiers BillingPlan: type: object additionalProperties: false properties: object: type: string description: String representing the object's type 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/BillingFee' nullable: true description: The monthly fee for this plan annual_monthly_fee: allOf: - $ref: '#/components/schemas/BillingFee' nullable: true description: The monthly equivalent when billed annually annual_fee: allOf: - $ref: '#/components/schemas/BillingFee' nullable: true description: The annual fee for this plan 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 free_trial_enabled: type: boolean description: Whether free trial is enabled for this plan free_trial_days: type: integer nullable: true description: Number of free trial days for this plan unit_prices: type: array items: $ref: '#/components/schemas/BillingPlanUnitPrice' description: Per-unit pricing tiers for this plan (for example, seats) features: type: array description: The features included in this plan items: type: object properties: object: type: string enum: - feature description: String representing the object's type id: type: string description: Unique identifier for the feature name: type: string description: Name of the feature description: type: string nullable: true description: Description of the feature slug: type: string description: URL-friendly representation of the feature's name avatar_url: type: string nullable: true description: URL for an image to represent the feature required: - object - id - name - description - slug - avatar_url 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 BillingPaymentMethod: type: object additionalProperties: false properties: object: type: string description: String representing the object's type 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 required: - object - id - payer_id - payment_type - gateway - gateway_external_id - gateway_external_account_id - last4 - status - card_type BillingPerUnitTotalTier: 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/BillingMoneyResponse' description: Price charged per block in this tier total: $ref: '#/components/schemas/BillingMoneyResponse' description: Total charge for this tier required: - fee_per_block - total BillingPerUnitTotal: 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/BillingPerUnitTotalTier' description: Computed totals for each pricing tier required: - name - block_size - tiers BillingSubscriptionItemNextPayment: type: object additionalProperties: false properties: amount: $ref: '#/components/schemas/BillingFee' description: Amount for the next payment date: type: integer format: int64 description: Unix timestamp (in milliseconds) for the next payment date per_unit_totals: type: array items: $ref: '#/components/schemas/BillingPerUnitTotal' description: Per-unit total breakdown for the next payment BillingPayer: type: object additionalProperties: false properties: object: type: string description: String representing the object's type 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 (only set when user_id isn't null) nullable: true last_name: type: string description: Last name of the payer (only set when user_id isn't null) nullable: true email: type: string format: email description: Email address of the payer (only set when user_id isn't null) 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 (only set when organization_id isn't null) nullable: true image_url: type: string format: uri description: URL of the payer's image/avatar credits_balance: $ref: '#/components/schemas/BillingMoneyResponse' 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 required: - object - id - instance_id - user_id - organization_id BillingSubscriptionItemSeats: 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/BillingPerUnitTotalTier' description: Per-unit cost breakdown by pricing tier required: - quantity BillingTotalsResponse: type: object additionalProperties: false properties: subtotal: $ref: '#/components/schemas/BillingMoneyResponse' description: Subtotal before adjustments base_fee: $ref: '#/components/schemas/BillingMoneyResponse' description: Base fee component before per-unit charges and adjustments tax_total: $ref: '#/components/schemas/BillingMoneyResponse' description: Total tax amount grand_total: $ref: '#/components/schemas/BillingMoneyResponse' description: Grand total amount total_due_after_free_trial: allOf: - $ref: '#/components/schemas/BillingMoneyResponse' nullable: true description: Total amount due after free trial ends credit: allOf: - $ref: '#/components/schemas/BillingMoneyResponse' nullable: true description: Credit amount past_due: allOf: - $ref: '#/components/schemas/BillingMoneyResponse' nullable: true description: Past due amount total_due_now: allOf: - $ref: '#/components/schemas/BillingMoneyResponse' nullable: true description: Total amount due now per_unit_totals: type: array items: $ref: '#/components/schemas/BillingPerUnitTotal' description: Per-unit total breakdown (for example, seats) credits: allOf: - $ref: '#/components/schemas/BillingCreditsResponse' nullable: true description: Unified credits breakdown proration: type: object nullable: true additionalProperties: false properties: credit: $ref: '#/components/schemas/BillingMoneyResponse' description: Proration credit amount required: - subtotal - base_fee - tax_total - grand_total BillingSubscriptionItem: type: object additionalProperties: false properties: object: type: string description: String representing the object's type 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 - ended - past_due - upcoming - incomplete - abandoned credit: $ref: '#/components/schemas/BillingSubscriptionCreditResponse' description: Credit information for this subscription (available in payment attempt events) credits: allOf: - $ref: '#/components/schemas/BillingCreditsResponse' nullable: true description: Unified credits breakdown for this subscription item plan_id: type: string description: Unique identifier for the associated plan price_id: type: string description: Unique identifier for the associated price plan: $ref: '#/components/schemas/BillingPlan' description: The associated plan plan_period: type: string description: The billing period for this subscription enum: - month - annual payment_method_id: type: string description: Unique identifier for the payment method payment_method: $ref: '#/components/schemas/BillingPaymentMethod' description: The payment method associated with this subscription lifetime_paid: $ref: '#/components/schemas/BillingFee' description: Total amount paid over the lifetime of this subscription amount: $ref: '#/components/schemas/BillingFee' description: Current amount due every period for this subscription next_payment: $ref: '#/components/schemas/BillingSubscriptionItemNextPayment' nullable: true description: Information about the next payment payer_id: type: string description: Unique identifier for the payer payer: $ref: '#/components/schemas/BillingPayer' 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 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 seats: allOf: - $ref: '#/components/schemas/BillingSubscriptionItemSeats' nullable: true description: Seat quantity for seat-based billing totals: allOf: - $ref: '#/components/schemas/BillingTotalsResponse' nullable: true description: Totals for this subscription item 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 BillingSubscriptionNextPayment: type: object additionalProperties: false properties: date: type: integer format: int64 description: Unix timestamp (milliseconds) of the next payment date amount: $ref: '#/components/schemas/BillingFee' description: The amount of the next payment required: - date - amount BillingSubscription: type: object additionalProperties: false properties: object: type: string description: String representing the object's type 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/BillingSubscriptionItem' description: Array of subscription items in this subscription next_payment: allOf: - $ref: '#/components/schemas/BillingSubscriptionNextPayment' nullable: true description: Information about the next scheduled payment eligible_for_free_trial: type: boolean description: Whether the payer is eligible for a free trial required: - object - id - instance_id - status - payer_id - created_at - updated_at - active_at - past_due_at - subscription_items Client.BillingSubscription: type: object additionalProperties: false properties: response: $ref: '#/components/schemas/BillingSubscription' client: type: object nullable: true allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.BillingSubscriptionItemList: type: object additionalProperties: false properties: response: type: object additionalProperties: false properties: data: type: array items: $ref: '#/components/schemas/BillingSubscriptionItem' total_count: type: integer format: int64 description: Total number of subscription items client: type: object nullable: true allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.BillingSubscriptionItem: type: object additionalProperties: false properties: response: $ref: '#/components/schemas/BillingSubscriptionItem' client: type: object nullable: true allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.BillingPaymentMethodList: type: object additionalProperties: false properties: response: type: object additionalProperties: false properties: data: type: array items: $ref: '#/components/schemas/BillingPaymentMethod' total_count: type: integer format: int64 description: Total number of payment methods client: type: object nullable: true allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.BillingPaymentMethod: type: object additionalProperties: false properties: response: allOf: - $ref: '#/components/schemas/BillingPaymentMethod' nullable: true client: type: object nullable: true allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client BillingPaymentMethodInitialize: type: object additionalProperties: false properties: object: type: string description: String representing the object's type enum: - commerce_payment_method_initialize external_client_secret: type: string description: Client secret from the payment gateway for setting up payment method external_gateway_id: type: string description: External gateway identifier payment_method_order: type: array items: type: string description: Ordered list of supported payment methods required: - object - payment_method_order Client.BillingPaymentMethodInitialize: type: object additionalProperties: false properties: response: $ref: '#/components/schemas/BillingPaymentMethodInitialize' client: type: object nullable: true allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client BillingCheckoutTotals: type: object additionalProperties: false properties: subtotal: $ref: '#/components/schemas/BillingMoneyResponse' description: The total, pre-tax, that will be due base_fee: $ref: '#/components/schemas/BillingMoneyResponse' description: Base fee component before per-unit charges and adjustments tax_total: $ref: '#/components/schemas/BillingMoneyResponse' description: The total amount of tax that will be due grand_total: $ref: '#/components/schemas/BillingMoneyResponse' description: The total, including tax, that will be due total_due_after_free_trial: type: object nullable: true allOf: - $ref: '#/components/schemas/BillingMoneyResponse' description: The total, including tax, that will be charged after the free trial ends total_due_now: type: object nullable: true allOf: - $ref: '#/components/schemas/BillingMoneyResponse' description: The total, including tax, that will be charged upon checkout total_due_per_period: $ref: '#/components/schemas/BillingMoneyResponse' description: The expected total payment for each future billing period. past_due: type: object nullable: true allOf: - $ref: '#/components/schemas/BillingMoneyResponse' description: The amount that is past due for the subscription credit: type: object nullable: true allOf: - $ref: '#/components/schemas/BillingMoneyResponse' description: The amount of credit that will be consumed before the payment method is charged credits: type: object nullable: true allOf: - $ref: '#/components/schemas/BillingCreditsResponse' description: Unified credits breakdown per_unit_totals: type: array items: $ref: '#/components/schemas/BillingPerUnitTotal' description: Per-unit total breakdown (for example, seats) required: - subtotal - base_fee - tax_total - grand_total - total_due_after_free_trial - credit - credits - total_due_now - total_due_per_period BillingCheckout: type: object additionalProperties: false properties: object: type: string description: String representing the object's type enum: - commerce_checkout id: type: string description: Unique identifier for the checkout plan: $ref: '#/components/schemas/BillingPlan' description: The plan that is being purchased. plan_period: type: string description: How frequently the plan being purchased will be renewed enum: - month - annual payer: $ref: '#/components/schemas/BillingPayer' description: The payer that will be charged payment_method: $ref: '#/components/schemas/BillingPaymentMethod' description: The payment method that will be charged external_gateway_id: type: string description: The external ID of the object in the payment processor that will receive the funds status: type: string description: Current status of the subscription item enum: - completed - needs_confirmation totals: $ref: '#/components/schemas/BillingCheckoutTotals' description: The various subtotals and totals owed subscription_item: type: object $ref: '#/components/schemas/BillingSubscriptionItem' description: The subscription item created as a result of the checkout plan_period_start: type: integer format: int64 description: When the first billing period of the plan will start, as milliseconds since the Unix epoch is_immediate_plan_change: type: boolean description: Whether the checkout will take effect upon completion or at the start of the next billing period free_trial_ends_at: type: integer format: int64 description: When the free trial will end, as milliseconds since the Unix epoch needs_payment_method: type: boolean description: Whether this checkout requires an active payment method or not required: - object - id - plan - plan_period - payer - external_gateway_id - status - totals - is_immediate_plan_change - needs_payment_method Client.BillingCheckout: type: object additionalProperties: false properties: response: $ref: '#/components/schemas/BillingCheckout' client: type: object nullable: true allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client BillingPayee: type: object additionalProperties: false properties: object: type: string description: String representing the object's type enum: - commerce_payee id: type: string description: Unique identifier for the payee gateway_type: type: string description: Type of payment gateway gateway_external_id: type: string description: External ID in the payment gateway gateway_status: type: string description: Status of the gateway connection required: - object - id - gateway_type - gateway_external_id - gateway_status BillingPaymentAttempt: type: object additionalProperties: false properties: object: type: string description: String representing the object's type enum: - commerce_payment id: type: string description: Unique identifier for the payment attempt payment_id: type: string description: Unique identifier for the payment instance_id: type: string description: Unique identifier for the instance charge_type: type: string description: Type of charge payee_id: type: string description: Unique identifier for the payee payee: $ref: '#/components/schemas/BillingPayee' description: The payee associated with this payment payer_id: type: string description: Unique identifier for the payer payer: $ref: '#/components/schemas/BillingPayer' description: The payer associated with this payment subscription_item_id: type: string description: Unique identifier for the subscription item (only present for recurring payments) subscription_item: $ref: '#/components/schemas/BillingSubscriptionItem' description: The subscription item associated with this payment amount: $ref: '#/components/schemas/BillingMoneyResponse' description: Payment amount with formatting totals: allOf: - $ref: '#/components/schemas/BillingTotalsResponse' nullable: true description: Totals breakdown for this payment attempt payment_method_id: type: string description: Unique identifier for the payment method used payment_method: $ref: '#/components/schemas/BillingPaymentMethod' nullable: true description: The payment method used for this payment statement_id: type: string description: Unique identifier for the statement gateway_external_id: type: string nullable: true description: External ID from the payment gateway gateway_external_url: type: string nullable: true description: URL to view this payment in the gateway dashboard status: type: string description: Status of the payment attempt 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 failed_reason: type: object description: Reason for payment failure 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 required: - object - id - payment_id - instance_id - charge_type - payee_id - payee - payer_id - payer - subscription_item_id - subscription_item - amount - payment_method_id - payment_method - statement_id - gateway_external_id - gateway_external_url - status - paid_at - failed_at - created_at - updated_at Client.BillingPaymentAttemptList: type: object additionalProperties: false properties: response: type: object additionalProperties: false properties: data: type: array items: $ref: '#/components/schemas/BillingPaymentAttempt' total_count: type: integer format: int64 description: Total number of payment attempts client: type: object nullable: true allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.BillingPaymentAttempt: type: object additionalProperties: false properties: response: $ref: '#/components/schemas/BillingPaymentAttempt' client: type: object nullable: true allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client BillingStatementTotalsResponse: type: object additionalProperties: false properties: subtotal: $ref: '#/components/schemas/BillingMoneyResponse' description: Subtotal amount (base fee + unit price totals) base_fee: $ref: '#/components/schemas/BillingMoneyResponse' description: Base plan fee before unit pricing tax_total: $ref: '#/components/schemas/BillingMoneyResponse' description: Total tax amount grand_total: $ref: '#/components/schemas/BillingMoneyResponse' description: Grand total amount required: - subtotal - base_fee - tax_total - grand_total BillingStatementResponseGroup: type: object additionalProperties: false properties: object: type: string description: String representing the object's type timestamp: type: integer format: int64 description: Unix timestamp (in milliseconds) for the group items: type: array items: $ref: '#/components/schemas/BillingPaymentAttempt' description: Payment items in this group required: - object - timestamp - items BillingStatement: type: object additionalProperties: false properties: object: type: string description: String representing the object's type enum: - commerce_statement instance_id: type: string description: Unique identifier for the instance id: type: string description: Unique identifier for the statement timestamp: type: integer format: int64 description: Unix timestamp (in milliseconds) for the statement payer: $ref: '#/components/schemas/BillingPayer' description: The payer associated with this statement status: type: string description: Status of the statement totals: $ref: '#/components/schemas/BillingStatementTotalsResponse' description: Totals breakdown for the statement groups: type: array items: $ref: '#/components/schemas/BillingStatementResponseGroup' description: Groups of payment items in the statement required: - object - instance_id - id - timestamp - payer - status - totals - groups Client.BillingStatementList: type: object additionalProperties: false properties: response: type: object additionalProperties: false properties: data: type: array items: $ref: '#/components/schemas/BillingStatement' total_count: type: integer format: int64 description: Total number of statements client: type: object nullable: true allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.BillingStatement: type: object additionalProperties: false properties: response: $ref: '#/components/schemas/BillingStatement' client: type: object nullable: true allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.BillingGenericObject: type: object additionalProperties: false properties: response: type: object nullable: true client: type: object nullable: true allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.BillingGenericArray: type: object additionalProperties: false properties: response: type: object properties: data: type: array items: type: object total_count: type: integer format: int64 required: - data - total_count client: type: object nullable: true allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.ClientWrappedOrganizationMemberships: type: object additionalProperties: false properties: response: oneOf: - type: object nullable: false properties: data: type: array items: $ref: '#/components/schemas/Client.OrganizationMembership' total_count: type: integer format: int64 - type: array items: $ref: '#/components/schemas/Client.OrganizationMembership' client: type: object nullable: false allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.PublicOrganizationData: 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 Client.OrganizationInvitation: type: object properties: id: type: string object: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - organization_invitation email_address: type: string role: type: string role_name: type: string organization_id: type: string public_organization_data: type: object allOf: - $ref: '#/components/schemas/Client.PublicOrganizationData' status: type: string description: String representing the object's type. Objects of the same type share the same value. enum: - pending - revoked - accepted - expired - completed public_metadata: type: object additionalProperties: true url: type: string nullable: true expires_at: type: integer nullable: true format: int64 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 Client.OrganizationInvitationUserContext: type: object properties: public_organization_data: type: object nullable: false allOf: - $ref: '#/components/schemas/Client.PublicOrganizationData' allOf: - $ref: '#/components/schemas/Client.OrganizationInvitation' Client.ClientWrappedOrganizationInvitationsUserContext: type: object additionalProperties: false properties: response: type: object properties: data: type: array items: $ref: '#/components/schemas/Client.OrganizationInvitationUserContext' total_count: type: integer format: int64 client: type: object nullable: false allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.ClientWrappedOrganizationInvitationUserContext: type: object additionalProperties: false properties: response: allOf: - $ref: '#/components/schemas/Client.OrganizationInvitationUserContext' type: object nullable: false client: allOf: - $ref: '#/components/schemas/schemas-Client.Client' type: object nullable: false required: - response - client Client.OrganizationSuggestion: type: object additionalProperties: false properties: object: type: string enum: - organization_suggestion id: type: string public_organization_data: type: object allOf: - $ref: '#/components/schemas/Client.PublicOrganizationData' status: type: string created_at: type: integer format: int64 description: Unix timestamp of creation. updated_at: type: integer format: int64 description: Unix timestamp of last update. required: - object - id - status - created_at - updated_at Client.ClientWrappedOrganizationSuggestions: type: object additionalProperties: false properties: response: type: object properties: data: type: array items: $ref: '#/components/schemas/Client.OrganizationSuggestion' total_count: type: integer format: int64 client: type: object nullable: false allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.ClientWrappedOrganizationSuggestion: type: object additionalProperties: false properties: response: type: object nullable: false allOf: - $ref: '#/components/schemas/Client.OrganizationSuggestion' client: type: object nullable: false allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.ClientWrappedOrganization: type: object additionalProperties: false properties: response: type: object nullable: false allOf: - $ref: '#/components/schemas/Client.Organization' client: type: object nullable: false allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client schemas-Client.ClientWrappedOrganization: type: object additionalProperties: false properties: response: type: object nullable: false allOf: - $ref: '#/components/schemas/Client.Organization' client: type: object nullable: false allOf: - $ref: '#/components/schemas/Client.Client' required: - response - client Client.ClientWrappedOrganizationInvitations: type: object additionalProperties: false properties: response: oneOf: - type: array items: $ref: '#/components/schemas/Client.OrganizationInvitation' - type: object properties: data: type: array items: $ref: '#/components/schemas/Client.OrganizationInvitation' total_count: type: integer format: int64 client: type: object nullable: false allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.ClientWrappedOrganizationInvitation: type: object additionalProperties: false properties: response: type: object nullable: false allOf: - $ref: '#/components/schemas/Client.OrganizationInvitation' client: type: object nullable: false allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.ClientWrappedOrganizationMembership: type: object additionalProperties: false properties: response: type: object nullable: false allOf: - $ref: '#/components/schemas/Client.OrganizationMembership' client: type: object nullable: false allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.OrganizationDomainVerification: type: object additionalProperties: false properties: status: type: string strategy: type: string attempts: type: integer nullable: true expire_at: nullable: true type: integer format: int64 required: - status - strategy - attempts - expire_at Client.OrganizationDomain: type: object additionalProperties: false properties: object: type: string enum: - organization_domain id: type: string organization_id: type: string name: type: string enrollment_mode: type: string affiliation_email_address: nullable: true type: string verification: type: object nullable: true allOf: - $ref: '#/components/schemas/Client.OrganizationDomainVerification' total_pending_invitations: type: integer total_pending_suggestions: type: integer public_organization_data: type: object nullable: true allOf: - $ref: '#/components/schemas/Client.PublicOrganizationData' 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 - organization_id - name - enrollment_mode - affiliation_email_address - verification - total_pending_invitations - total_pending_suggestions - created_at - updated_at Client.ClientWrappedOrganizationDomains: type: object additionalProperties: false properties: response: type: object properties: data: type: array items: $ref: '#/components/schemas/Client.OrganizationDomain' total_count: type: integer format: int64 client: type: object nullable: false allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.ClientWrappedOrganizationDomain: type: object additionalProperties: false properties: response: type: object nullable: false allOf: - $ref: '#/components/schemas/Client.OrganizationDomain' client: type: object nullable: false allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.OrganizationMembershipRequest: type: object additionalProperties: false properties: object: type: string enum: - organization_membership_request id: type: string organization_id: type: string status: type: string public_user_data: type: object nullable: true allOf: - $ref: '#/components/schemas/Client.PublicUserData' 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 - organization_id - status - public_user_data - created_at - updated_at Client.ClientWrappedOrganizationMembershipRequests: type: object additionalProperties: false properties: response: type: object properties: data: type: array items: $ref: '#/components/schemas/Client.OrganizationMembershipRequest' total_count: type: integer format: int64 client: type: object nullable: false allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.ClientWrappedOrganizationMembershipRequest: type: object additionalProperties: false properties: response: type: object nullable: false allOf: - $ref: '#/components/schemas/Client.OrganizationMembershipRequest' client: type: object nullable: false allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.Permission: type: object additionalProperties: false properties: object: type: string enum: - permission id: type: string name: type: string key: type: string description: type: string type: type: string enum: - system - user 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 Client.Role: type: object additionalProperties: false properties: object: type: string enum: - role id: type: string name: type: string key: type: string description: type: string is_creator_eligible: type: boolean permissions: type: array items: $ref: '#/components/schemas/Client.Permission' 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 - is_creator_eligible - permissions - created_at - updated_at Client.ClientWrappedRoles: type: object additionalProperties: false properties: response: type: object properties: data: type: array items: $ref: '#/components/schemas/Client.Role' total_count: type: integer format: int64 has_role_set_migration: type: boolean description: Indicates whether there is an active role set migration for this organization. client: type: object nullable: false allOf: - $ref: '#/components/schemas/schemas-Client.Client' required: - response - client Client.WaitlistEntry: type: object additionalProperties: false properties: object: type: string enum: - waitlist_entry id: type: string required: - object - id responses: WellKnown.Assetlinks: description: Get Android asset links for universal/deep linking content: application/json: schema: $ref: '#/components/schemas/WellKnown.Assetlinks' WellKnown.JWKS: description: Get the JSON Web Key Set content: application/json: schema: $ref: '#/components/schemas/JWKS' ClerkErrors: description: Request was not successful content: application/json: schema: $ref: '#/components/schemas/ClerkErrors' WellKnown.AppleAppSiteAssociation: description: Get the Apple App Site Association file content: application/json: schema: $ref: '#/components/schemas/WellKnown.AppleAppSiteAssociation' WellKnown.OpenIDConfiguration: description: Get a basic OpenID configuration payload content: application/json: schema: $ref: '#/components/schemas/WellKnown.OpenIDConfiguration' WellKnown.OAuth2AuthorizationServerMetadata: description: Get the OAuth 2.0 Authorization Server Metadata content: application/json: schema: $ref: '#/components/schemas/WellKnown.OAuth2AuthorizationServerMetadata' OAuth.DynamicClientRegistration: description: 'Client information response after successful OAuth 2.0 dynamic client registration. Returns the client identifier, client secret (for confidential clients), and client metadata according to RFC 7591.' content: application/json: schema: $ref: '#/components/schemas/OAuth.DynamicClientRegistrationResponse' OAuth.DynamicClientRegistrationError: description: 'OAuth 2.0 dynamic client registration error response according to RFC 7591. Indicates that the client registration request was invalid.' content: application/json: schema: $ref: '#/components/schemas/OAuth.DynamicClientRegistrationError' OAuth.Token: description: 'Successfully issued OAuth2 tokens. The response includes an `access_token` and `refresh_token`. If the `openid` scope was granted, an `id_token` (JWT) will also be included in the response.' content: application/json: schema: $ref: '#/components/schemas/OAuth.Token' examples: withoutIdToken: summary: Token Response without ID Token description: Response when `openid` scope is not included value: access_token: oat_abc123xyz... token_type: Bearer expires_in: 86400 refresh_token: clk_refresh_abc123xyz... scope: email profile withIdToken: summary: Token Response with ID Token (OpenID Connect) description: Response when `openid` scope is included, includes JWT ID token value: access_token: oat_abc123xyz... token_type: Bearer expires_in: 86400 refresh_token: clk_refresh_abc123xyz... scope: openid email profile id_token: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... OAuth.TokenError400: description: 'Bad request error. Common causes: - Missing required parameters - Invalid `grant_type` value - Malformed request - Expired authorization code - Invalid `redirect_uri` (doesn''t match authorization request) - Unsupported token type for revocation (e.g., JWT access tokens)' content: application/json: schema: type: object properties: error: type: string enum: - invalid_request - invalid_grant - unsupported_token_type example: invalid_request error_description: type: string example: The request is missing a required parameter OAuth.TokenError401: description: 'Unauthorized error. Common causes: - Invalid client credentials (`client_id` or `client_secret`) - Invalid or expired authorization code - Invalid or expired refresh token - Invalid `code_verifier` for PKCE flow' content: application/json: schema: type: object properties: error: type: string enum: - invalid_client - invalid_grant - unsupported_grant_type example: invalid_client error_description: type: string example: Client authentication failed OAuth.UserInfo: description: Get user info after successful OAuth2 flow content: application/json: schema: $ref: '#/components/schemas/OAuth.UserInfo' OAuth.TokenInfo: description: Get information for an access or refresh token content: application/json: schema: $ref: '#/components/schemas/OAuth.TokenInfo' OAuth.ConsentInfo: description: OAuth2 consent information (scopes with descriptions) for a given OAuth Application Client ID content: application/json: schema: $ref: '#/components/schemas/OAuth.ConsentInfo' AuthenticationInvalid: description: Authentication invalid content: application/json: schema: $ref: '#/components/schemas/ClerkErrors' AuthorizationInvalid: description: Authorization invalid content: application/json: schema: $ref: '#/components/schemas/ClerkErrors' Client.AccountPortal: description: Returns the account portal. content: application/json: schema: $ref: '#/components/schemas/Client.AccountPortal' Client.Environment: description: Returns the environment. content: application/json: schema: $ref: '#/components/schemas/Client.Environment' Client.Client: description: Returns the current session object. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedClient' Client.DeleteSession: description: Returns the response for DELETE session object. content: application/json: schema: $ref: '#/components/schemas/Client.DeleteSession' Client.SignIn: description: Returns the sign in object, as well as the updated session object. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedSignIn' responses-Client.SignIn: description: Returns the sign in object, as well as the updated session object. content: application/json: schema: $ref: '#/components/schemas/schemas-Client.ClientWrappedSignIn' Client.SignUp: description: Returns the sign up object, as well as the updated session object. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedSignUp' Client.Session: description: Returns a Session object. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedSession' Client.TouchSession: description: Returns a touched Session object. The `client` field may be null for intents that skip piggybacking. content: application/json: schema: $ref: '#/components/schemas/Client.TouchWrappedSession' Client.ActiveSessions: description: Returns an Active Sessions array. content: application/json: schema: $ref: '#/components/schemas/Client.ActiveSessions' Client.SessionReverification: description: Returns the session reverification object, as well as the session object. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedSessionReverification' Server.Sessions: description: Returns Sessions array. content: application/json: schema: $ref: '#/components/schemas/Server.Sessions' Server.UserEmailAddresses: description: Returns UserEmailAddresses array. content: application/json: schema: $ref: '#/components/schemas/Server.UserEmailAddresses' Client.ClientWrappedEmailAddress: description: Returns the response for Session wrapped Email object. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedEmailAddress' Client.ClientWrappedDeletedObject: description: Returns a deleted generic object. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedDeletedObject' Server.UserPhoneNumbers: description: Returns UserPhoneNumbers array. content: application/json: schema: $ref: '#/components/schemas/Server.UserPhoneNumbers' Client.ClientWrappedPhoneNumber: description: Returns the response for Session wrapped Email object. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedPhoneNumber' Client.DeletedPhoneNumber: description: Returns single DeletedPhoneNumber. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedDeletedObject' Server.UserWeb3Wallets: description: Returns UserWeb3Wallets array. content: application/json: schema: $ref: '#/components/schemas/Server.UserWeb3Wallets' Client.ClientWrappedWeb3Wallet: description: Returns the response for Session wrapped Web3 wallet object. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedWeb3Wallet' Client.ClientWrappedPasskey: description: Returns the response for Session wrapped Passkey object. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedPasskey' Client.DeletedPasskey: description: Returns a deleted Passkey object. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedDeletedObject' Client.ClientWrappedExternalAccount: description: Returns the response for Session wrapped Verification object. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedExternalAccount' Client.DeletedExternalAccount: description: Returns a deleted external account. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedDeletedObject' Client.ClientWrappedUser: description: Returns the response for Session wrapped User object. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedUser' Client.ClientWrappedTOTP: description: Returns the response for Session wrapped TOTP object. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedTOTP' Client.DeletedTOTP: description: Returns a deleted TOTP. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedDeletedObject' Client.ClientWrappedBackupCodes: description: Returns the response for Session wrapped Backup code object. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedBackupCodes' Token: description: Success content: application/json: schema: $ref: '#/components/schemas/Token' Client.ClientWrappedImage: description: Returns an Image object. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedImage' responses-Client.ClientWrappedUser: description: Returns the response for Session wrapped User object. content: application/json: schema: $ref: '#/components/schemas/schemas-Client.ClientWrappedUser' Client.BillingSubscription: description: Returns a commerce subscription. content: application/json: schema: $ref: '#/components/schemas/Client.BillingSubscription' ResourceNotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ClerkErrors' Client.BillingSubscriptionItemList: description: Returns a list of commerce subscription items. content: application/json: schema: $ref: '#/components/schemas/Client.BillingSubscriptionItemList' Client.BillingSubscriptionItem: description: Returns a commerce subscription item. content: application/json: schema: $ref: '#/components/schemas/Client.BillingSubscriptionItem' UnprocessableEntity: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ClerkErrors' Client.BillingPaymentMethodList: description: Returns a list of commerce payment methods. content: application/json: schema: $ref: '#/components/schemas/Client.BillingPaymentMethodList' Client.BillingPaymentMethod: description: Returns a commerce payment method. content: application/json: schema: $ref: '#/components/schemas/Client.BillingPaymentMethod' Client.BillingPaymentMethodInitialize: description: Returns payment method initialization data. content: application/json: schema: $ref: '#/components/schemas/Client.BillingPaymentMethodInitialize' Client.BillingCheckout: description: Returns a commerce checkout. content: application/json: schema: $ref: '#/components/schemas/Client.BillingCheckout' Client.BillingPaymentAttemptList: description: Returns a list of commerce payment attempts. content: application/json: schema: $ref: '#/components/schemas/Client.BillingPaymentAttemptList' Client.BillingPaymentAttempt: description: Returns a commerce payment attempt. content: application/json: schema: $ref: '#/components/schemas/Client.BillingPaymentAttempt' Client.BillingStatementList: description: Returns a list of commerce statements. content: application/json: schema: $ref: '#/components/schemas/Client.BillingStatementList' Client.BillingStatement: description: Returns a commerce statement. content: application/json: schema: $ref: '#/components/schemas/Client.BillingStatement' Client.BillingGenericObject: description: Returns a generic commerce object. content: application/json: schema: $ref: '#/components/schemas/Client.BillingGenericObject' Client.BillingGenericArray: description: Returns a generic commerce array. content: application/json: schema: $ref: '#/components/schemas/Client.BillingGenericArray' BillingPlanList: description: Returns a list of commerce plans. content: application/json: schema: type: object additionalProperties: false required: - data - total_count properties: data: type: array items: $ref: '#/components/schemas/BillingPlan' total_count: type: integer format: int64 BillingPlan: description: Returns a commerce plan. content: application/json: schema: $ref: '#/components/schemas/BillingPlan' Client.ClientWrappedOrganizationMemberships: description: Returns the response for Client wrapped array of OrganizationMembership objects. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedOrganizationMemberships' Client.ClientWrappedOrganizationInvitationsUserContext: description: Returns the response for Client wrapped array of OrganizationInvitation objects with user context. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedOrganizationInvitationsUserContext' Client.ClientWrappedOrganizationInvitationUserContext: description: Returns the response for Client wrapped OrganizationInvitation object with user context. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedOrganizationInvitationUserContext' Client.ClientWrappedOrganizationSuggestions: description: Returns the response for Client wrapped array of OrganizationSuggestion objects with user context. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedOrganizationSuggestions' Client.ClientWrappedOrganizationSuggestion: description: Returns the response for Client wrapped OrganizationSuggestion object with user context. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedOrganizationSuggestion' Client.ClientWrappedOrganization: description: Returns the response for Client wrapped Organization object. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedOrganization' responses-Client.ClientWrappedOrganization: description: Returns the response for Client wrapped Organization object. content: application/json: schema: $ref: '#/components/schemas/schemas-Client.ClientWrappedOrganization' Client.ClientWrappedOrganizationInvitations: description: Returns the response for Client wrapped array of OrganizationInvitation objects. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedOrganizationInvitations' Client.ClientWrappedOrganizationInvitation: description: Returns the response for Client wrapped OrganizationInvitation object. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedOrganizationInvitation' Client.ClientWrappedOrganizationMembership: description: Returns the response for Client wrapped OrganizationMembership object. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedOrganizationMembership' Client.ClientWrappedOrganizationDomains: description: Returns the response for Client wrapped array of OrganizationDomain objects. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedOrganizationDomains' Client.ClientWrappedOrganizationDomain: description: Returns the response for Client wrapped OrganizationDomain object. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedOrganizationDomain' Client.DeletedOrganizationDomain: description: Returns a deleted organization domain. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedDeletedObject' Client.ClientWrappedOrganizationMembershipRequests: description: Returns the response for Client wrapped OrganizationMembershipRequest objects. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedOrganizationMembershipRequests' Client.ClientWrappedOrganizationMembershipRequest: description: Returns the response for Client wrapped OrganizationMembershipRequest object. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedOrganizationMembershipRequest' Client.ClientWrappedRoles: description: Returns the response for Client wrapped Roles objects. content: application/json: schema: $ref: '#/components/schemas/Client.ClientWrappedRoles' Client.WaitlistEntry: description: Returns the waitlist object. content: application/json: schema: $ref: '#/components/schemas/Client.WaitlistEntry' parameters: LimitParameter: name: limit in: query description: 'Applies a limit to the number of results returned. Can be used for paginating the results together with `offset`.' 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 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 x-tagGroups: - name: Environment tags: - Environment - name: Client tags: - Client - Sessions - Sign Ins - Sign Ups - name: User tags: - User - Active Sessions - Email Addresses - Phone Numbers - Web3 Wallets - Passkeys - External Accounts - TOTP - Backup Codes - Organizations Memberships - API Keys - name: Organizations tags: - Organization - Organization Creation Defaults - Invitations - Membership Requests - Members - Domains - Roles - name: Billing tags: - Plans - Subscriptions - Subscription Items - Checkouts - Payment Methods - Statements - Payment Attempts - name: Other tags: - Well Known - DevBrowser - DevTools - Health - OAuth2 Identity Provider - OAuth2 Callbacks - SAML - Waitlist - Enterprise Connections