diff --git a/bapi/2021-02-05.yml b/bapi/2021-02-05.yml index d55687e..1a2f342 100644 --- a/bapi/2021-02-05.yml +++ b/bapi/2021-02-05.yml @@ -70,6 +70,8 @@ tags: url: https://clerk.com/docs/request-authentication/jwt-templates - name: OAuth Applications description: OAuth applications contain data for clients using Clerk as an OAuth2 identity provider. + - name: OAuth Access Tokens + description: Endpoints for managing OAuth Access Tokens, which are credentials to access protected resources on behalf of a user. - name: Organizations description: Organizations are used to group members under a common entity and provide shared access to resources. externalDocs: @@ -101,6 +103,8 @@ tags: Sessions are created when a user successfully goes through the sign in or sign up flows. externalDocs: url: https://clerk.com/docs/reference/clerkjs/session + - name: Machines + description: A Machine represents a machine/server/service which can be used in machine-to-machine authentication. - name: Sign-in Tokens description: |- Sign-in tokens are JWTs that can be used to sign in to an application without specifying any credentials. @@ -211,6 +215,157 @@ paths: responses: '200': $ref: '#/components/responses/WellKnown.JWKS' + /aws_credentials: + x-internal: true + get: + operationId: GetAWSCredentialList + x-speakeasy-group: awsCredentials + x-speakeasy-name-override: list + tags: + - AWS Credentials + summary: List all AWS Credentials + description: Returns a list of all AWS Credentials. + responses: + '200': + $ref: '#/components/responses/AWSCredential.List' + post: + operationId: CreateAWSCredential + x-speakeasy-group: awsCredentials + x-speakeasy-name-override: create + tags: + - AWS Credentials + summary: Create an AWS Credential + description: Create a new AWS Credential + requestBody: + content: + application/json: + schema: + type: object + properties: + access_key_id: + type: string + description: The Access Key ID from AWS + secret_access_key: + type: string + description: The Secret Access Key from AWS. + user_pool_ids: + type: array + items: + type: string + description: The User Pool IDs from AWS. + required: + - access_key_id + - secret_access_key + - user_pool_ids + responses: + '200': + $ref: '#/components/responses/AWSCredential' + '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' + /aws_credentials/{id}: + x-internal: true + get: + operationId: GetAWSCredential + x-speakeasy-group: awsCredentials + x-speakeasy-name-override: get + tags: + - AWS Credentials + summary: Retrieve an AWS Credential + description: Returns the details of an AWS Credential. + parameters: + - name: id + in: path + description: The ID of the AWS Credential to retrieve + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/AWSCredential' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + delete: + operationId: DeleteAWSCredential + x-speakeasy-group: awsCredentials + x-speakeasy-name-override: delete + tags: + - AWS Credentials + summary: Delete an AWS Credential + description: Delete the AWS Credential with the given ID + parameters: + - name: id + in: path + description: The ID of the AWS Credential to delete + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/DeletedObject' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + patch: + operationId: UpdateAWSCredential + x-speakeasy-group: awsCredentials + x-speakeasy-name-override: update + tags: + - AWS Credentials + summary: Update an AWS Credential + description: Updates an AWS credential. + parameters: + - name: id + in: path + description: The ID of the AWS Credential to update + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + access_key_id: + type: string + nullable: true + user_pool_ids: + type: array + items: + type: string + secret_access_key: + type: string + nullable: true + responses: + '200': + $ref: '#/components/responses/AWSCredential' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' /clients: get: deprecated: true @@ -343,11 +498,11 @@ paths: '422': $ref: '#/components/responses/UnprocessableEntity' /email_addresses/{email_address_id}: - x-speakeasy-usage-example: true get: operationId: GetEmailAddress x-speakeasy-group: emailAddresses x-speakeasy-name-override: get + x-speakeasy-usage-example: true tags: - Email Addresses summary: Retrieve an email address @@ -1455,7 +1610,7 @@ paths: Note: If you are performing a migration, check out our guide on [zero downtime migrations](https://clerk.com/docs/deployments/migrate-overview). - A rate limit rule of 20 requests per 10 seconds is applied to this endpoint. + The following rate limit rules apply to this endpoint: 1000 requests per 10 seconds for production instances and 100 requests per 10 seconds for development instances tags: - Users requestBody: @@ -2056,6 +2211,70 @@ paths: $ref: '#/components/responses/User' '402': $ref: '#/components/responses/PaymentRequired' + /users/ban: + post: + operationId: UsersBan + x-speakeasy-group: users + x-speakeasy-name-override: bulkBan + summary: Ban multiple users + description: Marks multiple users as banned, which means that all their sessions are revoked and they are not allowed to sign in again. + tags: + - Users + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - user_ids + properties: + user_ids: + type: array + items: + type: string + description: Array of user IDs to ban + minItems: 1 + maxItems: 50 + responses: + '200': + $ref: '#/components/responses/User.List' + '400': + $ref: '#/components/responses/ClerkErrors' + '402': + $ref: '#/components/responses/PaymentRequired' + /users/unban: + post: + operationId: UsersUnban + x-speakeasy-group: users + x-speakeasy-name-override: bulkUnban + summary: Unban multiple users + description: Removes the ban mark from multiple users. + tags: + - Users + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - user_ids + properties: + user_ids: + type: array + items: + type: string + description: Array of user IDs to unban + minItems: 1 + maxItems: 50 + responses: + '200': + $ref: '#/components/responses/User.List' + '400': + $ref: '#/components/responses/ClerkErrors' + '402': + $ref: '#/components/responses/PaymentRequired' /users/{user_id}/lock: post: operationId: LockUser @@ -2710,13 +2929,15 @@ paths: in: query required: false description: |- - Allows to return organizations in a particular order. - At the moment, you can order the returned organizations either by their `name`, `created_at` or `members_count`. + Allows to return invitations in a particular order. + At the moment, you can order the returned invitations either by their `created_at`, `email_address` or `expires_at`. In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. - For example, if you want organizations to be returned in descending order according to their `created_at` property, you can use `-created_at`. + For example, if you want invitations to be returned in descending order according to their `created_at` property, you can use `-created_at`. If you don't use `+` or `-`, then `+` is implied. + Defaults to `-created_at`. schema: type: string + default: '-created_at' - $ref: '#/components/parameters/Paginated' - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' @@ -3400,9 +3621,7 @@ paths: type: array items: type: string - description: |- - For browser-like stacks such as browser extensions, Electron, or Capacitor.js the instance allowed origins need to be updated with the request origin value. - For Chrome extensions popup, background, or service worker pages the origin is chrome-extension://extension_uiid. For Electron apps the default origin is http://localhost:3000. For Capacitor, the origin is capacitor://localhost. + description: For browser-like stacks such as browser extensions, Electron (not officially supported), or Capacitor.js (not officially supported), the instance allowed origins need to be updated with the request origin value. For Chrome extensions popup, background, or service worker pages, the origin is chrome-extension://extension_uiid. For Electron apps the default origin is http://localhost:3000. For Capacitor, the origin is capacitor://localhost. cookieless_dev: type: boolean description: |- @@ -3447,9 +3666,6 @@ paths: block_disposable_email_domains: type: boolean nullable: true - ignore_dots_for_gmail_addresses: - type: boolean - nullable: true responses: '200': $ref: '#/components/responses/InstanceRestrictions' @@ -3768,90 +3984,386 @@ paths: $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' - /organizations: + /machine_tokens: + x-internal: true + post: + operationId: CreateMachineToken + x-speakeasy-group: machineTokens + x-speakeasy-name-override: create + summary: Create a machine token + description: Create a new machine token + tags: + - Machine Tokens + requestBody: + content: + application/json: + schema: + type: object + properties: + machine_id: + type: string + maxLength: 96 + description: ID of the machine creating the token. Must be be prefixed with `mch_`. Must only contain lowercase letters, numbers, and underscores. + claims: + type: object + description: Claims to include in the JWT + nullable: true + expires_in_seconds: + type: integer + minimum: 30 + maximum: 315360000 + description: Token lifetime in seconds. Defaults to 30 seconds if not specified. + nullable: true + allowed_clock_skew: + type: integer + minimum: 0 + maximum: 300 + default: 5 + description: Allowed clock skew in seconds. Defaults to 5 seconds if not specified. + nullable: true + required: + - machine_id + responses: + '200': + $ref: '#/components/responses/MachineToken' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /machines: get: - operationId: ListOrganizations - x-speakeasy-group: organizations + operationId: ListMachines + x-speakeasy-group: machines x-speakeasy-name-override: list - summary: Get a list of organizations for an instance + summary: Get a list of machines for an instance description: |- - This request returns the list of organizations for an instance. - Results can be paginated using the optional `limit` and `offset` query parameters. - The organizations are ordered by descending creation date. - Most recent organizations will be returned first. + This request returns the list of machines for an instance. The machines are + ordered by descending creation date (i.e. most recent machines will be + returned first) tags: - - Organizations + - Machines parameters: + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' - in: query - required: false - name: include_members_count - description: Flag to denote whether the member counts of each organization should be included in the response or not. - schema: - type: boolean - - in: query - required: false - name: include_missing_member_with_elevated_permissions - description: Flag to denote whether or not to include a member with elevated permissions who is not currently a member of the organization. - schema: - type: boolean - - in: query - required: false name: query - description: |- - Returns organizations with ID, name, or slug that match the given query. - Uses exact match for organization ID and partial match for name and slug. - schema: - type: string - - in: query - name: user_id - description: |- - Returns organizations with the user ids specified. Any user ids not found are ignored. - For each user id, the `+` and `-` can be prepended to the id, which denote whether the - respective organization should be included or excluded from the result set. - schema: - type: array - items: - type: string - required: false - - in: query - name: organization_id - description: |- - Returns organizations with the organization ids specified. Any organization ids not found are ignored. - For each organization id, the `+` and `-` can be prepended to the id, which denote whether the - respective organization should be included or excluded from the result set. Accepts up to 100 organization ids. - Example: ?organization_id=+org_1&organization_id=-org_2 - schema: - type: array - items: - type: string - required: false - - in: query - name: order_by - description: |- - Allows to return organizations in a particular order. - At the moment, you can order the returned organizations either by their `name`, `created_at` or `members_count`. - In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. - For example, if you want organizations to be returned in descending order according to their `created_at` property, you can use `-created_at`. - If you don't use `+` or `-`, then `+` is implied. - Defaults to `-created_at`. + description: Returns machines with ID or name that match the given query. Uses exact match for machine ID and partial match for name. schema: type: string - default: '-created_at' + allowEmptyValue: true required: false - - $ref: '#/components/parameters/LimitParameter' - - $ref: '#/components/parameters/OffsetParameter' responses: '200': - $ref: '#/components/responses/Organizations' + $ref: '#/components/responses/Machine.List' '400': $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' '403': $ref: '#/components/responses/AuthorizationInvalid' '422': $ref: '#/components/responses/UnprocessableEntity' post: - operationId: CreateOrganization - x-speakeasy-group: organizations + operationId: CreateMachine + x-speakeasy-group: machines + x-speakeasy-name-override: create + summary: Create a machine + description: Creates a new machine. + tags: + - Machines + requestBody: + content: + application/json: + schema: + type: object + required: + - name + properties: + name: + type: string + description: The name of the machine + minLength: 1 + maxLength: 255 + scoped_machines: + type: array + items: + type: string + description: Array of machine IDs that this machine will have access to. Maximum of 25 scopes per machine. + maxItems: 25 + responses: + '200': + $ref: '#/components/responses/Machine' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /machines/{machine_id}: + get: + operationId: GetMachine + x-speakeasy-group: machines + x-speakeasy-name-override: get + summary: Retrieve a machine + description: Returns the details of a machine. + tags: + - Machines + parameters: + - name: machine_id + in: path + description: The ID of the machine to retrieve + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/Machine' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + patch: + operationId: UpdateMachine + x-speakeasy-group: machines + x-speakeasy-name-override: update + summary: Update a machine + description: |- + Updates an existing machine. + Only the provided fields will be updated. + tags: + - Machines + parameters: + - name: machine_id + in: path + description: The ID of the machine to update + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The name of the machine + minLength: 1 + maxLength: 255 + responses: + '200': + $ref: '#/components/responses/Machine' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + delete: + operationId: DeleteMachine + x-speakeasy-group: machines + x-speakeasy-name-override: delete + summary: Delete a machine + description: Deletes a machine. + tags: + - Machines + parameters: + - name: machine_id + in: path + description: The ID of the machine to delete + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/Machine.Deleted' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /machines/{machine_id}/scopes: + post: + operationId: CreateMachineScope + x-speakeasy-group: machines + x-speakeasy-name-override: createScope + summary: Create a machine scope + description: |- + Creates a new machine scope, allowing the specified machine to access another machine. + Maximum of 25 scopes per machine. + tags: + - Machines + parameters: + - name: machine_id + in: path + description: The ID of the machine that will have access to another machine + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + required: + - to_machine_id + properties: + to_machine_id: + type: string + description: The ID of the machine that will be scoped to the current machine + responses: + '200': + $ref: '#/components/responses/MachineScope' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /machines/{machine_id}/scopes/{other_machine_id}: + delete: + operationId: DeleteMachineScope + x-speakeasy-group: machines + x-speakeasy-name-override: deleteScope + summary: Delete a machine scope + description: Deletes a machine scope, removing access from one machine to another. + tags: + - Machines + parameters: + - name: machine_id + in: path + description: The ID of the machine that has access to another machine + required: true + schema: + type: string + - name: other_machine_id + in: path + description: The ID of the machine that is being accessed + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/MachineScope.Deleted' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /organizations: + get: + operationId: ListOrganizations + x-speakeasy-group: organizations + x-speakeasy-name-override: list + summary: Get a list of organizations for an instance + description: |- + This request returns the list of organizations for an instance. + Results can be paginated using the optional `limit` and `offset` query parameters. + The organizations are ordered by descending creation date. + Most recent organizations will be returned first. + tags: + - Organizations + parameters: + - in: query + required: false + name: include_members_count + description: Flag to denote whether the member counts of each organization should be included in the response or not. + schema: + type: boolean + - in: query + required: false + name: include_missing_member_with_elevated_permissions + description: Flag to denote whether or not to include a member with elevated permissions who is not currently a member of the organization. + schema: + type: boolean + - in: query + required: false + name: query + description: |- + Returns organizations with ID, name, or slug that match the given query. + Uses exact match for organization ID and partial match for name and slug. + schema: + type: string + - in: query + name: user_id + description: |- + Returns organizations with the user ids specified. Any user ids not found are ignored. + For each user id, the `+` and `-` can be prepended to the id, which denote whether the + respective organization should be included or excluded from the result set. + schema: + type: array + items: + type: string + required: false + - in: query + name: organization_id + description: |- + Returns organizations with the organization ids specified. Any organization ids not found are ignored. + For each organization id, the `+` and `-` can be prepended to the id, which denote whether the + respective organization should be included or excluded from the result set. Accepts up to 100 organization ids. + Example: ?organization_id=+org_1&organization_id=-org_2 + schema: + type: array + items: + type: string + required: false + - in: query + name: order_by + description: |- + Allows to return organizations in a particular order. + At the moment, you can order the returned organizations either by their `name`, `created_at` or `members_count`. + In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. + For example, if you want organizations to be returned in descending order according to their `created_at` property, you can use `-created_at`. + If you don't use `+` or `-`, then `+` is implied. + Defaults to `-created_at`. + schema: + type: string + default: '-created_at' + required: false + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' + responses: + '200': + $ref: '#/components/responses/Organizations' + '400': + $ref: '#/components/responses/ClerkErrors' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + post: + operationId: CreateOrganization + x-speakeasy-group: organizations x-speakeasy-name-override: create summary: Create an organization description: |- @@ -4279,6 +4791,25 @@ paths: - pending - accepted - revoked + - in: query + required: false + name: email_address + description: Returns organization invitations inviting the specified email address. + schema: + type: string + - in: query + name: order_by + required: false + description: |- + Allows to return organization invitations in a particular order. + You can order the returned organization invitations either by their `created_at` or `email_address`. + In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. + For example, if you want organization invitations to be returned in descending order according to their `created_at` property, you can use `-created_at`. + If you don't use `+` or `-`, then `+` is implied. + Defaults to `-created_at`. + schema: + type: string + default: '-created_at' - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' responses: @@ -4288,6 +4819,8 @@ paths: $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' /organizations/{organization_id}/invitations/bulk: post: operationId: CreateOrganizationInvitationBulk @@ -4770,6 +5303,8 @@ paths: $ref: '#/components/responses/AuthenticationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' /organizations/{organization_id}/memberships/{user_id}/metadata: patch: operationId: UpdateOrganizationMembershipMetadata @@ -4982,6 +5517,86 @@ paths: $ref: '#/components/responses/AuthenticationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' + /organization_domains: + get: + operationId: ListAllOrganizationDomains + x-speakeasy-group: organizationDomains + x-speakeasy-name-override: listAll + summary: List all organization domains + description: | + Retrieves a list of all organization domains within the current instance. + This endpoint can be used to list all domains across all organizations + or filter domains by organization, verification status, enrollment mode, or search query. + + The response includes pagination information and details about each domain + including its verification status, enrollment mode, and associated counts. + tags: + - Organization Domains + parameters: + - in: query + name: organization_id + description: The ID of the organization to filter domains by + required: false + schema: + type: string + - in: query + name: verified + description: Filter by verification status + required: false + schema: + type: string + enum: + - 'true' + - 'false' + - in: query + name: enrollment_mode + description: Filter by enrollment mode + required: false + style: form + explode: false + schema: + type: array + items: + type: string + enum: + - manual_invitation + - automatic_invitation + - automatic_suggestion + - in: query + name: query + description: | + Search domains by name or organization ID. + If the query starts with "org_", it will search by exact organization ID match. + Otherwise, it performs a case-insensitive partial match on the domain name. + + Note: An empty string or whitespace-only value is not allowed and will result in a validation error. + required: false + schema: + type: string + - in: query + name: order_by + description: | + Allows to return organization domains in a particular order. + At the moment, you can order the returned domains by their `name` or `created_at`. + In order to specify the direction, you can use the `+/-` symbols prepended to the property to order by. + For example, if you want domains to be returned in descending order according to their `created_at` property, you can use `-created_at`. + If you don't use `+` or `-`, then `+` is implied. + Defaults to `-created_at`. + required: false + schema: + type: string + default: '-created_at' + - $ref: '#/components/parameters/OffsetParameter' + - $ref: '#/components/parameters/LimitParameter' + responses: + '200': + $ref: '#/components/responses/OrganizationDomains' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' /proxy_checks: post: summary: Verify the proxy configuration for your domain @@ -5235,6 +5850,25 @@ paths: parameters: - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' + - name: order_by + in: query + description: |- + Allows to return OAuth applications in a particular order. + At the moment, you can order the returned OAuth applications by their `created_at` and `name`. + In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. + For example, if you want OAuth applications to be returned in descending order according to their `created_at` property, you can use `-created_at`. + If you don't use `+` or `-`, then `+` is implied. We only support one `order_by` parameter, and if multiple `order_by` parameters are provided, we will only keep the first one. For example, + if you pass `order_by=name&order_by=created_at`, we will consider only the first `order_by` parameter, which is `name`. The `created_at` parameter will be ignored in this case. + required: false + schema: + type: string + default: +created_at + - name: name_query + in: query + description: Returns OAuth applications with names that match the given query, via case-insensitive partial match. + required: false + schema: + type: string responses: '200': $ref: '#/components/responses/OAuthApplications' @@ -5285,6 +5919,16 @@ paths: default: profile email example: profile email public_metadata nullable: true + consent_screen_enabled: + type: boolean + default: true + description: True to enable a consent screen to display in the authentication flow. + nullable: true + pkce_required: + type: boolean + default: false + description: True to require the Proof Key of Code Exchange (PKCE) flow. + nullable: true public: type: boolean description: If true, this client is public and you can use the Proof Key of Code Exchange (PKCE) flow. @@ -5371,6 +6015,14 @@ paths: default: profile email example: profile email public_metadata private_metadata nullable: true + consent_screen_enabled: + type: boolean + description: True to enable a consent screen to display in the authentication flow. This cannot be disabled for dynamically registered OAuth Applications. + nullable: true + pkce_required: + type: boolean + description: True to require the Proof Key of Code Exchange (PKCE) flow. + nullable: true public: type: boolean description: If true, this client is public and you can use the Proof Key of Code Exchange (PKCE) flow. @@ -5508,7 +6160,13 @@ paths: description: The name to use as a label for this SAML Connection domain: type: string + deprecated: true description: The domain of your organization. Sign in flows using an email with this domain, will use this SAML Connection. + domains: + type: array + items: + type: string + description: The domains of your organization. Sign in flows using an email with one of these domains, will use this SAML Connection. provider: type: string description: The IdP provider of the connection. @@ -5557,8 +6215,12 @@ paths: type: string required: - name - - domain - provider + anyOf: + - required: + - domain + - required: + - domains responses: '200': $ref: '#/components/responses/SAMLConnection' @@ -5625,7 +6287,14 @@ paths: domain: type: string description: The domain to use for the new SAML Connection + deprecated: true nullable: true + domains: + type: array + items: + type: string + nullable: true + description: A list of the domains on use for the SAML connection idp_entity_id: type: string description: The entity id as provided by the IdP @@ -5874,6 +6543,148 @@ paths: $ref: '#/components/responses/AccountlessApplication' '500': $ref: '#/components/responses/ClerkErrors' + /oauth_applications/access_tokens/verify: + post: + x-speakeasy-group: oauthAccessTokens + x-speakeasy-name-override: verify + operationId: verifyOAuthAccessToken + summary: Verify an OAuth Access Token + tags: + - OAuth Access Tokens + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + access_token: + type: string + description: The access token to verify. + example: XXXXXXXXXXXXXX + secret: + type: string + description: The access token to verify. This is deprecated, use `access_token` instead. + deprecated: true + example: XXXXXXXXXXXXXX + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + object: + type: string + enum: + - clerk_idp_oauth_access_token + example: clerk_idp_oauth_access_token + id: + type: string + pattern: ^oat_[0-9A-Fa-f]{32}$ + example: oat_0ef5a7a33d87ed87ee7954c845d80450 + client_id: + type: string + example: client_2xhFjEI5X2qWRvtV13BzSj8H6Dk + subject: + type: string + pattern: ^user_\w{27}$ + example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk + scopes: + type: array + items: + type: string + example: + - read + - write + revoked: + type: boolean + example: false + revocation_reason: + type: string + nullable: true + example: Revoked by user + expired: + type: boolean + example: false + expiration: + type: number + nullable: true + example: 1716883200 + created_at: + type: number + example: 1716883200 + updated_at: + type: number + example: 1716883200 + required: + - object + - id + - client_id + - subject + - scopes + - revoked + - revocation_reason + - expired + - expiration + - created_at + - updated_at + additionalProperties: false + '400': + description: 400 Bad Request + content: + application/json: + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + example: Bad Request + long_message: + type: string + example: 'Invalid ''url_parameter.example'': Failed regex check' + code: + type: string + example: bad_request + required: + - message + - long_message + - code + required: + - errors + '404': + description: 404 Not Found + content: + application/json: + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + example: some details about the error + long_message: + type: string + example: some details about the error + code: + type: string + example: some_error_code + required: + - message + - long_message + - code + required: + - errors components: securitySchemes: bearerAuth: @@ -6153,17 +6964,97 @@ components: 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' + 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' + AWSCredential: + 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: + - aws_credential + access_key_id: + type: string + user_pool_ids: + type: array + items: + type: string + 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 + - access_key_id + - user_pool_ids + - created_at + - updated_at + ClerkError: + type: object + properties: + message: + type: string + long_message: + type: string + code: + type: string + meta: + type: object + clerk_trace_id: + type: string + 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 + DeletedObject: + type: object + additionalProperties: false + properties: + object: + type: string + id: + type: string + slug: + type: string + deleted: + type: boolean + required: + - object + - deleted SessionActivityResponse: type: object nullable: true @@ -6310,36 +7201,6 @@ components: - last_active_session_id - updated_at - created_at - ClerkError: - type: object - properties: - message: - type: string - long_message: - type: string - code: - type: string - meta: - type: object - clerk_trace_id: - type: string - 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 OTP: type: object additionalProperties: false @@ -6522,21 +7383,6 @@ components: - reserved - created_at - updated_at - DeletedObject: - type: object - additionalProperties: false - properties: - object: - type: string - id: - type: string - slug: - type: string - deleted: - type: boolean - required: - - object - - deleted PhoneNumber: type: object additionalProperties: false @@ -6665,6 +7511,9 @@ components: can_delete: type: boolean description: whether this template can be deleted + can_edit_body: + type: boolean + description: whether the body of this template can be edited can_toggle: type: boolean description: whether this template can be enabled or disabled, true only for notification SMS templates @@ -6948,6 +7797,9 @@ components: username: type: string nullable: true + phone_number: + type: string + nullable: true public_metadata: type: object additionalProperties: true @@ -7032,6 +7884,11 @@ components: type: string domain: type: string + deprecated: true + domains: + type: array + items: + type: string active: type: boolean provider: @@ -7057,12 +7914,16 @@ components: required: - id - name - - domain - active - provider - sync_user_attributes - created_at - updated_at + anyOf: + - required: + - domain + - required: + - domains SAMLAccount: type: object additionalProperties: false @@ -7274,9 +8135,9 @@ components: The hashing algorithm that was used to generate the password digest. The algorithms we support at the moment are [`bcrypt`](https://en.wikipedia.org/wiki/Bcrypt), [`bcrypt_sha256_django`](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/), [`md5`](https://en.wikipedia.org/wiki/MD5), `pbkdf2_sha1`, `pbkdf2_sha256`, [`pbkdf2_sha256_django`](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/), - [`phpass`](https://www.openwall.com/phpass/), [`scrypt_firebase`](https://firebaseopensource.com/projects/firebase/scrypt/), + [`phpass`](https://www.openwall.com/phpass/), `md5_phpass`, [`scrypt_firebase`](https://firebaseopensource.com/projects/firebase/scrypt/), [`scrypt_werkzeug`](https://werkzeug.palletsprojects.com/en/3.0.x/utils/#werkzeug.security.generate_password_hash), [`sha256`](https://en.wikipedia.org/wiki/SHA-2), - and the [`argon2`](https://argon2.online/) variants: `argon2i` and `argon2id`. + [`ldap_ssha`](https://www.openldap.org/faq/data/cache/347.html) and the [`argon2`](https://argon2.online/) variants: `argon2i` and `argon2id`. Each of the supported hashers expects the incoming digest to be in a particular format. See the [Clerk docs](https://clerk.com/docs/references/backend/user/create-user) for more information. TotalCount: @@ -7358,6 +8219,10 @@ components: type: string slug: type: string + image_url: + type: string + has_image: + type: boolean members_count: type: integer missing_member_with_elevated_permissions: @@ -7391,10 +8256,10 @@ components: - id - name - slug + - has_image - max_allowed_memberships - admin_delete_enabled - public_metadata - - private_metadata - created_at - updated_at OrganizationMembershipPublicUserData: @@ -7883,15 +8748,12 @@ components: type: boolean block_disposable_email_domains: type: boolean - ignore_dots_for_gmail_addresses: - type: boolean required: - object - allowlist - blocklist - block_email_subaddresses - block_disposable_email_domains - - ignore_dots_for_gmail_addresses OrganizationSettings: type: object additionalProperties: false @@ -7990,6 +8852,86 @@ components: - signing_algorithm - created_at - updated_at + MachineToken: + type: object + additionalProperties: false + properties: + object: + type: string + enum: + - token + jwt: + type: string + required: + - object + - jwt + MachineWithoutScopedMachines: + type: object + required: + - object + - id + - name + - instance_id + - created_at + - updated_at + properties: + object: + type: string + enum: + - machine + id: + type: string + description: Unique identifier for the machine. + name: + type: string + description: The name of the machine. + maxLength: 255 + minLength: 1 + instance_id: + type: string + description: The ID of the instance this machine belongs to. + created_at: + type: integer + format: int64 + description: Unix timestamp of creation. + updated_at: + type: integer + format: int64 + description: Unix timestamp of last update. + Machine: + allOf: + - $ref: '#/components/schemas/MachineWithoutScopedMachines' + - type: object + required: + - scoped_machines + properties: + scoped_machines: + type: array + items: + $ref: '#/components/schemas/MachineWithoutScopedMachines' + description: Array of machines this machine has access to. + MachineScope: + type: object + required: + - object + - from_machine_id + - to_machine_id + - created_at + properties: + object: + type: string + enum: + - machine_scope + from_machine_id: + type: string + description: The ID of the machine that has access to the target machine. + to_machine_id: + type: string + description: The ID of the machine that is being accessed. + created_at: + type: integer + format: int64 + description: Unix timestamp of creation. Organizations: type: object additionalProperties: false @@ -8466,6 +9408,18 @@ components: type: string client_id: type: string + client_uri: + type: string + nullable: true + client_image_url: + type: string + nullable: true + dynamically_registered: + type: boolean + consent_screen_enabled: + type: boolean + pkce_required: + type: boolean public: type: boolean scopes: @@ -8504,8 +9458,13 @@ components: - id - instance_id - name + - dynamically_registered + - consent_screen_enabled + - pkce_required - public - client_id + - client_uri + - client_image_url - scopes - redirect_uris - callback_url @@ -8571,6 +9530,11 @@ components: type: string domain: type: string + deprecated: true + domains: + type: array + items: + type: string idp_entity_id: type: string nullable: true @@ -8625,7 +9589,6 @@ components: - object - id - name - - domain - idp_entity_id - idp_sso_url - idp_certificate @@ -8638,6 +9601,11 @@ components: - sync_user_attributes - created_at - updated_at + anyOf: + - required: + - domain + - required: + - domains SAMLConnections: type: object additionalProperties: false @@ -8748,14 +9716,20 @@ components: application/json: schema: $ref: '#/components/schemas/JWKS' - Client.List: + AWSCredential.List: description: Success content: application/json: schema: type: array items: - $ref: '#/components/schemas/Client' + $ref: '#/components/schemas/AWSCredential' + AWSCredential: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/AWSCredential' ClerkErrors: description: Request was not successful content: @@ -8768,48 +9742,56 @@ components: application/json: schema: $ref: '#/components/schemas/ClerkErrors' - DeprecatedEndpoint: - description: The endpoint is considered deprecated and is pending removal. + AuthorizationInvalid: + description: Authorization invalid content: application/json: schema: $ref: '#/components/schemas/ClerkErrors' - UnprocessableEntity: - description: Invalid request parameters + ResourceNotFound: + description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ClerkErrors' - Client: - description: Success + UnprocessableEntity: + description: Invalid request parameters content: application/json: schema: - $ref: '#/components/schemas/Client' - ResourceNotFound: - description: Resource not found + $ref: '#/components/schemas/ClerkErrors' + DeletedObject: + description: Deleted Object content: application/json: schema: - $ref: '#/components/schemas/ClerkErrors' - EmailAddress: + $ref: '#/components/schemas/DeletedObject' + Client.List: description: Success content: application/json: schema: - $ref: '#/components/schemas/EmailAddress' - AuthorizationInvalid: - description: Authorization invalid + type: array + items: + $ref: '#/components/schemas/Client' + DeprecatedEndpoint: + description: The endpoint is considered deprecated and is pending removal. content: application/json: schema: $ref: '#/components/schemas/ClerkErrors' - DeletedObject: - description: Deleted Object + Client: + description: Success content: application/json: schema: - $ref: '#/components/schemas/DeletedObject' + $ref: '#/components/schemas/Client' + EmailAddress: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/EmailAddress' PhoneNumber: description: Success content: @@ -9031,6 +10013,99 @@ components: application/json: schema: $ref: '#/components/schemas/JWTTemplate' + MachineToken: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/MachineToken' + Machine.List: + description: Success + content: + application/json: + schema: + type: object + required: + - data + - total_count + properties: + data: + type: array + items: + $ref: '#/components/schemas/Machine' + total_count: + type: integer + description: Total number of machines + Machine: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/Machine' + Machine.Deleted: + description: Success + content: + application/json: + schema: + type: object + required: + - object + - id + - deleted + properties: + object: + type: string + enum: + - machine + description: String representing the object's type. + id: + type: string + description: The ID of the deleted machine + deleted: + type: boolean + enum: + - true + description: Whether the machine was successfully deleted + MachineScope: + description: Machine scope created successfully for a machine + content: + application/json: + schema: + $ref: '#/components/schemas/MachineScope' + Conflict: + description: Conflict + content: + application/json: + schema: + $ref: '#/components/schemas/ClerkErrors' + MachineScope.Deleted: + description: Machine scope deleted successfully for a machine + content: + application/json: + schema: + type: object + required: + - object + - from_machine_id + - to_machine_id + - deleted + properties: + object: + type: string + enum: + - machine_scope + description: String representing the object's type. + from_machine_id: + type: string + description: The ID of the machine that had access to the target machine + to_machine_id: + type: string + description: The ID of the machine that was being accessed + deleted: + type: boolean + enum: + - true + description: Whether the machine scope was successfully deleted Organizations: description: A list of organizations content: diff --git a/bapi/2024-10-01.yml b/bapi/2024-10-01.yml index 79bc7bc..e1250cb 100644 --- a/bapi/2024-10-01.yml +++ b/bapi/2024-10-01.yml @@ -70,6 +70,8 @@ tags: url: https://clerk.com/docs/request-authentication/jwt-templates - name: OAuth Applications description: OAuth applications contain data for clients using Clerk as an OAuth2 identity provider. + - name: OAuth Access Tokens + description: Endpoints for managing OAuth Access Tokens, which are credentials to access protected resources on behalf of a user. - name: Organizations description: Organizations are used to group members under a common entity and provide shared access to resources. externalDocs: @@ -101,6 +103,8 @@ tags: Sessions are created when a user successfully goes through the sign in or sign up flows. externalDocs: url: https://clerk.com/docs/reference/clerkjs/session + - name: Machines + description: A Machine represents a machine/server/service which can be used in machine-to-machine authentication. - name: Sign-in Tokens description: |- Sign-in tokens are JWTs that can be used to sign in to an application without specifying any credentials. @@ -211,6 +215,157 @@ paths: responses: '200': $ref: '#/components/responses/WellKnown.JWKS' + /aws_credentials: + x-internal: true + get: + operationId: GetAWSCredentialList + x-speakeasy-group: awsCredentials + x-speakeasy-name-override: list + tags: + - AWS Credentials + summary: List all AWS Credentials + description: Returns a list of all AWS Credentials. + responses: + '200': + $ref: '#/components/responses/AWSCredential.List' + post: + operationId: CreateAWSCredential + x-speakeasy-group: awsCredentials + x-speakeasy-name-override: create + tags: + - AWS Credentials + summary: Create an AWS Credential + description: Create a new AWS Credential + requestBody: + content: + application/json: + schema: + type: object + properties: + access_key_id: + type: string + description: The Access Key ID from AWS + secret_access_key: + type: string + description: The Secret Access Key from AWS. + user_pool_ids: + type: array + items: + type: string + description: The User Pool IDs from AWS. + required: + - access_key_id + - secret_access_key + - user_pool_ids + responses: + '200': + $ref: '#/components/responses/AWSCredential' + '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' + /aws_credentials/{id}: + x-internal: true + get: + operationId: GetAWSCredential + x-speakeasy-group: awsCredentials + x-speakeasy-name-override: get + tags: + - AWS Credentials + summary: Retrieve an AWS Credential + description: Returns the details of an AWS Credential. + parameters: + - name: id + in: path + description: The ID of the AWS Credential to retrieve + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/AWSCredential' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + delete: + operationId: DeleteAWSCredential + x-speakeasy-group: awsCredentials + x-speakeasy-name-override: delete + tags: + - AWS Credentials + summary: Delete an AWS Credential + description: Delete the AWS Credential with the given ID + parameters: + - name: id + in: path + description: The ID of the AWS Credential to delete + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/DeletedObject' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + patch: + operationId: UpdateAWSCredential + x-speakeasy-group: awsCredentials + x-speakeasy-name-override: update + tags: + - AWS Credentials + summary: Update an AWS Credential + description: Updates an AWS credential. + parameters: + - name: id + in: path + description: The ID of the AWS Credential to update + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + access_key_id: + type: string + nullable: true + user_pool_ids: + type: array + items: + type: string + secret_access_key: + type: string + nullable: true + responses: + '200': + $ref: '#/components/responses/AWSCredential' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' /clients: get: deprecated: true @@ -344,10 +499,10 @@ paths: $ref: '#/components/responses/UnprocessableEntity' /email_addresses/{email_address_id}: get: - x-speakeasy-usage-example: true operationId: GetEmailAddress x-speakeasy-group: emailAddresses x-speakeasy-name-override: get + x-speakeasy-usage-example: true tags: - Email Addresses summary: Retrieve an email address @@ -1455,7 +1610,7 @@ paths: Note: If you are performing a migration, check out our guide on [zero downtime migrations](https://clerk.com/docs/deployments/migrate-overview). - A rate limit rule of 20 requests per 10 seconds is applied to this endpoint. + The following rate limit rules apply to this endpoint: 1000 requests per 10 seconds for production instances and 100 requests per 10 seconds for development instances tags: - Users requestBody: @@ -2056,6 +2211,70 @@ paths: $ref: '#/components/responses/User' '402': $ref: '#/components/responses/PaymentRequired' + /users/ban: + post: + operationId: UsersBan + x-speakeasy-group: users + x-speakeasy-name-override: bulkBan + summary: Ban multiple users + description: Marks multiple users as banned, which means that all their sessions are revoked and they are not allowed to sign in again. + tags: + - Users + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - user_ids + properties: + user_ids: + type: array + items: + type: string + description: Array of user IDs to ban + minItems: 1 + maxItems: 50 + responses: + '200': + $ref: '#/components/responses/User.List' + '400': + $ref: '#/components/responses/ClerkErrors' + '402': + $ref: '#/components/responses/PaymentRequired' + /users/unban: + post: + operationId: UsersUnban + x-speakeasy-group: users + x-speakeasy-name-override: bulkUnban + summary: Unban multiple users + description: Removes the ban mark from multiple users. + tags: + - Users + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - user_ids + properties: + user_ids: + type: array + items: + type: string + description: Array of user IDs to unban + minItems: 1 + maxItems: 50 + responses: + '200': + $ref: '#/components/responses/User.List' + '400': + $ref: '#/components/responses/ClerkErrors' + '402': + $ref: '#/components/responses/PaymentRequired' /users/{user_id}/lock: post: operationId: LockUser @@ -2710,13 +2929,15 @@ paths: in: query required: false description: |- - Allows to return organizations in a particular order. - At the moment, you can order the returned organizations either by their `name`, `created_at` or `members_count`. + Allows to return invitations in a particular order. + At the moment, you can order the returned invitations either by their `created_at`, `email_address` or `expires_at`. In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. - For example, if you want organizations to be returned in descending order according to their `created_at` property, you can use `-created_at`. + For example, if you want invitations to be returned in descending order according to their `created_at` property, you can use `-created_at`. If you don't use `+` or `-`, then `+` is implied. + Defaults to `-created_at`. schema: type: string + default: '-created_at' - $ref: '#/components/parameters/Paginated' - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' @@ -3400,9 +3621,7 @@ paths: type: array items: type: string - description: |- - For browser-like stacks such as browser extensions, Electron, or Capacitor.js the instance allowed origins need to be updated with the request origin value. - For Chrome extensions popup, background, or service worker pages the origin is chrome-extension://extension_uiid. For Electron apps the default origin is http://localhost:3000. For Capacitor, the origin is capacitor://localhost. + description: For browser-like stacks such as browser extensions, Electron (not officially supported), or Capacitor.js (not officially supported), the instance allowed origins need to be updated with the request origin value. For Chrome extensions popup, background, or service worker pages, the origin is chrome-extension://extension_uiid. For Electron apps the default origin is http://localhost:3000. For Capacitor, the origin is capacitor://localhost. cookieless_dev: type: boolean description: |- @@ -3447,9 +3666,6 @@ paths: block_disposable_email_domains: type: boolean nullable: true - ignore_dots_for_gmail_addresses: - type: boolean - nullable: true responses: '200': $ref: '#/components/responses/InstanceRestrictions' @@ -3768,81 +3984,377 @@ paths: $ref: '#/components/responses/AuthorizationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' - /organizations: + /machine_tokens: + x-internal: true + post: + operationId: CreateMachineToken + x-speakeasy-group: machineTokens + x-speakeasy-name-override: create + summary: Create a machine token + description: Create a new machine token + tags: + - Machine Tokens + requestBody: + content: + application/json: + schema: + type: object + properties: + machine_id: + type: string + maxLength: 96 + description: ID of the machine creating the token. Must be be prefixed with `mch_`. Must only contain lowercase letters, numbers, and underscores. + claims: + type: object + description: Claims to include in the JWT + nullable: true + expires_in_seconds: + type: integer + minimum: 30 + maximum: 315360000 + description: Token lifetime in seconds. Defaults to 30 seconds if not specified. + nullable: true + allowed_clock_skew: + type: integer + minimum: 0 + maximum: 300 + default: 5 + description: Allowed clock skew in seconds. Defaults to 5 seconds if not specified. + nullable: true + required: + - machine_id + responses: + '200': + $ref: '#/components/responses/MachineToken' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /machines: get: - operationId: ListOrganizations - x-speakeasy-group: organizations + operationId: ListMachines + x-speakeasy-group: machines x-speakeasy-name-override: list - summary: Get a list of organizations for an instance + summary: Get a list of machines for an instance description: |- - This request returns the list of organizations for an instance. - Results can be paginated using the optional `limit` and `offset` query parameters. - The organizations are ordered by descending creation date. - Most recent organizations will be returned first. + This request returns the list of machines for an instance. The machines are + ordered by descending creation date (i.e. most recent machines will be + returned first) tags: - - Organizations + - Machines parameters: + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' - in: query - required: false - name: include_members_count - description: Flag to denote whether the member counts of each organization should be included in the response or not. - schema: - type: boolean - - in: query - required: false - name: include_missing_member_with_elevated_permissions - description: Flag to denote whether or not to include a member with elevated permissions who is not currently a member of the organization. - schema: - type: boolean - - in: query - required: false name: query - description: |- - Returns organizations with ID, name, or slug that match the given query. - Uses exact match for organization ID and partial match for name and slug. - schema: - type: string - - in: query - name: user_id - description: |- - Returns organizations with the user ids specified. Any user ids not found are ignored. - For each user id, the `+` and `-` can be prepended to the id, which denote whether the - respective organization should be included or excluded from the result set. - schema: - type: array - items: - type: string - required: false - - in: query - name: organization_id - description: |- - Returns organizations with the organization ids specified. Any organization ids not found are ignored. - For each organization id, the `+` and `-` can be prepended to the id, which denote whether the - respective organization should be included or excluded from the result set. Accepts up to 100 organization ids. - Example: ?organization_id=+org_1&organization_id=-org_2 - schema: - type: array - items: - type: string - required: false - - in: query - name: order_by - description: |- - Allows to return organizations in a particular order. - At the moment, you can order the returned organizations either by their `name`, `created_at` or `members_count`. - In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. - For example, if you want organizations to be returned in descending order according to their `created_at` property, you can use `-created_at`. - If you don't use `+` or `-`, then `+` is implied. - Defaults to `-created_at`. + description: Returns machines with ID or name that match the given query. Uses exact match for machine ID and partial match for name. schema: type: string - default: '-created_at' + allowEmptyValue: true required: false - - $ref: '#/components/parameters/LimitParameter' - - $ref: '#/components/parameters/OffsetParameter' responses: '200': - $ref: '#/components/responses/Organizations' + $ref: '#/components/responses/Machine.List' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + post: + operationId: CreateMachine + x-speakeasy-group: machines + x-speakeasy-name-override: create + summary: Create a machine + description: Creates a new machine. + tags: + - Machines + requestBody: + content: + application/json: + schema: + type: object + required: + - name + properties: + name: + type: string + description: The name of the machine + minLength: 1 + maxLength: 255 + scoped_machines: + type: array + items: + type: string + description: Array of machine IDs that this machine will have access to. Maximum of 25 scopes per machine. + maxItems: 25 + responses: + '200': + $ref: '#/components/responses/Machine' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /machines/{machine_id}: + get: + operationId: GetMachine + x-speakeasy-group: machines + x-speakeasy-name-override: get + summary: Retrieve a machine + description: Returns the details of a machine. + tags: + - Machines + parameters: + - name: machine_id + in: path + description: The ID of the machine to retrieve + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/Machine' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + patch: + operationId: UpdateMachine + x-speakeasy-group: machines + x-speakeasy-name-override: update + summary: Update a machine + description: |- + Updates an existing machine. + Only the provided fields will be updated. + tags: + - Machines + parameters: + - name: machine_id + in: path + description: The ID of the machine to update + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The name of the machine + minLength: 1 + maxLength: 255 + responses: + '200': + $ref: '#/components/responses/Machine' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + delete: + operationId: DeleteMachine + x-speakeasy-group: machines + x-speakeasy-name-override: delete + summary: Delete a machine + description: Deletes a machine. + tags: + - Machines + parameters: + - name: machine_id + in: path + description: The ID of the machine to delete + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/Machine.Deleted' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /machines/{machine_id}/scopes: + post: + operationId: CreateMachineScope + x-speakeasy-group: machines + x-speakeasy-name-override: createScope + summary: Create a machine scope + description: |- + Creates a new machine scope, allowing the specified machine to access another machine. + Maximum of 25 scopes per machine. + tags: + - Machines + parameters: + - name: machine_id + in: path + description: The ID of the machine that will have access to another machine + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + required: + - to_machine_id + properties: + to_machine_id: + type: string + description: The ID of the machine that will be scoped to the current machine + responses: + '200': + $ref: '#/components/responses/MachineScope' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /machines/{machine_id}/scopes/{other_machine_id}: + delete: + operationId: DeleteMachineScope + x-speakeasy-group: machines + x-speakeasy-name-override: deleteScope + summary: Delete a machine scope + description: Deletes a machine scope, removing access from one machine to another. + tags: + - Machines + parameters: + - name: machine_id + in: path + description: The ID of the machine that has access to another machine + required: true + schema: + type: string + - name: other_machine_id + in: path + description: The ID of the machine that is being accessed + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/MachineScope.Deleted' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /organizations: + get: + operationId: ListOrganizations + x-speakeasy-group: organizations + x-speakeasy-name-override: list + summary: Get a list of organizations for an instance + description: |- + This request returns the list of organizations for an instance. + Results can be paginated using the optional `limit` and `offset` query parameters. + The organizations are ordered by descending creation date. + Most recent organizations will be returned first. + tags: + - Organizations + parameters: + - in: query + required: false + name: include_members_count + description: Flag to denote whether the member counts of each organization should be included in the response or not. + schema: + type: boolean + - in: query + required: false + name: include_missing_member_with_elevated_permissions + description: Flag to denote whether or not to include a member with elevated permissions who is not currently a member of the organization. + schema: + type: boolean + - in: query + required: false + name: query + description: |- + Returns organizations with ID, name, or slug that match the given query. + Uses exact match for organization ID and partial match for name and slug. + schema: + type: string + - in: query + name: user_id + description: |- + Returns organizations with the user ids specified. Any user ids not found are ignored. + For each user id, the `+` and `-` can be prepended to the id, which denote whether the + respective organization should be included or excluded from the result set. + schema: + type: array + items: + type: string + required: false + - in: query + name: organization_id + description: |- + Returns organizations with the organization ids specified. Any organization ids not found are ignored. + For each organization id, the `+` and `-` can be prepended to the id, which denote whether the + respective organization should be included or excluded from the result set. Accepts up to 100 organization ids. + Example: ?organization_id=+org_1&organization_id=-org_2 + schema: + type: array + items: + type: string + required: false + - in: query + name: order_by + description: |- + Allows to return organizations in a particular order. + At the moment, you can order the returned organizations either by their `name`, `created_at` or `members_count`. + In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. + For example, if you want organizations to be returned in descending order according to their `created_at` property, you can use `-created_at`. + If you don't use `+` or `-`, then `+` is implied. + Defaults to `-created_at`. + schema: + type: string + default: '-created_at' + required: false + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' + responses: + '200': + $ref: '#/components/responses/Organizations' '400': $ref: '#/components/responses/ClerkErrors' '403': @@ -4279,6 +4791,25 @@ paths: - pending - accepted - revoked + - in: query + required: false + name: email_address + description: Returns organization invitations inviting the specified email address. + schema: + type: string + - in: query + name: order_by + required: false + description: |- + Allows to return organization invitations in a particular order. + You can order the returned organization invitations either by their `created_at` or `email_address`. + In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. + For example, if you want organization invitations to be returned in descending order according to their `created_at` property, you can use `-created_at`. + If you don't use `+` or `-`, then `+` is implied. + Defaults to `-created_at`. + schema: + type: string + default: '-created_at' - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' responses: @@ -4288,6 +4819,8 @@ paths: $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' /organizations/{organization_id}/invitations/bulk: post: operationId: CreateOrganizationInvitationBulk @@ -4766,6 +5299,8 @@ paths: $ref: '#/components/responses/AuthenticationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' /organizations/{organization_id}/memberships/{user_id}/metadata: patch: operationId: UpdateOrganizationMembershipMetadata @@ -4978,6 +5513,86 @@ paths: $ref: '#/components/responses/AuthenticationInvalid' '404': $ref: '#/components/responses/ResourceNotFound' + /organization_domains: + get: + operationId: ListAllOrganizationDomains + x-speakeasy-group: organizationDomains + x-speakeasy-name-override: listAll + summary: List all organization domains + description: | + Retrieves a list of all organization domains within the current instance. + This endpoint can be used to list all domains across all organizations + or filter domains by organization, verification status, enrollment mode, or search query. + + The response includes pagination information and details about each domain + including its verification status, enrollment mode, and associated counts. + tags: + - Organization Domains + parameters: + - in: query + name: organization_id + description: The ID of the organization to filter domains by + required: false + schema: + type: string + - in: query + name: verified + description: Filter by verification status + required: false + schema: + type: string + enum: + - 'true' + - 'false' + - in: query + name: enrollment_mode + description: Filter by enrollment mode + required: false + style: form + explode: false + schema: + type: array + items: + type: string + enum: + - manual_invitation + - automatic_invitation + - automatic_suggestion + - in: query + name: query + description: | + Search domains by name or organization ID. + If the query starts with "org_", it will search by exact organization ID match. + Otherwise, it performs a case-insensitive partial match on the domain name. + + Note: An empty string or whitespace-only value is not allowed and will result in a validation error. + required: false + schema: + type: string + - in: query + name: order_by + description: | + Allows to return organization domains in a particular order. + At the moment, you can order the returned domains by their `name` or `created_at`. + In order to specify the direction, you can use the `+/-` symbols prepended to the property to order by. + For example, if you want domains to be returned in descending order according to their `created_at` property, you can use `-created_at`. + If you don't use `+` or `-`, then `+` is implied. + Defaults to `-created_at`. + required: false + schema: + type: string + default: '-created_at' + - $ref: '#/components/parameters/OffsetParameter' + - $ref: '#/components/parameters/LimitParameter' + responses: + '200': + $ref: '#/components/responses/OrganizationDomains' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' /proxy_checks: post: summary: Verify the proxy configuration for your domain @@ -5231,6 +5846,25 @@ paths: parameters: - $ref: '#/components/parameters/LimitParameter' - $ref: '#/components/parameters/OffsetParameter' + - name: order_by + in: query + description: |- + Allows to return OAuth applications in a particular order. + At the moment, you can order the returned OAuth applications by their `created_at` and `name`. + In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. + For example, if you want OAuth applications to be returned in descending order according to their `created_at` property, you can use `-created_at`. + If you don't use `+` or `-`, then `+` is implied. We only support one `order_by` parameter, and if multiple `order_by` parameters are provided, we will only keep the first one. For example, + if you pass `order_by=name&order_by=created_at`, we will consider only the first `order_by` parameter, which is `name`. The `created_at` parameter will be ignored in this case. + required: false + schema: + type: string + default: +created_at + - name: name_query + in: query + description: Returns OAuth applications with names that match the given query, via case-insensitive partial match. + required: false + schema: + type: string responses: '200': $ref: '#/components/responses/OAuthApplications' @@ -5281,6 +5915,16 @@ paths: default: profile email example: profile email public_metadata nullable: true + consent_screen_enabled: + type: boolean + default: true + description: True to enable a consent screen to display in the authentication flow. + nullable: true + pkce_required: + type: boolean + default: false + description: True to require the Proof Key of Code Exchange (PKCE) flow. + nullable: true public: type: boolean description: If true, this client is public and you can use the Proof Key of Code Exchange (PKCE) flow. @@ -5367,6 +6011,14 @@ paths: default: profile email example: profile email public_metadata private_metadata nullable: true + consent_screen_enabled: + type: boolean + description: True to enable a consent screen to display in the authentication flow. This cannot be disabled for dynamically registered OAuth Applications. + nullable: true + pkce_required: + type: boolean + description: True to require the Proof Key of Code Exchange (PKCE) flow. + nullable: true public: type: boolean description: If true, this client is public and you can use the Proof Key of Code Exchange (PKCE) flow. @@ -5504,7 +6156,13 @@ paths: description: The name to use as a label for this SAML Connection domain: type: string + deprecated: true description: The domain of your organization. Sign in flows using an email with this domain, will use this SAML Connection. + domains: + type: array + items: + type: string + description: The domains of your organization. Sign in flows using an email with one of these domains, will use this SAML Connection. provider: type: string description: The IdP provider of the connection. @@ -5553,8 +6211,12 @@ paths: type: string required: - name - - domain - provider + anyOf: + - required: + - domain + - required: + - domains responses: '200': $ref: '#/components/responses/SAMLConnection' @@ -5621,7 +6283,14 @@ paths: domain: type: string description: The domain to use for the new SAML Connection + deprecated: true nullable: true + domains: + type: array + items: + type: string + nullable: true + description: A list of the domains on use for the SAML connection idp_entity_id: type: string description: The entity id as provided by the IdP @@ -5870,6 +6539,148 @@ paths: $ref: '#/components/responses/AccountlessApplication' '500': $ref: '#/components/responses/ClerkErrors' + /oauth_applications/access_tokens/verify: + post: + x-speakeasy-group: oauthAccessTokens + x-speakeasy-name-override: verify + operationId: verifyOAuthAccessToken + summary: Verify an OAuth Access Token + tags: + - OAuth Access Tokens + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + access_token: + type: string + description: The access token to verify. + example: XXXXXXXXXXXXXX + secret: + type: string + description: The access token to verify. This is deprecated, use `access_token` instead. + deprecated: true + example: XXXXXXXXXXXXXX + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + object: + type: string + enum: + - clerk_idp_oauth_access_token + example: clerk_idp_oauth_access_token + id: + type: string + pattern: ^oat_[0-9A-Fa-f]{32}$ + example: oat_0ef5a7a33d87ed87ee7954c845d80450 + client_id: + type: string + example: client_2xhFjEI5X2qWRvtV13BzSj8H6Dk + subject: + type: string + pattern: ^user_\w{27}$ + example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk + scopes: + type: array + items: + type: string + example: + - read + - write + revoked: + type: boolean + example: false + revocation_reason: + type: string + nullable: true + example: Revoked by user + expired: + type: boolean + example: false + expiration: + type: number + nullable: true + example: 1716883200 + created_at: + type: number + example: 1716883200 + updated_at: + type: number + example: 1716883200 + required: + - object + - id + - client_id + - subject + - scopes + - revoked + - revocation_reason + - expired + - expiration + - created_at + - updated_at + additionalProperties: false + '400': + description: 400 Bad Request + content: + application/json: + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + example: Bad Request + long_message: + type: string + example: 'Invalid ''url_parameter.example'': Failed regex check' + code: + type: string + example: bad_request + required: + - message + - long_message + - code + required: + - errors + '404': + description: 404 Not Found + content: + application/json: + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + example: some details about the error + long_message: + type: string + example: some details about the error + code: + type: string + example: some_error_code + required: + - message + - long_message + - code + required: + - errors components: securitySchemes: bearerAuth: @@ -6149,17 +6960,97 @@ components: 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' + 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' + AWSCredential: + 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: + - aws_credential + access_key_id: + type: string + user_pool_ids: + type: array + items: + type: string + 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 + - access_key_id + - user_pool_ids + - created_at + - updated_at + ClerkError: + type: object + properties: + message: + type: string + long_message: + type: string + code: + type: string + meta: + type: object + clerk_trace_id: + type: string + 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 + DeletedObject: + type: object + additionalProperties: false + properties: + object: + type: string + id: + type: string + slug: + type: string + deleted: + type: boolean + required: + - object + - deleted SessionActivityResponse: type: object nullable: true @@ -6306,36 +7197,6 @@ components: - last_active_session_id - updated_at - created_at - ClerkError: - type: object - properties: - message: - type: string - long_message: - type: string - code: - type: string - meta: - type: object - clerk_trace_id: - type: string - 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 OTP: type: object additionalProperties: false @@ -6518,21 +7379,6 @@ components: - reserved - created_at - updated_at - DeletedObject: - type: object - additionalProperties: false - properties: - object: - type: string - id: - type: string - slug: - type: string - deleted: - type: boolean - required: - - object - - deleted PhoneNumber: type: object additionalProperties: false @@ -6661,6 +7507,9 @@ components: can_delete: type: boolean description: whether this template can be deleted + can_edit_body: + type: boolean + description: whether the body of this template can be edited can_toggle: type: boolean description: whether this template can be enabled or disabled, true only for notification SMS templates @@ -6944,6 +7793,9 @@ components: username: type: string nullable: true + phone_number: + type: string + nullable: true public_metadata: type: object additionalProperties: true @@ -7028,6 +7880,11 @@ components: type: string domain: type: string + deprecated: true + domains: + type: array + items: + type: string active: type: boolean provider: @@ -7053,12 +7910,16 @@ components: required: - id - name - - domain - active - provider - sync_user_attributes - created_at - updated_at + anyOf: + - required: + - domain + - required: + - domains SAMLAccount: type: object additionalProperties: false @@ -7270,9 +8131,9 @@ components: The hashing algorithm that was used to generate the password digest. The algorithms we support at the moment are [`bcrypt`](https://en.wikipedia.org/wiki/Bcrypt), [`bcrypt_sha256_django`](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/), [`md5`](https://en.wikipedia.org/wiki/MD5), `pbkdf2_sha1`, `pbkdf2_sha256`, [`pbkdf2_sha256_django`](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/), - [`phpass`](https://www.openwall.com/phpass/), [`scrypt_firebase`](https://firebaseopensource.com/projects/firebase/scrypt/), + [`phpass`](https://www.openwall.com/phpass/), `md5_phpass`, [`scrypt_firebase`](https://firebaseopensource.com/projects/firebase/scrypt/), [`scrypt_werkzeug`](https://werkzeug.palletsprojects.com/en/3.0.x/utils/#werkzeug.security.generate_password_hash), [`sha256`](https://en.wikipedia.org/wiki/SHA-2), - and the [`argon2`](https://argon2.online/) variants: `argon2i` and `argon2id`. + [`ldap_ssha`](https://www.openldap.org/faq/data/cache/347.html) and the [`argon2`](https://argon2.online/) variants: `argon2i` and `argon2id`. Each of the supported hashers expects the incoming digest to be in a particular format. See the [Clerk docs](https://clerk.com/docs/references/backend/user/create-user) for more information. TotalCount: @@ -7354,6 +8215,10 @@ components: type: string slug: type: string + image_url: + type: string + has_image: + type: boolean members_count: type: integer missing_member_with_elevated_permissions: @@ -7387,10 +8252,10 @@ components: - id - name - slug + - has_image - max_allowed_memberships - admin_delete_enabled - public_metadata - - private_metadata - created_at - updated_at OrganizationMembershipPublicUserData: @@ -7879,15 +8744,12 @@ components: type: boolean block_disposable_email_domains: type: boolean - ignore_dots_for_gmail_addresses: - type: boolean required: - object - allowlist - blocklist - block_email_subaddresses - block_disposable_email_domains - - ignore_dots_for_gmail_addresses OrganizationSettings: type: object additionalProperties: false @@ -7986,6 +8848,86 @@ components: - signing_algorithm - created_at - updated_at + MachineToken: + type: object + additionalProperties: false + properties: + object: + type: string + enum: + - token + jwt: + type: string + required: + - object + - jwt + MachineWithoutScopedMachines: + type: object + required: + - object + - id + - name + - instance_id + - created_at + - updated_at + properties: + object: + type: string + enum: + - machine + id: + type: string + description: Unique identifier for the machine. + name: + type: string + description: The name of the machine. + maxLength: 255 + minLength: 1 + instance_id: + type: string + description: The ID of the instance this machine belongs to. + created_at: + type: integer + format: int64 + description: Unix timestamp of creation. + updated_at: + type: integer + format: int64 + description: Unix timestamp of last update. + Machine: + allOf: + - $ref: '#/components/schemas/MachineWithoutScopedMachines' + - type: object + required: + - scoped_machines + properties: + scoped_machines: + type: array + items: + $ref: '#/components/schemas/MachineWithoutScopedMachines' + description: Array of machines this machine has access to. + MachineScope: + type: object + required: + - object + - from_machine_id + - to_machine_id + - created_at + properties: + object: + type: string + enum: + - machine_scope + from_machine_id: + type: string + description: The ID of the machine that has access to the target machine. + to_machine_id: + type: string + description: The ID of the machine that is being accessed. + created_at: + type: integer + format: int64 + description: Unix timestamp of creation. Organizations: type: object additionalProperties: false @@ -8462,6 +9404,18 @@ components: type: string client_id: type: string + client_uri: + type: string + nullable: true + client_image_url: + type: string + nullable: true + dynamically_registered: + type: boolean + consent_screen_enabled: + type: boolean + pkce_required: + type: boolean public: type: boolean scopes: @@ -8500,8 +9454,13 @@ components: - id - instance_id - name + - dynamically_registered + - consent_screen_enabled + - pkce_required - public - client_id + - client_uri + - client_image_url - scopes - redirect_uris - callback_url @@ -8567,6 +9526,11 @@ components: type: string domain: type: string + deprecated: true + domains: + type: array + items: + type: string idp_entity_id: type: string nullable: true @@ -8621,7 +9585,6 @@ components: - object - id - name - - domain - idp_entity_id - idp_sso_url - idp_certificate @@ -8634,6 +9597,11 @@ components: - sync_user_attributes - created_at - updated_at + anyOf: + - required: + - domain + - required: + - domains SAMLConnections: type: object additionalProperties: false @@ -8744,14 +9712,20 @@ components: application/json: schema: $ref: '#/components/schemas/JWKS' - Client.List: + AWSCredential.List: description: Success content: application/json: schema: type: array items: - $ref: '#/components/schemas/Client' + $ref: '#/components/schemas/AWSCredential' + AWSCredential: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/AWSCredential' ClerkErrors: description: Request was not successful content: @@ -8764,48 +9738,56 @@ components: application/json: schema: $ref: '#/components/schemas/ClerkErrors' - DeprecatedEndpoint: - description: The endpoint is considered deprecated and is pending removal. + AuthorizationInvalid: + description: Authorization invalid content: application/json: schema: $ref: '#/components/schemas/ClerkErrors' - UnprocessableEntity: - description: Invalid request parameters + ResourceNotFound: + description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ClerkErrors' - Client: - description: Success + UnprocessableEntity: + description: Invalid request parameters content: application/json: schema: - $ref: '#/components/schemas/Client' - ResourceNotFound: - description: Resource not found + $ref: '#/components/schemas/ClerkErrors' + DeletedObject: + description: Deleted Object content: application/json: schema: - $ref: '#/components/schemas/ClerkErrors' - EmailAddress: + $ref: '#/components/schemas/DeletedObject' + Client.List: description: Success content: application/json: schema: - $ref: '#/components/schemas/EmailAddress' - AuthorizationInvalid: - description: Authorization invalid + type: array + items: + $ref: '#/components/schemas/Client' + DeprecatedEndpoint: + description: The endpoint is considered deprecated and is pending removal. content: application/json: schema: $ref: '#/components/schemas/ClerkErrors' - DeletedObject: - description: Deleted Object + Client: + description: Success content: application/json: schema: - $ref: '#/components/schemas/DeletedObject' + $ref: '#/components/schemas/Client' + EmailAddress: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/EmailAddress' PhoneNumber: description: Success content: @@ -9027,6 +10009,99 @@ components: application/json: schema: $ref: '#/components/schemas/JWTTemplate' + MachineToken: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/MachineToken' + Machine.List: + description: Success + content: + application/json: + schema: + type: object + required: + - data + - total_count + properties: + data: + type: array + items: + $ref: '#/components/schemas/Machine' + total_count: + type: integer + description: Total number of machines + Machine: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/Machine' + Machine.Deleted: + description: Success + content: + application/json: + schema: + type: object + required: + - object + - id + - deleted + properties: + object: + type: string + enum: + - machine + description: String representing the object's type. + id: + type: string + description: The ID of the deleted machine + deleted: + type: boolean + enum: + - true + description: Whether the machine was successfully deleted + MachineScope: + description: Machine scope created successfully for a machine + content: + application/json: + schema: + $ref: '#/components/schemas/MachineScope' + Conflict: + description: Conflict + content: + application/json: + schema: + $ref: '#/components/schemas/ClerkErrors' + MachineScope.Deleted: + description: Machine scope deleted successfully for a machine + content: + application/json: + schema: + type: object + required: + - object + - from_machine_id + - to_machine_id + - deleted + properties: + object: + type: string + enum: + - machine_scope + description: String representing the object's type. + from_machine_id: + type: string + description: The ID of the machine that had access to the target machine + to_machine_id: + type: string + description: The ID of the machine that was being accessed + deleted: + type: boolean + enum: + - true + description: Whether the machine scope was successfully deleted Organizations: description: A list of organizations content: diff --git a/bapi/2025-04-10.yml b/bapi/2025-04-10.yml new file mode 100644 index 0000000..d89df99 --- /dev/null +++ b/bapi/2025-04-10.yml @@ -0,0 +1,10510 @@ +openapi: 3.0.3 +info: + title: Clerk Backend API + x-logo: + url: https://clerk.com/_next/image?url=%2Fimages%2Fclerk-logo.svg&w=96&q=75 + altText: Clerk docs + href: https://clerk.com/docs + contact: + email: support@clerk.com + name: Clerk Platform Team + url: https://clerk.com/support + description: |- + The Clerk REST Backend API, meant to be accessed by backend servers. + + ### Versions + + When the API changes in a way that isn't compatible with older versions, a new version is released. + Each version is identified by its release date, e.g. `2025-04-10`. For more information, please see [Clerk API Versions](https://clerk.com/docs/versioning/available-versions). + + Please see https://clerk.com/docs for more information. + version: '2025-04-10' + termsOfService: https://clerk.com/terms + license: + name: MIT + url: https://github.com/clerk/openapi-specs/blob/main/LICENSE +servers: + - url: https://api.clerk.com/v1 +security: + - bearerAuth: [] +tags: + - name: Actor Tokens + description: Allow your users to sign in on behalf of other users. + externalDocs: + url: https://clerk.com/docs/authentication/user-impersonation#actor-tokens + - name: Allow-list / Block-list + description: |- + Allow-lists and Block-lists allow you to control who can sign up or sign in + to your application, by restricting access based on the user's email + address or phone number. + externalDocs: + url: https://clerk.com/docs/authentication/allowlist + - name: Clients + description: The Client object tracks sessions, as well as the state of any sign in and sign up attempts, for a given device. + externalDocs: + url: https://clerk.com/docs/reference/clerkjs/client + - name: Domains + description: Domains represent each instance's URLs and DNS setup. + - name: Email Addresses + description: A user can be associated with one or more email addresses, which allows them to be contacted via email. + externalDocs: + url: https://clerk.com/docs/reference/clerkjs/emailaddress + - name: Email & SMS Templates + description: Email & SMS templates allow you to customize the theming and wording of emails & SMS messages that are sent by your instance. + externalDocs: + url: https://clerk.com/docs/authentication/email-sms-templates + - name: Instance Settings + description: Modify the settings of your instance. + - name: Invitations + description: Invitations allow you to invite someone to sign up to your application, via email. + externalDocs: + url: https://clerk.com/docs/authentication/invitations + - name: JWKS + description: Retrieve the JSON Web Key Set which can be used to verify the token signatures of the instance. + - name: JWT Templates + description: |- + JWT Templates allow you to generate custom authentication tokens + tied to authenticated sessions, enabling you to integrate with third-party + services. + externalDocs: + url: https://clerk.com/docs/request-authentication/jwt-templates + - name: OAuth Applications + description: OAuth applications contain data for clients using Clerk as an OAuth2 identity provider. + - name: OAuth Access Tokens + description: Endpoints for managing OAuth Access Tokens, which are credentials to access protected resources on behalf of a user. + - name: Organizations + description: Organizations are used to group members under a common entity and provide shared access to resources. + externalDocs: + url: https://clerk.com/docs/organizations/overview + - name: Organization Invitations + description: Invite users to an organization. + externalDocs: + url: https://clerk.com/docs/organizations/invite-users + - name: Organization Memberships + description: Manage member roles in an organization. + externalDocs: + url: https://clerk.com/docs/organizations/manage-member-roles + - name: Phone Numbers + description: A user can be associated with one or more phone numbers, which allows them to be contacted via SMS. + externalDocs: + url: https://clerk.com/docs/reference/clerkjs/phonenumber + - name: Redirect URLs + description: |- + Redirect URLs are whitelisted URLs that facilitate secure authentication flows in native applications (e.g. React Native, Expo). + In these contexts, Clerk ensures that security-critical nonces are passed only to the whitelisted URLs. + - name: SAML Connections + description: |- + A SAML Connection holds configuration data required for facilitating a SAML SSO flow between your + Clerk Instance (SP) and a particular SAML IdP. + - name: Sessions + description: |- + The Session object is an abstraction over an HTTP session. + It models the period of information exchange between a user and the server. + Sessions are created when a user successfully goes through the sign in or sign up flows. + externalDocs: + url: https://clerk.com/docs/reference/clerkjs/session + - name: Machines + description: A Machine represents a machine/server/service which can be used in machine-to-machine authentication. + - name: Sign-in Tokens + description: |- + Sign-in tokens are JWTs that can be used to sign in to an application without specifying any credentials. + A sign-in token can be used at most once and they can be consumed from the Frontend API using the `ticket` strategy. + - name: Sign Ups + description: Sign-up objects track the progress of a sign-up attempt and store any field collected from user input. + externalDocs: + url: https://clerk.com/docs/reference/clerkjs/signup + - name: Testing Tokens + description: Tokens meant for use by end-to-end test suites in requests to the Frontend API, so as to bypass bot detection measures. + externalDocs: + url: https://clerk.com/docs/testing/overview#testing-tokens + - name: Users + description: The user object represents a user that has successfully signed up to your application. + externalDocs: + url: https://clerk.com/docs/reference/clerkjs/user + - name: Webhooks + description: You can configure webhooks to be notified about various events that happen on your instance. + externalDocs: + url: https://clerk.com/docs/integration/webhooks + - name: Miscellaneous + description: Various endpoints that do not belong in any particular category. + - name: Beta Features + description: Modify instance settings that are currently in beta. + - name: Waitlist Entries + description: Manage waitlist entries. + - name: Proxy Checks + description: Check if a user is using a proxy. + - name: Organization Domains + description: Manage organization domains. + - name: Accountless Applications + description: Create and complete accountless applications. Note that this is an experimental feature and subject to change or be removed without notice. +externalDocs: + url: https://clerk.com/docs +paths: + /public/interstitial: + get: + operationId: GetPublicInterstitial + x-speakeasy-group: miscellaneous + x-speakeasy-name-override: getPublicInterstitial + security: [] + summary: Returns the markup for the interstitial page + description: |- + The Clerk interstitial endpoint serves an html page that loads clerk.js in order to check the user's authentication state. + It is used by Clerk SDKs when the user's authentication state cannot be immediately determined. + tags: + - Miscellaneous + parameters: + - name: frontendApi + deprecated: true + in: query + required: false + description: Please use `frontend_api` instead + schema: + type: string + - name: frontend_api + in: query + required: false + description: The Frontend API key of your instance + schema: + type: string + - name: publishable_key + in: query + required: false + description: The publishable key of your instance + schema: + type: string + - name: proxy_url + in: query + required: false + description: The proxy URL of your instance + schema: + type: string + - name: domain + in: query + required: false + description: The domain of your instance + schema: + type: string + - name: sign_in_url + in: query + required: false + description: The sign in URL of your instance + schema: + type: string + - name: use_domain_for_script + in: query + required: false + description: Whether to use the domain for the script URL + schema: + type: boolean + responses: + '200': + description: The interstitial page markup + '400': + description: A required query parameter is missing + '500': + description: An infinite redirect loop was detected + /jwks: + get: + operationId: GetJWKS + x-speakeasy-group: jwks + x-speakeasy-name-override: getJWKS + summary: Retrieve the JSON Web Key Set of the instance + description: Retrieve the JSON Web Key Set of the instance + tags: + - JWKS + responses: + '200': + $ref: '#/components/responses/WellKnown.JWKS' + /aws_credentials: + x-internal: true + get: + operationId: GetAWSCredentialList + x-speakeasy-group: awsCredentials + x-speakeasy-name-override: list + tags: + - AWS Credentials + summary: List all AWS Credentials + description: Returns a list of all AWS Credentials. + responses: + '200': + $ref: '#/components/responses/AWSCredential.List' + post: + operationId: CreateAWSCredential + x-speakeasy-group: awsCredentials + x-speakeasy-name-override: create + tags: + - AWS Credentials + summary: Create an AWS Credential + description: Create a new AWS Credential + requestBody: + content: + application/json: + schema: + type: object + properties: + access_key_id: + type: string + description: The Access Key ID from AWS + secret_access_key: + type: string + description: The Secret Access Key from AWS. + user_pool_ids: + type: array + items: + type: string + description: The User Pool IDs from AWS. + required: + - access_key_id + - secret_access_key + - user_pool_ids + responses: + '200': + $ref: '#/components/responses/AWSCredential' + '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' + /aws_credentials/{id}: + x-internal: true + get: + operationId: GetAWSCredential + x-speakeasy-group: awsCredentials + x-speakeasy-name-override: get + tags: + - AWS Credentials + summary: Retrieve an AWS Credential + description: Returns the details of an AWS Credential. + parameters: + - name: id + in: path + description: The ID of the AWS Credential to retrieve + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/AWSCredential' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + delete: + operationId: DeleteAWSCredential + x-speakeasy-group: awsCredentials + x-speakeasy-name-override: delete + tags: + - AWS Credentials + summary: Delete an AWS Credential + description: Delete the AWS Credential with the given ID + parameters: + - name: id + in: path + description: The ID of the AWS Credential to delete + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/DeletedObject' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + patch: + operationId: UpdateAWSCredential + x-speakeasy-group: awsCredentials + x-speakeasy-name-override: update + tags: + - AWS Credentials + summary: Update an AWS Credential + description: Updates an AWS credential. + parameters: + - name: id + in: path + description: The ID of the AWS Credential to update + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + access_key_id: + type: string + nullable: true + user_pool_ids: + type: array + items: + type: string + secret_access_key: + type: string + nullable: true + responses: + '200': + $ref: '#/components/responses/AWSCredential' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + /clients: + get: + deprecated: true + operationId: GetClientList + x-speakeasy-group: clients + x-speakeasy-name-override: list + tags: + - Clients + summary: List all clients + description: |- + Returns a list of all clients. The clients are returned sorted by creation date, + with the newest clients appearing first. + Warning: the endpoint is being deprecated and will be removed in future versions. + parameters: + - $ref: '#/components/parameters/Paginated' + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' + responses: + '200': + $ref: '#/components/responses/Client.List' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '410': + $ref: '#/components/responses/DeprecatedEndpoint' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /clients/verify: + post: + operationId: VerifyClient + x-speakeasy-group: clients + x-speakeasy-name-override: verify + tags: + - Clients + summary: Verify a client + description: Verifies the client in the provided token + requestBody: + description: Parameters. + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + token: + type: string + description: A JWT that represents the active client. + required: + - token + responses: + '200': + $ref: '#/components/responses/Client' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + /clients/{client_id}: + get: + operationId: GetClient + x-speakeasy-group: clients + x-speakeasy-name-override: get + tags: + - Clients + summary: Get a client + description: Returns the details of a client. + parameters: + - name: client_id + in: path + description: Client ID. + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/Client' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + /clients/handshake_payload: {} + /email_addresses: + post: + operationId: CreateEmailAddress + x-speakeasy-group: emailAddresses + x-speakeasy-name-override: create + tags: + - Email Addresses + summary: Create an email address + description: Create a new email address + requestBody: + content: + application/json: + schema: + type: object + properties: + user_id: + type: string + description: The ID representing the user + email_address: + type: string + description: The new email address. Must adhere to the RFC 5322 specification for email address format. + verified: + type: boolean + description: When created, the email address will be marked as verified. + nullable: true + primary: + type: boolean + description: |- + Create this email address as the primary email address for the user. + Default: false, unless it is the first email address. + nullable: true + required: + - user_id + - email_address + responses: + '200': + $ref: '#/components/responses/EmailAddress' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /email_addresses/{email_address_id}: + get: + operationId: GetEmailAddress + x-speakeasy-group: emailAddresses + x-speakeasy-name-override: get + x-speakeasy-usage-example: true + tags: + - Email Addresses + summary: Retrieve an email address + description: Returns the details of an email address. + parameters: + - name: email_address_id + in: path + description: The ID of the email address to retrieve + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/EmailAddress' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + delete: + operationId: DeleteEmailAddress + x-speakeasy-group: emailAddresses + x-speakeasy-name-override: delete + tags: + - Email Addresses + summary: Delete an email address + description: Delete the email address with the given ID + parameters: + - name: email_address_id + in: path + description: The ID of the email address to delete + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/DeletedObject' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + patch: + operationId: UpdateEmailAddress + x-speakeasy-group: emailAddresses + x-speakeasy-name-override: update + tags: + - Email Addresses + summary: Update an email address + description: Updates an email address. + parameters: + - name: email_address_id + in: path + description: The ID of the email address to update + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + verified: + type: boolean + description: The email address will be marked as verified. + nullable: true + primary: + type: boolean + description: Set this email address as the primary email address for the user. + nullable: true + responses: + '200': + $ref: '#/components/responses/EmailAddress' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + /phone_numbers: + post: + operationId: CreatePhoneNumber + x-speakeasy-group: phoneNumbers + x-speakeasy-name-override: create + tags: + - Phone Numbers + summary: Create a phone number + description: Create a new phone number + requestBody: + content: + application/json: + schema: + type: object + properties: + user_id: + type: string + description: The ID representing the user + phone_number: + type: string + description: The new phone number. Must adhere to the E.164 standard for phone number format. + verified: + type: boolean + description: When created, the phone number will be marked as verified. + nullable: true + primary: + type: boolean + description: 'Create this phone number as the primary phone number for the user. Default: false, unless it is the first phone number.' + nullable: true + reserved_for_second_factor: + type: boolean + description: |- + Create this phone number as reserved for multi-factor authentication. The phone number must also be verified. + If there are no other reserved second factors, the phone number will be set as the default second factor. + nullable: true + required: + - user_id + - phone_number + responses: + '200': + $ref: '#/components/responses/PhoneNumber' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /phone_numbers/{phone_number_id}: + get: + operationId: GetPhoneNumber + x-speakeasy-group: phoneNumbers + x-speakeasy-name-override: get + tags: + - Phone Numbers + summary: Retrieve a phone number + description: Returns the details of a phone number + parameters: + - name: phone_number_id + in: path + description: The ID of the phone number to retrieve + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/PhoneNumber' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + delete: + operationId: DeletePhoneNumber + x-speakeasy-group: phoneNumbers + x-speakeasy-name-override: delete + tags: + - Phone Numbers + summary: Delete a phone number + description: Delete the phone number with the given ID + parameters: + - name: phone_number_id + in: path + description: The ID of the phone number to delete + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/DeletedObject' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + patch: + operationId: UpdatePhoneNumber + x-speakeasy-group: phoneNumbers + x-speakeasy-name-override: update + tags: + - Phone Numbers + summary: Update a phone number + description: Updates a phone number + parameters: + - name: phone_number_id + in: path + description: The ID of the phone number to update + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + verified: + type: boolean + description: The phone number will be marked as verified. + nullable: true + primary: + type: boolean + description: Set this phone number as the primary phone number for the user. + nullable: true + reserved_for_second_factor: + type: boolean + description: |- + Set this phone number as reserved for multi-factor authentication. + The phone number must also be verified. + If there are no other reserved second factors, the phone number will be set as the default second factor. + nullable: true + responses: + '200': + $ref: '#/components/responses/PhoneNumber' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + /sessions: + get: + operationId: GetSessionList + x-speakeasy-group: sessions + x-speakeasy-name-override: list + tags: + - Sessions + summary: List all sessions + description: |- + Returns a list of all sessions. + The sessions are returned sorted by creation date, with the newest sessions appearing first. + **Deprecation Notice (2024-01-01):** All parameters were initially considered optional, however + moving forward at least one of `client_id` or `user_id` parameters should be provided. + parameters: + - name: client_id + in: query + required: false + description: List sessions for the given client + schema: + type: string + - name: user_id + in: query + required: false + description: List sessions for the given user + schema: + type: string + - name: status + in: query + required: false + description: Filter sessions by the provided status + schema: + type: string + enum: + - abandoned + - active + - ended + - expired + - removed + - replaced + - revoked + - $ref: '#/components/parameters/Paginated' + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' + responses: + '200': + $ref: '#/components/responses/Session.List' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + post: + operationId: createSession + x-speakeasy-group: sessions + x-speakeasy-name-override: create + tags: + - Sessions + summary: Create a new active session + description: |- + Create a new active session for the provided user ID. + + **This operation is intended only for use in testing, and is not available for production instances.** If you are looking to generate a user session from the backend, + we recommend using the [Sign-in Tokens](https://clerk.com/docs/reference/backend-api/tag/Sign-in-Tokens#operation/CreateSignInToken) resource instead. + requestBody: + content: + application/json: + schema: + type: object + properties: + user_id: + type: string + description: The ID representing the user + required: + - user_id + responses: + '200': + $ref: '#/components/responses/Session' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '404': + $ref: '#/components/responses/ClerkErrors' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /sessions/{session_id}: + get: + operationId: GetSession + x-speakeasy-group: sessions + x-speakeasy-name-override: get + tags: + - Sessions + summary: Retrieve a session + description: Retrieve the details of a session + parameters: + - name: session_id + in: path + description: The ID of the session + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/Session' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + /sessions/{session_id}/refresh: + post: + operationId: RefreshSession + x-speakeasy-group: sessions + x-speakeasy-name-override: refresh + tags: + - Sessions + summary: Refresh a session + description: |- + Refreshes a session by creating a new session token. A 401 is returned when there + are validation errors, which signals the SDKs to fallback to the handshake flow. + parameters: + - name: session_id + in: path + description: The ID of the session + required: true + schema: + type: string + requestBody: + description: Refresh session parameters + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + expired_token: + type: string + description: |- + The JWT that is sent via the `__session` cookie from your frontend. + Note: this JWT must be associated with the supplied session ID. + refresh_token: + type: string + description: The JWT that is sent via the `__session` cookie from your frontend. + request_origin: + type: string + description: The origin of the request. + request_headers: + type: object + additionalProperties: true + description: The headers of the request. + nullable: true + format: + type: string + description: The format of the response. + nullable: true + default: token + enum: + - token + - cookie + request_originating_ip: + type: string + description: The IP address of the request. + nullable: true + required: + - expired_token + - refresh_token + - request_origin + responses: + '200': + $ref: '#/components/responses/Session.Refresh' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + /sessions/{session_id}/revoke: + post: + operationId: RevokeSession + x-speakeasy-group: sessions + x-speakeasy-name-override: revoke + tags: + - Sessions + summary: Revoke a session + description: |- + Sets the status of a session as "revoked", which is an unauthenticated state. + In multi-session mode, a revoked session will still be returned along with its client object, however the user will need to sign in again. + parameters: + - name: session_id + in: path + description: The ID of the session + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/Session' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + /sessions/{session_id}/tokens: + post: + operationId: CreateSessionToken + x-speakeasy-group: sessions + x-speakeasy-name-override: createToken + tags: + - Sessions + summary: Create a session token + description: Creates a session JSON Web Token (JWT) based on a session. + parameters: + - name: session_id + in: path + description: The ID of the session + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + expires_in_seconds: + type: number + minimum: 30 + maximum: 315360000 + description: Use this parameter to override the default session token lifetime. + nullable: true + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + object: + type: string + enum: + - token + jwt: + type: string + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + /sessions/{session_id}/tokens/{template_name}: + post: + operationId: CreateSessionTokenFromTemplate + x-speakeasy-group: sessions + x-speakeasy-name-override: createTokenFromTemplate + tags: + - Sessions + summary: Create a session token from a jwt template + description: Creates a JSON Web Token(JWT) based on a session and a JWT Template name defined for your instance + parameters: + - name: session_id + in: path + description: The ID of the session + required: true + schema: + type: string + - name: template_name + in: path + description: The name of the JWT Template defined in your instance (e.g. `custom_hasura`). + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + expires_in_seconds: + type: number + minimum: 30 + maximum: 315360000 + description: Use this parameter to override the JWT token lifetime. + nullable: true + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + properties: + object: + type: string + enum: + - token + jwt: + type: string + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + /templates/{template_type}: + get: + deprecated: true + operationId: GetTemplateList + x-speakeasy-group: emailSMSTemplates + x-speakeasy-name-override: list + summary: List all templates + description: |- + Returns a list of all templates. + The templates are returned sorted by position. + tags: + - Email & SMS Templates + parameters: + - name: template_type + in: path + description: The type of templates to list (email or SMS) + required: true + schema: + type: string + enum: + - email + - sms + - $ref: '#/components/parameters/Paginated' + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' + responses: + '200': + $ref: '#/components/responses/Template.List' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /templates/{template_type}/{slug}: + get: + deprecated: true + operationId: GetTemplate + x-speakeasy-group: emailSMSTemplates + x-speakeasy-name-override: get + summary: Retrieve a template + description: Returns the details of a template + tags: + - Email & SMS Templates + parameters: + - name: template_type + in: path + description: The type of templates to retrieve (email or SMS) + required: true + schema: + type: string + enum: + - email + - sms + - name: slug + in: path + description: The slug (i.e. machine-friendly name) of the template to retrieve + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/Template' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + put: + deprecated: true + operationId: UpsertTemplate + x-speakeasy-group: emailAndSmsTemplates + x-speakeasy-name-override: upsert + summary: Update a template for a given type and slug + description: Updates the existing template of the given type and slug + tags: + - Email & SMS Templates + parameters: + - name: template_type + in: path + description: The type of template to update + required: true + schema: + type: string + enum: + - email + - sms + - name: slug + in: path + description: The slug of the template to update + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + name: + type: string + description: The user-friendly name of the template + subject: + type: string + description: |- + The email subject. + Applicable only to email templates. + nullable: true + markup: + type: string + description: The editor markup used to generate the body of the template + nullable: true + body: + type: string + description: The template body before variable interpolation + delivered_by_clerk: + type: boolean + description: Whether Clerk should deliver emails or SMS messages based on the current template + nullable: true + from_email_name: + type: string + description: |- + The local part of the From email address that will be used for emails. + For example, in the address 'hello@example.com', the local part is 'hello'. + Applicable only to email templates. + reply_to_email_name: + type: string + description: |- + The local part of the Reply To email address that will be used for emails. + For example, in the address 'hello@example.com', the local part is 'hello'. + Applicable only to email templates. + responses: + '200': + $ref: '#/components/responses/Template' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '402': + $ref: '#/components/responses/PaymentRequired' + '403': + $ref: '#/components/responses/ClerkErrors' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /templates/{template_type}/{slug}/revert: + post: + deprecated: true + operationId: RevertTemplate + x-speakeasy-group: emailSMSTemplates + x-speakeasy-name-override: revert + summary: Revert a template + description: Reverts an updated template to its default state + tags: + - Email & SMS Templates + parameters: + - name: template_type + in: path + description: The type of template to revert + required: true + schema: + type: string + enum: + - email + - sms + - name: slug + in: path + description: The slug of the template to revert + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/Template' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '402': + $ref: '#/components/responses/PaymentRequired' + '404': + $ref: '#/components/responses/ResourceNotFound' + /templates/{template_type}/{slug}/preview: + post: + deprecated: true + operationId: PreviewTemplate + x-speakeasy-group: templates + x-speakeasy-name-override: preview + summary: Preview changes to a template + description: Returns a preview of a template for a given template_type, slug and body + tags: + - Email & SMS Templates + parameters: + - name: template_type + in: path + description: The type of template to preview + required: true + schema: + type: string + - name: slug + in: path + description: The slug of the template to preview + required: true + schema: + type: string + requestBody: + description: Required parameters + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + subject: + type: string + description: |- + The email subject. + Applicable only to email templates. + nullable: true + body: + type: string + description: The template body before variable interpolation + from_email_name: + type: string + description: |- + The local part of the From email address that will be used for emails. + For example, in the address 'hello@example.com', the local part is 'hello'. + Applicable only to email templates. + reply_to_email_name: + type: string + description: |- + The local part of the Reply To email address that will be used for emails. + For example, in the address 'hello@example.com', the local part is 'hello'. + Applicable only to email templates. + responses: + '200': + description: OK + content: + application/json: + schema: + type: object + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /templates/{template_type}/{slug}/toggle_delivery: + post: + deprecated: true + operationId: ToggleTemplateDelivery + x-speakeasy-group: emailSMSTemplates + x-speakeasy-name-override: toggleTemplateDelivery + summary: Toggle the delivery by Clerk for a template of a given type and slug + description: |- + Toggles the delivery by Clerk for a template of a given type and slug. + If disabled, Clerk will not deliver the resulting email or SMS. + The app developer will need to listen to the `email.created` or `sms.created` webhooks in order to handle delivery themselves. + tags: + - Email & SMS Templates + parameters: + - name: template_type + in: path + description: The type of template to toggle delivery for + required: true + schema: + type: string + enum: + - email + - sms + - name: slug + in: path + description: The slug of the template for which to toggle delivery + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + delivered_by_clerk: + type: boolean + description: Whether Clerk should deliver emails or SMS messages based on the current template + responses: + '200': + $ref: '#/components/responses/Template' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + /users: + get: + operationId: GetUserList + x-speakeasy-group: users + x-speakeasy-name-override: list + summary: List all users + description: |- + Returns a list of all users. + The users are returned sorted by creation date, with the newest users appearing first. + tags: + - Users + parameters: + - name: email_address + in: query + schema: + type: array + items: + type: string + description: |- + Returns users with the specified email addresses. + Accepts up to 100 email addresses. + Any email addresses not found are ignored. + required: false + - name: phone_number + in: query + schema: + type: array + items: + type: string + description: |- + Returns users with the specified phone numbers. + Accepts up to 100 phone numbers. + Any phone numbers not found are ignored. + required: false + - name: external_id + in: query + schema: + type: array + items: + type: string + description: |- + Returns users with the specified external ids. + For each external id, the `+` and `-` can be + prepended to the id, which denote whether the + respective external id should be included or + excluded from the result set. + Accepts up to 100 external ids. + Any external ids not found are ignored. + required: false + - name: username + in: query + schema: + type: array + items: + type: string + description: |- + Returns users with the specified usernames. + Accepts up to 100 usernames. + Any usernames not found are ignored. + required: false + - name: web3_wallet + in: query + schema: + type: array + items: + type: string + description: |- + Returns users with the specified web3 wallet addresses. + Accepts up to 100 web3 wallet addresses. + Any web3 wallet addressed not found are ignored. + required: false + - name: user_id + in: query + schema: + type: array + items: + type: string + description: |- + Returns users with the user ids specified. + For each user id, the `+` and `-` can be + prepended to the id, which denote whether the + respective user id should be included or + excluded from the result set. + Accepts up to 100 user ids. + Any user ids not found are ignored. + required: false + - name: organization_id + in: query + schema: + type: array + items: + type: string + description: |- + Returns users that have memberships to the + given organizations. + For each organization id, the `+` and `-` can be + prepended to the id, which denote whether the + respective organization should be included or + excluded from the result set. + Accepts up to 100 organization ids. + required: false + - name: query + in: query + description: |- + Returns users that match the given query. + For possible matches, we check the email addresses, phone numbers, usernames, web3 wallets, user ids, first and last names. + The query value doesn't need to match the exact value you are looking for, it is capable of partial matches as well. + schema: + type: string + required: false + - name: email_address_query + in: query + description: |- + Returns users with emails that match the given query, via case-insensitive partial match. + For example, `email_address_query=ello` will match a user with the email `HELLO@example.com`. + schema: + type: string + required: false + - name: phone_number_query + in: query + description: |- + Returns users with phone numbers that match the given query, via case-insensitive partial match. + For example, `phone_number_query=555` will match a user with the phone number `+1555xxxxxxx`. + schema: + type: string + required: false + - name: username_query + in: query + description: |- + Returns users with usernames that match the given query, via case-insensitive partial match. + For example, `username_query=CoolUser` will match a user with the username `SomeCoolUser`. + schema: + type: string + - name: name_query + in: query + description: Returns users with names that match the given query, via case-insensitive partial match. + schema: + type: string + - name: banned + in: query + required: false + description: Returns users which are either banned (`banned=true`) or not banned (`banned=false`). + schema: + type: boolean + - name: last_active_at_before + in: query + description: |- + Returns users whose last session activity was before the given date (with millisecond precision). + Example: use 1700690400000 to retrieve users whose last session activity was before 2023-11-23. + example: 1700690400000 + schema: + type: integer + - name: last_active_at_after + in: query + description: |- + Returns users whose last session activity was after the given date (with millisecond precision). + Example: use 1700690400000 to retrieve users whose last session activity was after 2023-11-23. + example: 1700690400000 + schema: + type: integer + - name: last_active_at_since + in: query + deprecated: true + description: |- + Returns users that had session activity since the given date. + Example: use 1700690400000 to retrieve users that had session activity from 2023-11-23 until the current day. + Deprecated in favor of `last_active_at_after`. + example: 1700690400000 + schema: + type: integer + - name: created_at_before + in: query + description: |- + Returns users who have been created before the given date (with millisecond precision). + Example: use 1730160000000 to retrieve users who have been created before 2024-10-29. + example: 1730160000000 + schema: + type: integer + - name: created_at_after + in: query + description: |- + Returns users who have been created after the given date (with millisecond precision). + Example: use 1730160000000 to retrieve users who have been created after 2024-10-29. + example: 1730160000000 + schema: + type: integer + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' + - name: order_by + in: query + description: |- + Allows to return users in a particular order. + At the moment, you can order the returned users by their `created_at`,`updated_at`,`email_address`,`web3wallet`,`first_name`,`last_name`,`phone_number`,`username`,`last_active_at`,`last_sign_in_at`. + In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. + For example, if you want users to be returned in descending order according to their `created_at` property, you can use `-created_at`. + If you don't use `+` or `-`, then `+` is implied. We only support one `order_by` parameter, and if multiple `order_by` parameters are provided, we will only keep the first one. For example, + if you pass `order_by=username&order_by=created_at`, we will consider only the first `order_by` parameter, which is `username`. The `created_at` parameter will be ignored in this case. + schema: + type: string + default: '-created_at' + required: false + responses: + '200': + $ref: '#/components/responses/User.List' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + post: + operationId: CreateUser + x-speakeasy-group: users + x-speakeasy-name-override: create + summary: Create a new user + description: |- + Creates a new user. Your user management settings determine how you should setup your user model. + + Any email address and phone number created using this method will be marked as verified. + + Note: If you are performing a migration, check out our guide on [zero downtime migrations](https://clerk.com/docs/deployments/migrate-overview). + + The following rate limit rules apply to this endpoint: 1000 requests per 10 seconds for production instances and 100 requests per 10 seconds for development instances + tags: + - Users + requestBody: + required: true + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + external_id: + type: string + description: |- + The ID of the user as used in your external systems or your previous authentication solution. + Must be unique across your instance. + nullable: true + first_name: + type: string + description: The first name to assign to the user + nullable: true + last_name: + type: string + description: The last name to assign to the user + nullable: true + email_address: + type: array + items: + type: string + description: |- + Email addresses to add to the user. + Must be unique across your instance. + The first email address will be set as the user's primary email address. + phone_number: + type: array + items: + type: string + description: |- + Phone numbers to add to the user. + Must be unique across your instance. + The first phone number will be set as the user's primary phone number. + web3_wallet: + type: array + items: + type: string + description: |- + Web3 wallets to add to the user. + Must be unique across your instance. + The first wallet will be set as the user's primary wallet. + username: + type: string + description: |- + The username to give to the user. + It must be unique across your instance. + nullable: true + password: + type: string + description: |- + The plaintext password to give the user. + Must be at least 8 characters long, and can not be in any list of hacked passwords. + nullable: true + password_digest: + type: string + description: |- + In case you already have the password digests and not the passwords, you can use them for the newly created user via this property. + The digests should be generated with one of the supported algorithms. + The hashing algorithm can be specified using the `password_hasher` property. + nullable: true + password_hasher: + $ref: '#/components/schemas/PasswordHasher' + skip_password_checks: + type: boolean + description: |- + When set to `true` all password checks are skipped. + It is recommended to use this method only when migrating plaintext passwords to Clerk. + Upon migration the user base should be prompted to pick stronger password. + nullable: true + skip_password_requirement: + type: boolean + description: |- + When set to `true`, `password` is not required anymore when creating the user and can be omitted. + This is useful when you are trying to create a user that doesn't have a password, in an instance that is using passwords. + Please note that you cannot use this flag if password is the only way for a user to sign into your instance. + nullable: true + totp_secret: + type: string + description: |- + In case TOTP is configured on the instance, you can provide the secret to enable it on the newly created user without the need to reset it. + Please note that currently the supported options are: + * Period: 30 seconds + * Code length: 6 digits + * Algorithm: SHA1 + nullable: true + backup_codes: + type: array + items: + type: string + description: |- + If Backup Codes are configured on the instance, you can provide them to enable it on the newly created user without the need to reset them. + You must provide the backup codes in plain format or the corresponding bcrypt digest. + public_metadata: + type: object + description: Metadata saved on the user, that is visible to both your Frontend and Backend APIs + additionalProperties: true + private_metadata: + type: object + description: Metadata saved on the user, that is only visible to your Backend API + additionalProperties: true + unsafe_metadata: + type: object + description: |- + Metadata saved on the user, that can be updated from both the Frontend and Backend APIs. + Note: Since this data can be modified from the frontend, it is not guaranteed to be safe. + additionalProperties: true + delete_self_enabled: + type: boolean + description: | + If enabled, user can delete themselves via FAPI. + nullable: true + legal_accepted_at: + type: string + description: A custom timestamp denoting _when_ the user accepted legal requirements, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`). + nullable: true + skip_legal_checks: + type: boolean + description: |- + When set to `true` all legal checks are skipped. + It is not recommended to skip legal checks unless you are migrating a user to Clerk. + nullable: true + create_organization_enabled: + type: boolean + description: | + If enabled, user can create organizations via FAPI. + nullable: true + create_organizations_limit: + type: integer + description: | + The maximum number of organizations the user can create. 0 means unlimited. + nullable: true + created_at: + type: string + description: A custom date/time denoting _when_ the user signed up to the application, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`). + nullable: true + responses: + '200': + $ref: '#/components/responses/User' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthenticationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /users/count: + get: + operationId: GetUsersCount + x-speakeasy-group: users + x-speakeasy-name-override: count + summary: Count users + description: Returns a total count of all users that match the given filtering criteria. + tags: + - Users + parameters: + - name: email_address + in: query + schema: + type: array + items: + type: string + description: |- + Counts users with the specified email addresses. + Accepts up to 100 email addresses. + Any email addresses not found are ignored. + required: false + - name: phone_number + in: query + schema: + type: array + items: + type: string + description: |- + Counts users with the specified phone numbers. + Accepts up to 100 phone numbers. + Any phone numbers not found are ignored. + required: false + - name: external_id + in: query + schema: + type: array + items: + type: string + description: |- + Counts users with the specified external ids. + Accepts up to 100 external ids. + Any external ids not found are ignored. + required: false + - name: username + in: query + schema: + type: array + items: + type: string + description: |- + Counts users with the specified usernames. + Accepts up to 100 usernames. + Any usernames not found are ignored. + required: false + - name: web3_wallet + in: query + schema: + type: array + items: + type: string + description: |- + Counts users with the specified web3 wallet addresses. + Accepts up to 100 web3 wallet addresses. + Any web3 wallet addressed not found are ignored. + required: false + - name: user_id + in: query + schema: + type: array + items: + type: string + description: |- + Counts users with the user ids specified. + Accepts up to 100 user ids. + Any user ids not found are ignored. + required: false + - name: organization_id + in: query + schema: + type: array + items: + type: string + description: |- + Returns users that have memberships to the given organizations. For each organization id, the `+` and `-` + can be prepended to the id, which denote whether the respective organization should be included or + excluded from the result set. Accepts up to 100 organization ids. + required: false + - name: query + in: query + description: |- + Counts users that match the given query. + For possible matches, we check the email addresses, phone numbers, usernames, web3 wallets, user ids, first and last names. + The query value doesn't need to match the exact value you are looking for, it is capable of partial matches as well. + schema: + type: string + required: false + - name: email_address_query + in: query + description: |- + Counts users with emails that match the given query, via case-insensitive partial match. + For example, `email_address_query=ello` will match a user with the email `HELLO@example.com`, + and will be included in the resulting count. + schema: + type: string + required: false + - name: phone_number_query + in: query + description: |- + Counts users with phone numbers that match the given query, via case-insensitive partial match. + For example, `phone_number_query=555` will match a user with the phone number `+1555xxxxxxx`, + and will be included in the resulting count. + schema: + type: string + required: false + - name: username_query + in: query + description: |- + Counts users with usernames that match the given query, via case-insensitive partial match. + For example, `username_query=CoolUser` will match a user with the username `SomeCoolUser`, + and will be included in the resulting count. + schema: + type: string + - name: name_query + in: query + description: Returns users with names that match the given query, via case-insensitive partial match. + schema: + type: string + - name: banned + in: query + required: false + description: Counts users which are either banned (`banned=true`) or not banned (`banned=false`). + schema: + type: boolean + - name: last_active_at_before + in: query + description: |- + Returns users whose last session activity was before the given date (with millisecond precision). + Example: use 1700690400000 to retrieve users whose last session activity was before 2023-11-23. + example: 1700690400000 + schema: + type: integer + - name: last_active_at_after + in: query + description: |- + Returns users whose last session activity was after the given date (with millisecond precision). + Example: use 1700690400000 to retrieve users whose last session activity was after 2023-11-23. + example: 1700690400000 + schema: + type: integer + - name: last_active_at_since + in: query + deprecated: true + description: |- + Returns users that had session activity since the given date. + Example: use 1700690400000 to retrieve users that had session activity from 2023-11-23 until the current day. + Deprecated in favor of `last_active_at_after`. + example: 1700690400000 + schema: + type: integer + - name: created_at_before + in: query + description: |- + Returns users who have been created before the given date (with millisecond precision). + Example: use 1730160000000 to retrieve users who have been created before 2024-10-29. + example: 1730160000000 + schema: + type: integer + - name: created_at_after + in: query + description: |- + Returns users who have been created after the given date (with millisecond precision). + Example: use 1730160000000 to retrieve users who have been created after 2024-10-29. + example: 1730160000000 + schema: + type: integer + responses: + '200': + $ref: '#/components/responses/User.Count' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /users/{user_id}: + get: + operationId: GetUser + x-speakeasy-group: users + x-speakeasy-name-override: get + summary: Retrieve a user + description: Retrieve the details of a user + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user to retrieve + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/User' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + patch: + operationId: UpdateUser + x-speakeasy-group: users + x-speakeasy-name-override: update + summary: Update a user + description: |- + Update a user's attributes. + + You can set the user's primary contact identifiers (email address and phone numbers) by updating the `primary_email_address_id` and `primary_phone_number_id` attributes respectively. + Both IDs should correspond to verified identifications that belong to the user. + + You can remove a user's username by setting the username attribute to null or the blank string "". + This is a destructive action; the identification will be deleted forever. + Usernames can be removed only if they are optional in your instance settings and there's at least one other identifier which can be used for authentication. + + This endpoint allows changing a user's password. When passing the `password` parameter directly you have two further options. + You can ignore the password policy checks for your instance by setting the `skip_password_checks` parameter to `true`. + You can also choose to sign the user out of all their active sessions on any device once the password is updated. Just set `sign_out_of_other_sessions` to `true`. + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user to update + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + external_id: + type: string + description: |- + The ID of the user as used in your external systems or your previous authentication solution. + Must be unique across your instance. + nullable: true + first_name: + type: string + description: The first name to assign to the user + nullable: true + last_name: + type: string + description: The last name to assign to the user + nullable: true + primary_email_address_id: + type: string + description: |- + The ID of the email address to set as primary. + It must be verified, and present on the current user. + nullable: true + notify_primary_email_address_changed: + type: boolean + description: |- + If set to `true`, the user will be notified that their primary email address has changed. + By default, no notification is sent. + nullable: true + default: false + primary_phone_number_id: + type: string + description: |- + The ID of the phone number to set as primary. + It must be verified, and present on the current user. + nullable: true + primary_web3_wallet_id: + type: string + description: |- + The ID of the web3 wallets to set as primary. + It must be verified, and present on the current user. + nullable: true + username: + type: string + description: |- + The username to give to the user. + It must be unique across your instance. + nullable: true + profile_image_id: + type: string + description: The ID of the image to set as the user's profile image + nullable: true + password: + type: string + description: |- + The plaintext password to give the user. + Must be at least 8 characters long, and can not be in any list of hacked passwords. + nullable: true + password_digest: + type: string + description: |- + In case you already have the password digests and not the passwords, you can use them for the newly created user via this property. + The digests should be generated with one of the supported algorithms. + The hashing algorithm can be specified using the `password_hasher` property. + password_hasher: + $ref: '#/components/schemas/PasswordHasher' + skip_password_checks: + type: boolean + description: Set it to `true` if you're updating the user's password and want to skip any password policy settings check. This parameter can only be used when providing a `password`. + nullable: true + sign_out_of_other_sessions: + type: boolean + description: Set to `true` to sign out the user from all their active sessions once their password is updated. This parameter can only be used when providing a `password`. + nullable: true + totp_secret: + type: string + description: |- + In case TOTP is configured on the instance, you can provide the secret to enable it on the specific user without the need to reset it. + Please note that currently the supported options are: + * Period: 30 seconds + * Code length: 6 digits + * Algorithm: SHA1 + nullable: true + backup_codes: + type: array + items: + type: string + description: |- + If Backup Codes are configured on the instance, you can provide them to enable it on the specific user without the need to reset them. + You must provide the backup codes in plain format or the corresponding bcrypt digest. + public_metadata: + type: object + description: Metadata saved on the user, that is visible to both your Frontend and Backend APIs + additionalProperties: true + nullable: true + private_metadata: + type: object + description: Metadata saved on the user, that is only visible to your Backend API + additionalProperties: true + nullable: true + unsafe_metadata: + type: object + description: |- + Metadata saved on the user, that can be updated from both the Frontend and Backend APIs. + Note: Since this data can be modified from the frontend, it is not guaranteed to be safe. + additionalProperties: true + nullable: true + delete_self_enabled: + type: boolean + description: If true, the user can delete themselves with the Frontend API. + nullable: true + create_organization_enabled: + type: boolean + description: If true, the user can create organizations with the Frontend API. + nullable: true + legal_accepted_at: + type: string + description: A custom timestamps denoting _when_ the user accepted legal requirements, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`). + nullable: true + skip_legal_checks: + type: boolean + description: |- + When set to `true` all legal checks are skipped. + It is not recommended to skip legal checks unless you are migrating a user to Clerk. + nullable: true + create_organizations_limit: + type: integer + description: The maximum number of organizations the user can create. 0 means unlimited. + nullable: true + created_at: + type: string + description: A custom date/time denoting _when_ the user signed up to the application, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`). + nullable: true + responses: + '200': + $ref: '#/components/responses/User' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + delete: + operationId: DeleteUser + x-speakeasy-group: users + x-speakeasy-name-override: delete + summary: Delete a user + description: Delete the specified user + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user to delete + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/DeletedObject' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + /users/{user_id}/ban: + post: + operationId: BanUser + x-speakeasy-group: users + x-speakeasy-name-override: ban + summary: Ban a user + description: Marks the given user as banned, which means that all their sessions are revoked and they are not allowed to sign in again. + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user to ban + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/User' + '402': + $ref: '#/components/responses/PaymentRequired' + /users/{user_id}/unban: + post: + operationId: UnbanUser + x-speakeasy-group: users + x-speakeasy-name-override: unban + summary: Unban a user + description: Removes the ban mark from the given user. + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user to unban + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/User' + '402': + $ref: '#/components/responses/PaymentRequired' + /users/ban: + post: + operationId: UsersBan + x-speakeasy-group: users + x-speakeasy-name-override: bulkBan + summary: Ban multiple users + description: Marks multiple users as banned, which means that all their sessions are revoked and they are not allowed to sign in again. + tags: + - Users + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - user_ids + properties: + user_ids: + type: array + items: + type: string + description: Array of user IDs to ban + minItems: 1 + maxItems: 50 + responses: + '200': + $ref: '#/components/responses/User.List' + '400': + $ref: '#/components/responses/ClerkErrors' + '402': + $ref: '#/components/responses/PaymentRequired' + /users/unban: + post: + operationId: UsersUnban + x-speakeasy-group: users + x-speakeasy-name-override: bulkUnban + summary: Unban multiple users + description: Removes the ban mark from multiple users. + tags: + - Users + requestBody: + required: true + content: + application/json: + schema: + type: object + required: + - user_ids + properties: + user_ids: + type: array + items: + type: string + description: Array of user IDs to unban + minItems: 1 + maxItems: 50 + responses: + '200': + $ref: '#/components/responses/User.List' + '400': + $ref: '#/components/responses/ClerkErrors' + '402': + $ref: '#/components/responses/PaymentRequired' + /users/{user_id}/lock: + post: + operationId: LockUser + x-speakeasy-group: users + x-speakeasy-name-override: lock + summary: Lock a user + description: |- + Marks the given user as locked, which means they are not allowed to sign in again until the lock expires. + Lock duration can be configured in the instance's restrictions settings. + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user to lock + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/User' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + /users/{user_id}/unlock: + post: + operationId: UnlockUser + x-speakeasy-group: users + x-speakeasy-name-override: unlock + summary: Unlock a user + description: Removes the lock from the given user. + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user to unlock + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/User' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + /users/{user_id}/profile_image: + post: + operationId: SetUserProfileImage + x-speakeasy-group: users + x-speakeasy-name-override: setProfileImage + summary: Set user profile image + description: Update a user's profile image + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user to update the profile image for + required: true + schema: + type: string + requestBody: + required: true + content: + multipart/form-data: + schema: + type: object + properties: + file: + type: string + format: binary + responses: + '200': + $ref: '#/components/responses/User' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/ClerkErrors' + '404': + $ref: '#/components/responses/ClerkErrors' + delete: + operationId: DeleteUserProfileImage + x-speakeasy-group: users + x-speakeasy-name-override: deleteProfileImage + summary: Delete user profile image + description: Delete a user's profile image + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user to delete the profile image for + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/User' + '404': + $ref: '#/components/responses/ClerkErrors' + /users/{user_id}/metadata: + patch: + operationId: UpdateUserMetadata + x-speakeasy-group: users + x-speakeasy-name-override: updateMetadata + summary: Merge and update a user's metadata + description: |- + Update a user's metadata attributes by merging existing values with the provided parameters. + + This endpoint behaves differently than the *Update a user* endpoint. + Metadata values will not be replaced entirely. + Instead, a deep merge will be performed. + Deep means that any nested JSON objects will be merged as well. + + You can remove metadata keys at any level by setting their value to `null`. + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user whose metadata will be updated and merged + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + public_metadata: + type: object + additionalProperties: true + description: |- + Metadata saved on the user, that is visible to both your frontend and backend. + The new object will be merged with the existing value. + private_metadata: + type: object + additionalProperties: true + description: |- + Metadata saved on the user that is only visible to your backend. + The new object will be merged with the existing value. + unsafe_metadata: + type: object + additionalProperties: true + description: |- + Metadata saved on the user, that can be updated from both the Frontend and Backend APIs. + The new object will be merged with the existing value. + + Note: Since this data can be modified from the frontend, it is not guaranteed to be safe. + responses: + '200': + $ref: '#/components/responses/User' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /users/{user_id}/oauth_access_tokens/{provider}: + get: + operationId: GetOAuthAccessToken + x-speakeasy-group: users + x-speakeasy-name-override: getOAuthAccessToken + summary: Retrieve the OAuth access token of a user + description: |- + Fetch the corresponding OAuth access token for a user that has previously authenticated with a particular OAuth provider. + For OAuth 2.0, if the access token has expired and we have a corresponding refresh token, the access token will be refreshed transparently the new one will be returned. + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user for which to retrieve the OAuth access token + required: true + schema: + type: string + - name: provider + in: path + description: The ID of the OAuth provider (e.g. `oauth_google`) + required: true + schema: + type: string + - $ref: '#/components/parameters/Paginated' + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' + responses: + '200': + $ref: '#/components/responses/OAuthAccessToken' + '400': + $ref: '#/components/responses/ClerkErrors' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /users/{user_id}/organization_memberships: + get: + operationId: UsersGetOrganizationMemberships + x-speakeasy-group: users + x-speakeasy-name-override: getOrganizationMemberships + summary: Retrieve all memberships for a user + description: Retrieve a paginated list of the user's organization memberships + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user whose organization memberships we want to retrieve + required: true + schema: + type: string + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' + responses: + '200': + $ref: '#/components/responses/OrganizationMemberships' + '403': + $ref: '#/components/responses/ClerkErrors' + /users/{user_id}/organization_invitations: + get: + operationId: UsersGetOrganizationInvitations + x-speakeasy-group: users + x-speakeasy-name-override: getOrganizationInvitations + summary: Retrieve all invitations for a user + description: Retrieve a paginated list of the user's organization invitations + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user whose organization invitations we want to retrieve + required: true + schema: + type: string + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' + - in: query + name: status + description: Filter organization invitations based on their status + required: false + schema: + type: string + enum: + - pending + - accepted + - revoked + responses: + '200': + $ref: '#/components/responses/OrganizationInvitationsWithPublicOrganizationData' + '400': + $ref: '#/components/responses/ClerkErrors' + '403': + $ref: '#/components/responses/ClerkErrors' + '404': + $ref: '#/components/responses/ResourceNotFound' + /users/{user_id}/verify_password: + post: + operationId: VerifyPassword + x-speakeasy-group: users + x-speakeasy-name-override: verifyPassword + summary: Verify the password of a user + description: |- + Check that the user's password matches the supplied input. + Useful for custom auth flows and re-verification. + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user for whom to verify the password + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + password: + type: string + description: The user password to verify + required: + - password + responses: + '200': + description: The provided password was correct. + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + verified: + type: boolean + nullable: false + '400': + description: The user does not have a password set. + '404': + description: The user does not exist. + '422': + description: The provided password was incorrect. + '500': + $ref: '#/components/responses/ClerkErrors' + /users/{user_id}/verify_totp: + post: + operationId: VerifyTOTP + x-speakeasy-group: users + x-speakeasy-name-override: verifyTotp + summary: Verify a TOTP or backup code for a user + description: |- + Verify that the provided TOTP or backup code is valid for the user. + Verifying a backup code will result it in being consumed (i.e. it will + become invalid). + Useful for custom auth flows and re-verification. + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user for whom to verify the TOTP + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + code: + type: string + description: The TOTP or backup code to verify + required: + - code + responses: + '200': + description: The provided TOTP or backup code was correct. + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + verified: + type: boolean + nullable: false + code_type: + type: string + nullable: false + enum: + - totp + - backup_code + '400': + description: The user does not have TOTP configured for their account. + '404': + description: The user does not exist. + '422': + description: The provided TOTP or backup code was incorrect. + '500': + $ref: '#/components/responses/ClerkErrors' + /users/{user_id}/mfa: + delete: + operationId: DisableMFA + x-speakeasy-group: users + x-speakeasy-name-override: disableMfa + summary: Disable a user's MFA methods + description: Disable all of a user's MFA methods (e.g. OTP sent via SMS, TOTP on their authenticator app) at once. + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user whose MFA methods are to be disabled + required: true + schema: + type: string + responses: + '200': + description: Successful operation. + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + user_id: + type: string + nullable: false + '404': + $ref: '#/components/responses/ResourceNotFound' + '500': + $ref: '#/components/responses/ClerkErrors' + /users/{user_id}/backup_code: + delete: + operationId: DeleteBackupCode + x-speakeasy-group: users + x-speakeasy-name-override: deleteBackupCodes + summary: Disable all user's Backup codes + description: Disable all of a user's backup codes. + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user whose backup codes are to be deleted. + required: true + schema: + type: string + responses: + '200': + description: Successful operation. + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + user_id: + type: string + nullable: false + '404': + $ref: '#/components/responses/ResourceNotFound' + '500': + $ref: '#/components/responses/ClerkErrors' + /users/{user_id}/passkeys/{passkey_identification_id}: + delete: + operationId: UserPasskeyDelete + x-speakeasy-group: users + x-speakeasy-name-override: deletePasskey + summary: Delete a user passkey + description: Delete the passkey identification for a given user and notify them through email. + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user that owns the passkey identity + required: true + schema: + type: string + - name: passkey_identification_id + in: path + description: The ID of the passkey identity to be deleted + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/DeletedObject' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '500': + $ref: '#/components/responses/ClerkErrors' + /users/{user_id}/web3_wallets/{web3_wallet_identification_id}: + delete: + operationId: UserWeb3WalletDelete + x-speakeasy-group: users + x-speakeasy-name-override: deleteWeb3Wallet + summary: Delete a user web3 wallet + description: Delete the web3 wallet identification for a given user. + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user that owns the web3 wallet + required: true + schema: + type: string + - name: web3_wallet_identification_id + in: path + description: The ID of the web3 wallet identity to be deleted + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/DeletedObject' + '400': + $ref: '#/components/responses/ClerkErrors' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '500': + $ref: '#/components/responses/ClerkErrors' + /users/{user_id}/totp: + delete: + operationId: DeleteTOTP + x-speakeasy-group: users + x-speakeasy-name-override: deleteTOTP + summary: Delete all the user's TOTPs + description: Deletes all of the user's TOTPs. + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user whose TOTPs are to be deleted + required: true + schema: + type: string + responses: + '200': + description: Successful operation. + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + user_id: + type: string + nullable: false + '404': + $ref: '#/components/responses/ResourceNotFound' + '500': + $ref: '#/components/responses/ClerkErrors' + /users/{user_id}/external_accounts/{external_account_id}: + delete: + operationId: DeleteExternalAccount + x-speakeasy-group: users + x-speakeasy-name-override: deleteExternalAccount + summary: Delete External Account + description: Delete an external account by ID. + tags: + - Users + parameters: + - name: user_id + in: path + description: The ID of the user's external account + required: true + schema: + type: string + - name: external_account_id + in: path + description: The ID of the external account to delete + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/DeletedObject' + '400': + $ref: '#/components/responses/ClerkErrors' + '403': + $ref: '#/components/responses/ClerkErrors' + '404': + $ref: '#/components/responses/ResourceNotFound' + '500': + $ref: '#/components/responses/ClerkErrors' + /invitations: + post: + operationId: CreateInvitation + x-speakeasy-group: invitations + x-speakeasy-name-override: create + summary: Create an invitation + description: |- + Creates a new invitation for the given email address and sends the invitation email. + Keep in mind that you cannot create an invitation if there is already one for the given email address. + Also, trying to create an invitation for an email address that already exists in your application will result to an error. + tags: + - Invitations + requestBody: + description: Required parameters + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + email_address: + type: string + description: The email address the invitation will be sent to + public_metadata: + type: object + description: |- + Metadata that will be attached to the newly created invitation. + The value of this property should be a well-formed JSON object. + Once the user accepts the invitation and signs up, these metadata will end up in the user's public metadata. + additionalProperties: true + redirect_url: + type: string + description: |- + Optional URL which specifies where to redirect the user once they click the invitation link. + This is only required if you have implemented a [custom flow](https://clerk.com/docs/authentication/invitations#custom-flow) and you're not using Clerk Hosted Pages or Clerk Components. + notify: + type: boolean + description: |- + Optional flag which denotes whether an email invitation should be sent to the given email address. + Defaults to `true`. + nullable: true + default: true + ignore_existing: + type: boolean + description: Whether an invitation should be created if there is already an existing invitation for this email address, or it's claimed by another user. + nullable: true + default: false + expires_in_days: + type: integer + description: The number of days the invitation will be valid for. By default, the invitation expires after 30 days. + nullable: true + minimum: 1 + maximum: 365 + template_slug: + type: string + enum: + - invitation + - waitlist_invitation + description: The slug of the email template to use for the invitation email. + required: + - email_address + responses: + '200': + $ref: '#/components/responses/Invitation' + '400': + $ref: '#/components/responses/ClerkErrors' + '422': + $ref: '#/components/responses/UnprocessableEntity' + get: + summary: List all invitations + x-speakeasy-group: invitations + x-speakeasy-name-override: list + description: Returns all non-revoked invitations for your application, sorted by creation date + operationId: ListInvitations + parameters: + - in: query + name: status + required: false + description: Filter invitations based on their status + schema: + type: string + enum: + - pending + - accepted + - revoked + - expired + - in: query + required: false + name: query + description: Filter invitations based on their `email_address` or `id` + schema: + type: string + - name: order_by + in: query + required: false + description: |- + Allows to return invitations in a particular order. + At the moment, you can order the returned invitations either by their `created_at`, `email_address` or `expires_at`. + In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. + For example, if you want invitations to be returned in descending order according to their `created_at` property, you can use `-created_at`. + If you don't use `+` or `-`, then `+` is implied. + Defaults to `-created_at`. + schema: + type: string + default: '-created_at' + - $ref: '#/components/parameters/Paginated' + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' + tags: + - Invitations + responses: + '200': + $ref: '#/components/responses/Invitation.List' + /invitations/bulk: + post: + operationId: CreateBulkInvitations + x-speakeasy-group: invitations + x-speakeasy-name-override: bulkCreate + summary: Create multiple invitations + description: |- + Use this API operation to create multiple invitations for the provided email addresses. You can choose to send the + invitations as emails by setting the `notify` parameter to `true`. There cannot be an existing invitation for any + of the email addresses you provide unless you set `ignore_existing` to `true` for specific email addresses. Please + note that there must be no existing user for any of the email addresses you provide, and this rule cannot be bypassed. + tags: + - Invitations + requestBody: + description: Required parameters + content: + application/json: + schema: + type: array + items: + type: object + additionalProperties: false + properties: + email_address: + type: string + description: The email address the invitation will be sent to + public_metadata: + type: object + nullable: true + description: |- + Metadata that will be attached to the newly created invitation. + The value of this property should be a well-formed JSON object. + Once the user accepts the invitation and signs up, these metadata will end up in the user's public metadata. + additionalProperties: true + redirect_url: + type: string + nullable: true + description: The URL where the user is redirected upon visiting the invitation link, where they can accept the invitation. Required if you have implemented a [custom flow for handling application invitations](/docs/custom-flows/invitations). + notify: + type: boolean + description: |- + Optional flag which denotes whether an email invitation should be sent to the given email address. + Defaults to true. + nullable: true + default: true + ignore_existing: + type: boolean + description: |- + Whether an invitation should be created if there is already an existing invitation for this email + address, or it's claimed by another user. + nullable: true + default: false + expires_in_days: + type: integer + description: The number of days the invitation will be valid for. By default, the invitation expires after 30 days. + nullable: true + minimum: 1 + maximum: 365 + template_slug: + type: string + enum: + - invitation + - waitlist_invitation + description: The slug of the email template to use for the invitation email. + default: invitation + required: + - email_address + responses: + '200': + $ref: '#/components/responses/Invitation.List' + '400': + $ref: '#/components/responses/ClerkErrors' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /invitations/{invitation_id}/revoke: + post: + operationId: RevokeInvitation + x-speakeasy-group: invitations + x-speakeasy-name-override: revoke + summary: Revokes an invitation + description: |- + Revokes the given invitation. + Revoking an invitation will prevent the user from using the invitation link that was sent to them. + However, it doesn't prevent the user from signing up if they follow the sign up flow. + Only active (i.e. non-revoked) invitations can be revoked. + tags: + - Invitations + parameters: + - name: invitation_id + in: path + description: The ID of the invitation to be revoked + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/Invitation.Revoked' + '400': + $ref: '#/components/responses/ClerkErrors' + '404': + $ref: '#/components/responses/ResourceNotFound' + /organization_invitations: + get: + operationId: ListInstanceOrganizationInvitations + x-speakeasy-group: organizationInvitations + x-speakeasy-name-override: getAll + summary: Get a list of organization invitations for the current instance + description: |- + This request returns the list of organization invitations for the instance. + Results can be paginated using the optional `limit` and `offset` query parameters. + You can filter them by providing the 'status' query parameter, that accepts multiple values. + You can change the order by providing the 'order' query parameter, that accepts multiple values. + You can filter by the invited user email address providing the `query` query parameter. + The organization invitations are ordered by descending creation date by default. + tags: + - Organization Invitations + parameters: + - in: query + name: order_by + required: false + description: |- + Allows to return organization invitations in a particular order. + At the moment, you can order the returned organization invitations either by their `created_at` or `email_address`. + In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. + For example, if you want organization invitations to be returned in descending order according to their `created_at` property, you can use `-created_at`. + If you don't use `+` or `-`, then `+` is implied. + Defaults to `-created_at`. + schema: + type: string + default: '-created_at' + - in: query + name: status + description: Filter organization invitations based on their status + required: false + schema: + type: string + enum: + - pending + - accepted + - revoked + - in: query + required: false + name: query + description: Filter organization invitations based on their `email_address` + schema: + type: string + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' + responses: + '200': + $ref: '#/components/responses/OrganizationInvitationsWithPublicOrganizationData' + '400': + $ref: '#/components/responses/ClerkErrors' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/ClerkErrors' + '500': + $ref: '#/components/responses/ClerkErrors' + /allowlist_identifiers: + get: + operationId: ListAllowlistIdentifiers + x-speakeasy-group: allowlistIdentifiers + x-speakeasy-name-override: list + summary: List all identifiers on the allow-list + description: Get a list of all identifiers allowed to sign up to an instance + parameters: + - $ref: '#/components/parameters/Paginated' + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' + tags: + - Allow-list / Block-list + responses: + '200': + $ref: '#/components/responses/AllowlistIdentifier.List' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '402': + $ref: '#/components/responses/PaymentRequired' + post: + operationId: CreateAllowlistIdentifier + x-speakeasy-group: allowlistIdentifiers + x-speakeasy-name-override: create + summary: Add identifier to the allow-list + description: Create an identifier allowed to sign up to an instance + tags: + - Allow-list / Block-list + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + identifier: + type: string + description: |- + The identifier to be added in the allow-list. + This can be an email address, a phone number or a web3 wallet. + notify: + type: boolean + description: |- + This flag denotes whether the given identifier will receive an invitation to join the application. + Note that this only works for email address and phone number identifiers. + default: false + required: + - identifier + responses: + '200': + $ref: '#/components/responses/AllowlistIdentifier' + '400': + $ref: '#/components/responses/ClerkErrors' + '402': + $ref: '#/components/responses/PaymentRequired' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /allowlist_identifiers/{identifier_id}: + delete: + operationId: DeleteAllowlistIdentifier + x-speakeasy-group: allowlistIdentifiers + x-speakeasy-name-override: delete + summary: Delete identifier from allow-list + description: Delete an identifier from the instance allow-list + tags: + - Allow-list / Block-list + parameters: + - name: identifier_id + in: path + description: The ID of the identifier to delete from the allow-list + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/DeletedObject' + '402': + $ref: '#/components/responses/PaymentRequired' + '404': + $ref: '#/components/responses/ResourceNotFound' + /blocklist_identifiers: + get: + operationId: ListBlocklistIdentifiers + x-speakeasy-group: blocklistIdentifiers + x-speakeasy-name-override: list + summary: List all identifiers on the block-list + description: Get a list of all identifiers which are not allowed to access an instance + tags: + - Allow-list / Block-list + responses: + '200': + $ref: '#/components/responses/BlocklistIdentifier.List' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '402': + $ref: '#/components/responses/PaymentRequired' + post: + operationId: CreateBlocklistIdentifier + x-speakeasy-group: blocklistIdentifiers + x-speakeasy-name-override: create + summary: Add identifier to the block-list + description: Create an identifier that is blocked from accessing an instance + tags: + - Allow-list / Block-list + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + identifier: + type: string + description: |- + The identifier to be added in the block-list. + This can be an email address, a phone number or a web3 wallet. + required: + - identifier + responses: + '200': + $ref: '#/components/responses/BlocklistIdentifier' + '400': + $ref: '#/components/responses/ClerkErrors' + '402': + $ref: '#/components/responses/PaymentRequired' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /blocklist_identifiers/{identifier_id}: + delete: + operationId: DeleteBlocklistIdentifier + x-speakeasy-group: blocklistIdentifiers + x-speakeasy-name-override: delete + summary: Delete identifier from block-list + description: Delete an identifier from the instance block-list + tags: + - Allow-list / Block-list + parameters: + - name: identifier_id + in: path + description: The ID of the identifier to delete from the block-list + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/DeletedObject' + '402': + $ref: '#/components/responses/PaymentRequired' + '404': + $ref: '#/components/responses/ResourceNotFound' + /beta_features/instance_settings: + patch: + operationId: UpdateInstanceAuthConfig + x-speakeasy-group: betaFeatures + x-speakeasy-name-override: updateInstanceSettings + summary: Update instance settings + description: Updates the settings of an instance + tags: + - Beta Features + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + restricted_to_allowlist: + type: boolean + description: Whether sign up is restricted to email addresses, phone numbers and usernames that are on the allowlist. + nullable: true + default: false + from_email_address: + type: string + description: |- + The local part of the email address from which authentication-related emails (e.g. OTP code, magic links) will be sent. + Only alphanumeric values are allowed. + Note that this value should contain only the local part of the address (e.g. `foo` for `foo@example.com`). + nullable: true + progressive_sign_up: + type: boolean + description: Enable the Progressive Sign Up algorithm. Refer to the [docs](https://clerk.com/docs/upgrade-guides/progressive-sign-up) for more info. + nullable: true + enhanced_email_deliverability: + type: boolean + description: |- + The "enhanced_email_deliverability" feature will send emails from "verifications@clerk.dev" instead of your domain. + This can be helpful if you do not have a high domain reputation. + nullable: true + test_mode: + type: boolean + description: |- + Toggles test mode for this instance, allowing the use of test email addresses and phone numbers. + Defaults to true for development instances. + nullable: true + responses: + '200': + $ref: '#/components/responses/InstanceSettings' + '402': + $ref: '#/components/responses/PaymentRequired' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /beta_features/domain: + put: + deprecated: true + operationId: UpdateProductionInstanceDomain + x-speakeasy-group: betaFeatures + x-speakeasy-name-override: updateProductionInstanceDomain + summary: Update production instance domain + description: |- + Change the domain of a production instance. + + Changing the domain requires updating the [DNS records](https://clerk.com/docs/deployments/overview#dns-records) accordingly, deploying new [SSL certificates](https://clerk.com/docs/deployments/overview#deploy), updating your Social Connection's redirect URLs and setting the new keys in your code. + + WARNING: Changing your domain will invalidate all current user sessions (i.e. users will be logged out). Also, while your application is being deployed, a small downtime is expected to occur. + tags: + - Beta Features + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + home_url: + type: string + description: The new home URL of the production instance e.g. https://www.example.com + is_secondary: + type: boolean + description: Whether the domain is a secondary app. + responses: + '202': + description: Accepted + '400': + $ref: '#/components/responses/ClerkErrors' + '422': + $ref: '#/components/responses/ClerkErrors' + /actor_tokens: + post: + operationId: CreateActorToken + x-speakeasy-group: actorTokens + x-speakeasy-name-override: create + summary: Create actor token + description: |- + Create an actor token that can be used to impersonate the given user. + The `actor` parameter needs to include at least a "sub" key whose value is the ID of the actor (impersonating) user. + tags: + - Actor Tokens + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + user_id: + type: string + description: The ID of the user being impersonated. + actor: + type: object + additionalProperties: true + description: |- + The actor payload. It needs to include a sub property which should contain the ID of the actor. + This whole payload will be also included in the JWT session token. + properties: + sub: + type: string + description: The ID of the actor. + required: + - sub + example: + sub: user_2OEpKhcCN1Lat9NQ0G6puh7q5Rb + expires_in_seconds: + type: integer + description: |- + Optional parameter to specify the life duration of the actor token in seconds. + By default, the duration is 1 hour. + default: 3600 + session_max_duration_in_seconds: + type: integer + description: |- + The maximum duration that the session which will be created by the generated actor token should last. + By default, the duration of a session created via an actor token, lasts 30 minutes. + default: 1800 + required: + - user_id + - actor + responses: + '200': + $ref: '#/components/responses/ActorToken' + '400': + $ref: '#/components/responses/ClerkErrors' + '402': + $ref: '#/components/responses/PaymentRequired' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /actor_tokens/{actor_token_id}/revoke: + post: + x-speakeasy-group: actorTokens + x-speakeasy-name-override: revoke + summary: Revoke actor token + description: Revokes a pending actor token. + operationId: RevokeActorToken + tags: + - Actor Tokens + parameters: + - name: actor_token_id + in: path + description: The ID of the actor token to be revoked. + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/ActorToken' + '400': + $ref: '#/components/responses/ClerkErrors' + '404': + $ref: '#/components/responses/ResourceNotFound' + /domains: + get: + operationId: ListDomains + x-speakeasy-group: domains + x-speakeasy-name-override: list + summary: List all instance domains + description: |- + Use this endpoint to get a list of all domains for an instance. + The response will contain the primary domain for the instance and any satellite domains. Each domain in the response contains information about the URLs where Clerk operates and the required CNAME targets. + tags: + - Domains + responses: + '200': + $ref: '#/components/responses/Domains' + post: + summary: Add a domain + operationId: AddDomain + x-speakeasy-group: domains + x-speakeasy-name-override: add + description: |- + Add a new domain for your instance. + Useful in the case of multi-domain instances, allows adding satellite domains to an instance. + The new domain must have a `name`. The domain name can contain the port for development instances, like `localhost:3000`. + At the moment, instances can have only one primary domain, so the `is_satellite` parameter must be set to `true`. + If you're planning to configure the new satellite domain to run behind a proxy, pass the `proxy_url` parameter accordingly. + tags: + - Domains + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The new domain name. Can contain the port for development instances. + is_satellite: + type: boolean + description: Marks the new domain as satellite. Only `true` is accepted at the moment. + enum: + - true + proxy_url: + type: string + description: The full URL of the proxy which will forward requests to the Clerk Frontend API for this domain. Applicable only to production instances. + nullable: true + required: + - name + - is_satellite + responses: + '200': + $ref: '#/components/responses/Domain' + '400': + $ref: '#/components/responses/ClerkErrors' + '402': + $ref: '#/components/responses/ClerkErrors' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /domains/{domain_id}: + delete: + operationId: DeleteDomain + x-speakeasy-group: domains + x-speakeasy-name-override: delete + summary: Delete a satellite domain + description: |- + Deletes a satellite domain for the instance. + It is currently not possible to delete the instance's primary domain. + tags: + - Domains + parameters: + - in: path + name: domain_id + required: true + schema: + type: string + description: The ID of the domain that will be deleted. Must be a satellite domain. + responses: + '200': + $ref: '#/components/responses/DeletedObject' + '403': + $ref: '#/components/responses/ClerkErrors' + '404': + $ref: '#/components/responses/ResourceNotFound' + patch: + operationId: UpdateDomain + x-speakeasy-group: domains + x-speakeasy-name-override: update + summary: Update a domain + description: |- + The `proxy_url` can be updated only for production instances. + Update one of the instance's domains. Both primary and satellite domains can be updated. + If you choose to use Clerk via proxy, use this endpoint to specify the `proxy_url`. + Whenever you decide you'd rather switch to DNS setup for Clerk, simply set `proxy_url` + to `null` for the domain. When you update a production instance's primary domain name, + you have to make sure that you've completed all the necessary setup steps for DNS and + emails to work. Expect downtime otherwise. Updating a primary domain's name will also + update the instance's home origin, affecting the default application paths. + tags: + - Domains + parameters: + - in: path + name: domain_id + required: true + schema: + type: string + description: The ID of the domain that will be updated. + requestBody: + required: true + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + name: + type: string + description: |- + The new domain name. For development instances, can contain the port, + i.e `myhostname:3000`. For production instances, must be a valid FQDN, + i.e `mysite.com`. Cannot contain protocol scheme. + nullable: true + proxy_url: + type: string + description: |- + The full URL of the proxy that will forward requests to Clerk's Frontend API. + Can only be updated for production instances. + nullable: true + is_secondary: + type: boolean + description: |- + Whether this is a domain for a secondary app, meaning that any subdomain provided is significant and + will be stored as part of the domain. This is useful for supporting multiple apps (one primary and + multiple secondaries) on the same root domain (eTLD+1). + nullable: true + responses: + '200': + $ref: '#/components/responses/Domain' + '400': + $ref: '#/components/responses/ClerkErrors' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /instance: + get: + operationId: GetInstance + x-speakeasy-group: instanceSettings + x-speakeasy-name-override: get + summary: Fetch the current instance + description: Fetches the current instance + tags: + - Instance Settings + responses: + '200': + $ref: '#/components/responses/Instance' + patch: + operationId: UpdateInstance + x-speakeasy-group: instanceSettings + x-speakeasy-name-override: update + summary: Update instance settings + description: Updates the settings of an instance + tags: + - Instance Settings + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + test_mode: + type: boolean + description: |- + Toggles test mode for this instance, allowing the use of test email addresses and phone numbers. + Defaults to true for development instances. + nullable: true + hibp: + type: boolean + description: Whether the instance should be using the HIBP service to check passwords for breaches + nullable: true + enhanced_email_deliverability: + type: boolean + description: |- + The "enhanced_email_deliverability" feature will send emails from "verifications@clerk.dev" instead of your domain. + This can be helpful if you do not have a high domain reputation. + nullable: true + support_email: + type: string + nullable: true + clerk_js_version: + type: string + nullable: true + development_origin: + type: string + nullable: true + allowed_origins: + type: array + items: + type: string + description: For browser-like stacks such as browser extensions, Electron (not officially supported), or Capacitor.js (not officially supported), the instance allowed origins need to be updated with the request origin value. For Chrome extensions popup, background, or service worker pages, the origin is chrome-extension://extension_uiid. For Electron apps the default origin is http://localhost:3000. For Capacitor, the origin is capacitor://localhost. + cookieless_dev: + type: boolean + description: |- + Whether the instance should operate in cookieless development mode (i.e. without third-party cookies). + Deprecated: Please use `url_based_session_syncing` instead. + deprecated: true + nullable: true + url_based_session_syncing: + type: boolean + description: Whether the instance should use URL-based session syncing in development mode (i.e. without third-party cookies). + nullable: true + responses: + '204': + description: Accepted + '422': + $ref: '#/components/responses/UnprocessableEntity' + /instance/restrictions: + patch: + operationId: UpdateInstanceRestrictions + x-speakeasy-group: instanceSettings + x-speakeasy-name-override: updateRestrictions + summary: Update instance restrictions + description: Updates the restriction settings of an instance + tags: + - Instance Settings + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + allowlist: + type: boolean + nullable: true + blocklist: + type: boolean + nullable: true + block_email_subaddresses: + type: boolean + nullable: true + block_disposable_email_domains: + type: boolean + nullable: true + responses: + '200': + $ref: '#/components/responses/InstanceRestrictions' + '402': + $ref: '#/components/responses/PaymentRequired' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /instance/change_domain: + post: + operationId: ChangeProductionInstanceDomain + x-speakeasy-group: instanceSettings + x-speakeasy-name-override: changeDomain + summary: Update production instance domain + description: |- + Change the domain of a production instance. + + Changing the domain requires updating the [DNS records](https://clerk.com/docs/deployments/overview#dns-records) accordingly, deploying new [SSL certificates](https://clerk.com/docs/deployments/overview#deploy), updating your Social Connection's redirect URLs and setting the new keys in your code. + + WARNING: Changing your domain will invalidate all current user sessions (i.e. users will be logged out). Also, while your application is being deployed, a small downtime is expected to occur. + tags: + - Beta Features + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + home_url: + type: string + description: The new home URL of the production instance e.g. https://www.example.com + is_secondary: + type: boolean + description: |- + Whether this is a domain for a secondary app, meaning that any subdomain provided is significant and + will be stored as part of the domain. This is useful for supporting multiple apps (one primary and + multiple secondaries) on the same root domain (eTLD+1). + responses: + '202': + description: Accepted + '400': + $ref: '#/components/responses/ClerkErrors' + '422': + $ref: '#/components/responses/ClerkErrors' + /instance/organization_settings: + patch: + operationId: UpdateInstanceOrganizationSettings + x-speakeasy-group: instanceSettings + x-speakeasy-name-override: updateOrganizationSettings + summary: Update instance organization settings + description: Updates the organization settings of the instance + tags: + - Instance Settings + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + enabled: + type: boolean + nullable: true + max_allowed_memberships: + type: integer + nullable: true + admin_delete_enabled: + type: boolean + nullable: true + domains_enabled: + type: boolean + nullable: true + domains_enrollment_modes: + type: array + items: + type: string + description: |- + Specify which enrollment modes to enable for your Organization Domains. + Supported modes are 'automatic_invitation' & 'automatic_suggestion'. + creator_role_id: + type: string + description: Specify what the default organization role is for an organization creator. + nullable: true + domains_default_role_id: + type: string + description: Specify what the default organization role is for the organization domains. + nullable: true + responses: + '200': + $ref: '#/components/responses/OrganizationSettings' + '400': + $ref: '#/components/responses/ClerkErrors' + '402': + $ref: '#/components/responses/PaymentRequired' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /webhooks/svix: + post: + operationId: CreateSvixApp + x-speakeasy-group: webhooks + x-speakeasy-name-override: createSvixApp + summary: Create a Svix app + description: Create a Svix app and associate it with the current instance + tags: + - Webhooks + responses: + '200': + $ref: '#/components/responses/SvixURL' + '400': + $ref: '#/components/responses/ClerkErrors' + delete: + operationId: DeleteSvixApp + x-speakeasy-group: webhooks + x-speakeasy-name-override: deleteSvixApp + summary: Delete a Svix app + description: Delete a Svix app and disassociate it from the current instance + tags: + - Webhooks + responses: + '204': + description: Svix app was successfully deleted + '400': + $ref: '#/components/responses/ClerkErrors' + /webhooks/svix_url: + post: + operationId: GenerateSvixAuthURL + x-speakeasy-group: webhooks + x-speakeasy-name-override: generateSvixAuthURL + summary: Create a Svix Dashboard URL + description: Generate a new url for accessing the Svix's management dashboard for that particular instance + tags: + - Webhooks + responses: + '200': + $ref: '#/components/responses/SvixURL' + '400': + $ref: '#/components/responses/ClerkErrors' + /jwt_templates: + get: + operationId: ListJWTTemplates + x-speakeasy-group: jwtTemplates + x-speakeasy-name-override: list + summary: List all templates + parameters: + - $ref: '#/components/parameters/Paginated' + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' + tags: + - JWT Templates + responses: + '200': + $ref: '#/components/responses/JWTTemplate.List' + post: + operationId: CreateJWTTemplate + x-speakeasy-group: jwtTemplates + x-speakeasy-name-override: create + summary: Create a JWT template + description: Create a new JWT template + tags: + - JWT Templates + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: JWT template name + nullable: false + claims: + type: object + description: JWT template claims in JSON format + nullable: false + lifetime: + type: number + minimum: 30 + maximum: 315360000 + description: JWT token lifetime + nullable: true + allowed_clock_skew: + type: number + minimum: 0 + maximum: 300 + description: JWT token allowed clock skew + nullable: true + custom_signing_key: + type: boolean + description: Whether a custom signing key/algorithm is also provided for this template + signing_algorithm: + type: string + description: The custom signing algorithm to use when minting JWTs. Required if `custom_signing_key` is `true`. + nullable: true + signing_key: + type: string + description: The custom signing private key to use when minting JWTs. Required if `custom_signing_key` is `true`. + nullable: true + required: + - name + - claims + responses: + '200': + $ref: '#/components/responses/JWTTemplate' + '400': + $ref: '#/components/responses/ClerkErrors' + '402': + $ref: '#/components/responses/PaymentRequired' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /jwt_templates/{template_id}: + get: + operationId: GetJWTTemplate + x-speakeasy-group: jwtTemplates + x-speakeasy-name-override: get + summary: Retrieve a template + description: Retrieve the details of a given JWT template + tags: + - JWT Templates + parameters: + - name: template_id + in: path + description: JWT Template ID + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/JWTTemplate' + '404': + $ref: '#/components/responses/ResourceNotFound' + patch: + operationId: UpdateJWTTemplate + x-speakeasy-group: jwtTemplates + x-speakeasy-name-override: update + summary: Update a JWT template + description: Updates an existing JWT template + tags: + - JWT Templates + parameters: + - name: template_id + in: path + description: The ID of the JWT template to update + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: JWT template name + nullable: false + claims: + type: object + description: JWT template claims in JSON format + nullable: false + lifetime: + type: number + minimum: 30 + maximum: 315360000 + description: JWT token lifetime + nullable: true + allowed_clock_skew: + type: number + minimum: 0 + maximum: 300 + description: JWT token allowed clock skew + nullable: true + custom_signing_key: + type: boolean + description: Whether a custom signing key/algorithm is also provided for this template + signing_algorithm: + type: string + description: The custom signing algorithm to use when minting JWTs. Required if `custom_signing_key` is `true`. + nullable: true + signing_key: + type: string + description: The custom signing private key to use when minting JWTs. Required if `custom_signing_key` is `true`. + nullable: true + required: + - name + - claims + responses: + '200': + $ref: '#/components/responses/JWTTemplate' + '400': + $ref: '#/components/responses/ClerkErrors' + '402': + $ref: '#/components/responses/PaymentRequired' + '422': + $ref: '#/components/responses/UnprocessableEntity' + delete: + operationId: DeleteJWTTemplate + x-speakeasy-group: jwtTemplates + x-speakeasy-name-override: delete + summary: Delete a Template + description: '' + tags: + - JWT Templates + parameters: + - name: template_id + in: path + description: JWT Template ID + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/DeletedObject' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + /machine_tokens: + x-internal: true + post: + operationId: CreateMachineToken + x-speakeasy-group: machineTokens + x-speakeasy-name-override: create + summary: Create a machine token + description: Create a new machine token + tags: + - Machine Tokens + requestBody: + content: + application/json: + schema: + type: object + properties: + machine_id: + type: string + maxLength: 96 + description: ID of the machine creating the token. Must be be prefixed with `mch_`. Must only contain lowercase letters, numbers, and underscores. + claims: + type: object + description: Claims to include in the JWT + nullable: true + expires_in_seconds: + type: integer + minimum: 30 + maximum: 315360000 + description: Token lifetime in seconds. Defaults to 30 seconds if not specified. + nullable: true + allowed_clock_skew: + type: integer + minimum: 0 + maximum: 300 + default: 5 + description: Allowed clock skew in seconds. Defaults to 5 seconds if not specified. + nullable: true + required: + - machine_id + responses: + '200': + $ref: '#/components/responses/MachineToken' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /machines: + get: + operationId: ListMachines + x-speakeasy-group: machines + x-speakeasy-name-override: list + summary: Get a list of machines for an instance + description: |- + This request returns the list of machines for an instance. The machines are + ordered by descending creation date (i.e. most recent machines will be + returned first) + tags: + - Machines + parameters: + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' + - in: query + name: query + description: Returns machines with ID or name that match the given query. Uses exact match for machine ID and partial match for name. + schema: + type: string + allowEmptyValue: true + required: false + responses: + '200': + $ref: '#/components/responses/Machine.List' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + post: + operationId: CreateMachine + x-speakeasy-group: machines + x-speakeasy-name-override: create + summary: Create a machine + description: Creates a new machine. + tags: + - Machines + requestBody: + content: + application/json: + schema: + type: object + required: + - name + properties: + name: + type: string + description: The name of the machine + minLength: 1 + maxLength: 255 + scoped_machines: + type: array + items: + type: string + description: Array of machine IDs that this machine will have access to. Maximum of 25 scopes per machine. + maxItems: 25 + responses: + '200': + $ref: '#/components/responses/Machine' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /machines/{machine_id}: + get: + operationId: GetMachine + x-speakeasy-group: machines + x-speakeasy-name-override: get + summary: Retrieve a machine + description: Returns the details of a machine. + tags: + - Machines + parameters: + - name: machine_id + in: path + description: The ID of the machine to retrieve + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/Machine' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + patch: + operationId: UpdateMachine + x-speakeasy-group: machines + x-speakeasy-name-override: update + summary: Update a machine + description: |- + Updates an existing machine. + Only the provided fields will be updated. + tags: + - Machines + parameters: + - name: machine_id + in: path + description: The ID of the machine to update + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: The name of the machine + minLength: 1 + maxLength: 255 + responses: + '200': + $ref: '#/components/responses/Machine' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + delete: + operationId: DeleteMachine + x-speakeasy-group: machines + x-speakeasy-name-override: delete + summary: Delete a machine + description: Deletes a machine. + tags: + - Machines + parameters: + - name: machine_id + in: path + description: The ID of the machine to delete + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/Machine.Deleted' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /machines/{machine_id}/scopes: + post: + operationId: CreateMachineScope + x-speakeasy-group: machines + x-speakeasy-name-override: createScope + summary: Create a machine scope + description: |- + Creates a new machine scope, allowing the specified machine to access another machine. + Maximum of 25 scopes per machine. + tags: + - Machines + parameters: + - name: machine_id + in: path + description: The ID of the machine that will have access to another machine + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + required: + - to_machine_id + properties: + to_machine_id: + type: string + description: The ID of the machine that will be scoped to the current machine + responses: + '200': + $ref: '#/components/responses/MachineScope' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '409': + $ref: '#/components/responses/Conflict' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /machines/{machine_id}/scopes/{other_machine_id}: + delete: + operationId: DeleteMachineScope + x-speakeasy-group: machines + x-speakeasy-name-override: deleteScope + summary: Delete a machine scope + description: Deletes a machine scope, removing access from one machine to another. + tags: + - Machines + parameters: + - name: machine_id + in: path + description: The ID of the machine that has access to another machine + required: true + schema: + type: string + - name: other_machine_id + in: path + description: The ID of the machine that is being accessed + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/MachineScope.Deleted' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /organizations: + get: + operationId: ListOrganizations + x-speakeasy-group: organizations + x-speakeasy-name-override: list + summary: Get a list of organizations for an instance + description: |- + This request returns the list of organizations for an instance. + Results can be paginated using the optional `limit` and `offset` query parameters. + The organizations are ordered by descending creation date. + Most recent organizations will be returned first. + tags: + - Organizations + parameters: + - in: query + required: false + name: include_members_count + description: Flag to denote whether the member counts of each organization should be included in the response or not. + schema: + type: boolean + - in: query + required: false + name: include_missing_member_with_elevated_permissions + description: Flag to denote whether or not to include a member with elevated permissions who is not currently a member of the organization. + schema: + type: boolean + - in: query + required: false + name: query + description: |- + Returns organizations with ID, name, or slug that match the given query. + Uses exact match for organization ID and partial match for name and slug. + schema: + type: string + - in: query + name: user_id + description: |- + Returns organizations with the user ids specified. Any user ids not found are ignored. + For each user id, the `+` and `-` can be prepended to the id, which denote whether the + respective organization should be included or excluded from the result set. + schema: + type: array + items: + type: string + required: false + - in: query + name: organization_id + description: |- + Returns organizations with the organization ids specified. Any organization ids not found are ignored. + For each organization id, the `+` and `-` can be prepended to the id, which denote whether the + respective organization should be included or excluded from the result set. Accepts up to 100 organization ids. + Example: ?organization_id=+org_1&organization_id=-org_2 + schema: + type: array + items: + type: string + required: false + - in: query + name: order_by + description: |- + Allows to return organizations in a particular order. + At the moment, you can order the returned organizations either by their `name`, `created_at` or `members_count`. + In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. + For example, if you want organizations to be returned in descending order according to their `created_at` property, you can use `-created_at`. + If you don't use `+` or `-`, then `+` is implied. + Defaults to `-created_at`. + schema: + type: string + default: '-created_at' + required: false + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' + responses: + '200': + $ref: '#/components/responses/Organizations' + '400': + $ref: '#/components/responses/ClerkErrors' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + post: + operationId: CreateOrganization + x-speakeasy-group: organizations + x-speakeasy-name-override: create + summary: Create an organization + description: |- + Creates a new organization with the given name for an instance. + You can specify an optional slug for the new organization. + If provided, the organization slug can contain only lowercase alphanumeric characters (letters and digits) and the dash "-". + Organization slugs must be unique for the instance. + You can provide additional metadata for the organization and set any custom attribute you want. + Organizations support private and public metadata. + Private metadata can only be accessed from the Backend API. + Public metadata can be accessed from the Backend API, and are read-only from the Frontend API. + The `created_by` user will see this as their [active organization] (https://clerk.com/docs/organizations/overview#active-organization) + the next time they create a session, presuming they don't explicitly set a different organization as active before then. + tags: + - Organizations + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: |- + The name of the new organization. + May not contain URLs or HTML. + Max length: 256 + created_by: + type: string + description: The ID of the User who will become the administrator for the new organization + nullable: true + private_metadata: + type: object + description: Metadata saved on the organization, accessible only from the Backend API + additionalProperties: true + nullable: true + public_metadata: + type: object + description: Metadata saved on the organization, read-only from the Frontend API and fully accessible (read/write) from the Backend API + additionalProperties: true + nullable: true + slug: + type: string + description: |- + A slug for the new organization. + Can contain only lowercase alphanumeric characters and the dash "-". + Must be unique for the instance. + nullable: true + max_allowed_memberships: + type: integer + minimum: 0 + description: The maximum number of memberships allowed for this organization + nullable: true + created_at: + type: string + description: A custom date/time denoting _when_ the organization was created, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`). + nullable: true + required: + - name + responses: + '200': + $ref: '#/components/responses/Organization' + '400': + $ref: '#/components/responses/ClerkErrors' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /organizations/{organization_id}: + get: + operationId: GetOrganization + x-speakeasy-group: organizations + x-speakeasy-name-override: get + summary: Retrieve an organization by ID or slug + description: Fetches the organization whose ID or slug matches the provided `id_or_slug` URL query parameter. + tags: + - Organizations + parameters: + - in: path + name: organization_id + required: true + schema: + type: string + description: The ID or slug of the organization + - in: query + required: false + name: include_members_count + description: Flag to denote whether or not the organization's members count should be included in the response. + schema: + type: boolean + - in: query + required: false + name: include_missing_member_with_elevated_permissions + description: Flag to denote whether or not to include a member with elevated permissions who is not currently a member of the organization. + schema: + type: boolean + responses: + '200': + $ref: '#/components/responses/Organization' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + patch: + operationId: UpdateOrganization + x-speakeasy-group: organizations + x-speakeasy-name-override: update + summary: Update an organization + description: Updates an existing organization + tags: + - Organizations + parameters: + - in: path + name: organization_id + required: true + schema: + type: string + description: The ID of the organization to update + requestBody: + required: true + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + public_metadata: + type: object + description: Metadata saved on the organization, that is visible to both your frontend and backend. + additionalProperties: true + nullable: true + private_metadata: + type: object + description: Metadata saved on the organization that is only visible to your backend. + additionalProperties: true + nullable: true + name: + type: string + description: |- + The new name of the organization. + May not contain URLs or HTML. + Max length: 256 + nullable: true + slug: + type: string + description: The new slug of the organization, which needs to be unique in the instance + nullable: true + max_allowed_memberships: + type: integer + minimum: 0 + description: The maximum number of memberships allowed for this organization + nullable: true + admin_delete_enabled: + type: boolean + description: If true, an admin can delete this organization with the Frontend API. + nullable: true + created_at: + type: string + description: A custom date/time denoting _when_ the organization was created, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`). + nullable: true + responses: + '200': + $ref: '#/components/responses/Organization' + '402': + $ref: '#/components/responses/ResourceNotFound' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + delete: + operationId: DeleteOrganization + x-speakeasy-group: organizations + x-speakeasy-name-override: delete + summary: Delete an organization + description: |- + Deletes the given organization. + Please note that deleting an organization will also delete all memberships and invitations. + This is not reversible. + tags: + - Organizations + parameters: + - in: path + name: organization_id + required: true + schema: + type: string + description: The ID of the organization to delete + responses: + '200': + $ref: '#/components/responses/DeletedObject' + '404': + $ref: '#/components/responses/ResourceNotFound' + /organizations/{organization_id}/metadata: + patch: + operationId: MergeOrganizationMetadata + x-speakeasy-group: organizations + x-speakeasy-name-override: mergeMetadata + summary: Merge and update metadata for an organization + description: |- + Update organization metadata attributes by merging existing values with the provided parameters. + Metadata values will be updated via a deep merge. + Deep meaning that any nested JSON objects will be merged as well. + You can remove metadata keys at any level by setting their value to `null`. + tags: + - Organizations + parameters: + - name: organization_id + in: path + description: The ID of the organization for which metadata will be merged or updated + required: true + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + public_metadata: + type: object + description: |- + Metadata saved on the organization, that is visible to both your frontend and backend. + The new object will be merged with the existing value. + additionalProperties: true + private_metadata: + type: object + description: |- + Metadata saved on the organization that is only visible to your backend. + The new object will be merged with the existing value. + additionalProperties: true + responses: + '200': + $ref: '#/components/responses/Organization' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /organizations/{organization_id}/logo: + put: + operationId: UploadOrganizationLogo + x-speakeasy-group: organizations + x-speakeasy-name-override: uploadLogo + summary: Upload a logo for the organization + description: |- + Set or replace an organization's logo, by uploading an image file. + This endpoint uses the `multipart/form-data` request content type and accepts a file of image type. + The file size cannot exceed 10MB. + Only the following file content types are supported: `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `image/x-icon`, `image/vnd.microsoft.icon`. + tags: + - Organizations + parameters: + - name: organization_id + in: path + description: The ID of the organization for which to upload a logo + required: true + schema: + type: string + requestBody: + content: + multipart/form-data: + schema: + type: object + properties: + uploader_user_id: + type: string + description: The ID of the user that will be credited with the image upload. + file: + type: string + format: binary + required: + - file + responses: + '200': + $ref: '#/components/responses/OrganizationWithLogo' + '400': + $ref: '#/components/responses/ClerkErrors' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '413': + $ref: '#/components/responses/ClerkErrors' + delete: + operationId: DeleteOrganizationLogo + x-speakeasy-group: organizations + x-speakeasy-name-override: deleteLogo + summary: Delete the organization's logo. + description: Delete the organization's logo. + tags: + - Organizations + parameters: + - name: organization_id + in: path + description: The ID of the organization for which the logo will be deleted. + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/Organization' + '404': + $ref: '#/components/responses/ResourceNotFound' + /organizations/{organization_id}/invitations: + post: + operationId: CreateOrganizationInvitation + x-speakeasy-group: organizationInvitations + x-speakeasy-name-override: create + summary: Create and send an organization invitation + description: |- + Creates a new organization invitation and sends an email to the provided `email_address` with a link to accept the invitation and join the organization. + You can specify the `role` for the invited organization member. + + New organization invitations get a "pending" status until they are revoked by an organization administrator or accepted by the invitee. + + The request body supports passing an optional `redirect_url` parameter. + When the invited user clicks the link to accept the invitation, they will be redirected to the URL provided. + Use this parameter to implement a custom invitation acceptance flow. + + You can specify the ID of the user that will send the invitation with the `inviter_user_id` parameter. + That user must be a member with administrator privileges in the organization. + Only "admin" members can create organization invitations. + + You can optionally provide public and private metadata for the organization invitation. + The public metadata are visible by both the Frontend and the Backend whereas the private ones only by the Backend. + When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership. + tags: + - Organization Invitations + parameters: + - in: path + required: true + name: organization_id + schema: + type: string + description: The ID of the organization for which to send the invitation + requestBody: + content: + application/json: + schema: + type: object + properties: + email_address: + type: string + description: The email address of the new member that is going to be invited to the organization + inviter_user_id: + type: string + nullable: true + description: |- + The ID of the user that invites the new member to the organization. + Must be an administrator in the organization. + role: + type: string + description: The role of the new member in the organization + public_metadata: + type: object + description: |- + Metadata saved on the organization invitation, read-only from the Frontend API and fully accessible (read/write) from the Backend API. + When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership. + additionalProperties: true + nullable: true + private_metadata: + type: object + description: |- + Metadata saved on the organization invitation, fully accessible (read/write) from the Backend API but not visible from the Frontend API. + When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership. + additionalProperties: true + nullable: true + redirect_url: + type: string + description: Optional URL that the invitee will be redirected to once they accept the invitation by clicking the join link in the invitation email. + nullable: true + expires_in_days: + type: integer + description: The number of days the invitation will be valid for. By default, the invitation has a 30 days expire. + nullable: true + minimum: 1 + maximum: 365 + required: + - email_address + - role + responses: + '200': + $ref: '#/components/responses/OrganizationInvitation' + '400': + $ref: '#/components/responses/ClerkErrors' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + get: + operationId: ListOrganizationInvitations + x-speakeasy-group: organizationInvitations + x-speakeasy-name-override: list + summary: Get a list of organization invitations + description: |- + This request returns the list of organization invitations. + Results can be paginated using the optional `limit` and `offset` query parameters. + You can filter them by providing the 'status' query parameter, that accepts multiple values. + The organization invitations are ordered by descending creation date. + Most recent invitations will be returned first. + Any invitations created as a result of an Organization Domain are not included in the results. + tags: + - Organization Invitations + parameters: + - in: path + required: true + name: organization_id + schema: + type: string + description: The organization ID. + - in: query + name: status + description: Filter organization invitations based on their status + required: false + schema: + type: string + enum: + - pending + - accepted + - revoked + - in: query + required: false + name: email_address + description: Returns organization invitations inviting the specified email address. + schema: + type: string + - in: query + name: order_by + required: false + description: |- + Allows to return organization invitations in a particular order. + You can order the returned organization invitations either by their `created_at` or `email_address`. + In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. + For example, if you want organization invitations to be returned in descending order according to their `created_at` property, you can use `-created_at`. + If you don't use `+` or `-`, then `+` is implied. + Defaults to `-created_at`. + schema: + type: string + default: '-created_at' + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' + responses: + '200': + $ref: '#/components/responses/OrganizationInvitations' + '400': + $ref: '#/components/responses/ClerkErrors' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /organizations/{organization_id}/invitations/bulk: + post: + operationId: CreateOrganizationInvitationBulk + x-speakeasy-group: organizationInvitations + x-speakeasy-name-override: bulkCreate + summary: Bulk create and send organization invitations + description: |- + Creates new organization invitations in bulk and sends out emails to the provided email addresses with a link to accept the invitation and join the organization. + You can specify a different `role` for each invited organization member. + New organization invitations get a "pending" status until they are revoked by an organization administrator or accepted by the invitee. + The request body supports passing an optional `redirect_url` parameter for each invitation. + When the invited user clicks the link to accept the invitation, they will be redirected to the provided URL. + Use this parameter to implement a custom invitation acceptance flow. + You can specify the ID of the user that will send the invitation with the `inviter_user_id` parameter. Each invitation + can have a different inviter user. + Inviter users must be members with administrator privileges in the organization. + Only "admin" members can create organization invitations. + You can optionally provide public and private metadata for each organization invitation. The public metadata are visible + by both the Frontend and the Backend, whereas the private metadata are only visible by the Backend. + When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership. + tags: + - Organization Invitations + parameters: + - in: path + required: true + name: organization_id + schema: + type: string + description: The organization ID. + requestBody: + required: true + content: + application/json: + schema: + type: array + items: + type: object + properties: + email_address: + type: string + description: The email address of the new member that is going to be invited to the organization + inviter_user_id: + type: string + nullable: true + description: |- + The ID of the user that invites the new member to the organization. + Must be an administrator in the organization. + role: + type: string + description: The role of the new member in the organization + public_metadata: + type: object + description: |- + Metadata saved on the organization invitation, read-only from the Frontend API and fully accessible (read/write) from the Backend API. + When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership. + additionalProperties: true + nullable: true + private_metadata: + type: object + description: |- + Metadata saved on the organization invitation, fully accessible (read/write) from the Backend API but not visible from the Frontend API. + When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership. + additionalProperties: true + nullable: true + redirect_url: + type: string + description: Optional URL that the invitee will be redirected to once they accept the invitation by clicking the join link in the invitation email. + nullable: true + expires_in_days: + type: integer + description: The number of days the invitation will be valid for. By default, the invitation has a 30 days expire. + nullable: true + minimum: 1 + maximum: 365 + required: + - email_address + - role + responses: + '200': + $ref: '#/components/responses/OrganizationInvitations' + '400': + $ref: '#/components/responses/ClerkErrors' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /organizations/{organization_id}/invitations/pending: + get: + deprecated: true + operationId: ListPendingOrganizationInvitations + x-speakeasy-group: organizationInvitations + x-speakeasy-name-override: listPending + summary: Get a list of pending organization invitations + description: |- + This request returns the list of organization invitations with "pending" status. + These are the organization invitations that can still be used to join the organization, but have not been accepted by the invited user yet. + Results can be paginated using the optional `limit` and `offset` query parameters. + The organization invitations are ordered by descending creation date. + Most recent invitations will be returned first. + Any invitations created as a result of an Organization Domain are not included in the results. + tags: + - Organization Invitations + parameters: + - in: path + required: true + name: organization_id + schema: + type: string + description: The organization ID. + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' + responses: + '200': + $ref: '#/components/responses/OrganizationInvitations' + '400': + $ref: '#/components/responses/ClerkErrors' + '404': + $ref: '#/components/responses/ResourceNotFound' + /organizations/{organization_id}/invitations/{invitation_id}: + get: + operationId: GetOrganizationInvitation + x-speakeasy-group: organizationInvitations + x-speakeasy-name-override: get + summary: Retrieve an organization invitation by ID + description: Use this request to get an existing organization invitation by ID. + tags: + - Organization Invitations + parameters: + - in: path + required: true + name: organization_id + schema: + type: string + description: The organization ID. + - in: path + required: true + name: invitation_id + schema: + type: string + description: The organization invitation ID. + responses: + '200': + $ref: '#/components/responses/OrganizationInvitation' + '400': + $ref: '#/components/responses/ClerkErrors' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + /organizations/{organization_id}/invitations/{invitation_id}/revoke: + post: + operationId: RevokeOrganizationInvitation + x-speakeasy-group: organizationInvitations + x-speakeasy-name-override: revoke + summary: Revoke a pending organization invitation + description: |- + Use this request to revoke a previously issued organization invitation. + Revoking an organization invitation makes it invalid; the invited user will no longer be able to join the organization with the revoked invitation. + Only organization invitations with "pending" status can be revoked. + The request accepts the `requesting_user_id` parameter to specify the user which revokes the invitation. + Only users with "admin" role can revoke invitations. + tags: + - Organization Invitations + parameters: + - in: path + required: true + name: organization_id + schema: + type: string + description: The organization ID. + - in: path + required: true + name: invitation_id + schema: + type: string + description: The organization invitation ID. + requestBody: + required: false + content: + application/json: + schema: + type: object + properties: + requesting_user_id: + type: string + nullable: true + description: |- + The ID of the user that revokes the invitation. + Must be an administrator in the organization. + responses: + '200': + $ref: '#/components/responses/OrganizationInvitation' + '400': + $ref: '#/components/responses/ClerkErrors' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + /organizations/{organization_id}/memberships: + post: + operationId: CreateOrganizationMembership + x-speakeasy-group: organizationMemberships + x-speakeasy-name-override: create + summary: Create a new organization membership + description: |- + Adds a user as a member to the given organization. + Only users in the same instance as the organization can be added as members. + + This organization will be the user's [active organization] (https://clerk.com/docs/organizations/overview#active-organization) + the next time they create a session, presuming they don't explicitly set a + different organization as active before then. + tags: + - Organization Memberships + parameters: + - in: path + required: true + name: organization_id + schema: + type: string + description: The ID of the organization where the new membership will be created + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + user_id: + type: string + description: |- + The ID of the user that will be added as a member in the organization. + The user needs to exist in the same instance as the organization and must not be a member of the given organization already. + role: + type: string + description: The role that the new member will have in the organization. + required: + - user_id + - role + responses: + '200': + $ref: '#/components/responses/OrganizationMembership' + '400': + $ref: '#/components/responses/ClerkErrors' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + get: + operationId: ListOrganizationMemberships + x-speakeasy-group: organizationMemberships + x-speakeasy-name-override: list + summary: Get a list of all members of an organization + description: Retrieves all user memberships for the given organization + tags: + - Organization Memberships + parameters: + - in: path + required: true + name: organization_id + schema: + type: string + description: The organization ID. + - in: query + required: false + name: order_by + description: |- + Sorts organizations memberships by phone_number, email_address, created_at, first_name, last_name or username. + By prepending one of those values with + or -, we can choose to sort in ascending (ASC) or descending (DESC) order." + schema: + type: string + - name: user_id + in: query + schema: + type: array + items: + type: string + description: |- + Returns users with the user ids specified. For each user id, the `+` and `-` can be + prepended to the id, which denote whether the respective user id should be included or + excluded from the result set. Accepts up to 100 user ids. Any user ids not found are ignored. + required: false + - name: email_address + in: query + schema: + type: array + items: + type: string + description: Returns users with the specified email addresses. Accepts up to 100 email addresses. Any email addresses not found are ignored. + required: false + - name: phone_number + in: query + schema: + type: array + items: + type: string + description: Returns users with the specified phone numbers. Accepts up to 100 phone numbers. Any phone numbers not found are ignored. + required: false + - name: username + in: query + schema: + type: array + items: + type: string + description: |- + Returns users with the specified usernames. + Accepts up to 100 usernames. + Any usernames not found are ignored. + required: false + - name: web3_wallet + in: query + schema: + type: array + items: + type: string + description: |- + Returns users with the specified web3 wallet addresses. + Accepts up to 100 web3 wallet addresses. + Any web3 wallet addressed not found are ignored. + required: false + - name: role + in: query + schema: + type: array + items: + type: string + description: Returns users with the specified roles. Accepts up to 100 roles. Any roles not found are ignored. + required: false + - name: query + in: query + description: |- + Returns users that match the given query. + For possible matches, we check the email addresses, phone numbers, usernames, web3 wallets, user ids, first and last names. + The query value doesn't need to match the exact value you are looking for, it is capable of partial matches as well. + schema: + type: string + required: false + - name: email_address_query + in: query + description: |- + Returns users with emails that match the given query, via case-insensitive partial match. + For example, `email_address_query=ello` will match a user with the email `HELLO@example.com`. + schema: + type: string + required: false + - name: phone_number_query + in: query + description: |- + Returns users with phone numbers that match the given query, via case-insensitive partial match. + For example, `phone_number_query=555` will match a user with the phone number `+1555xxxxxxx`. + schema: + type: string + required: false + - name: username_query + in: query + description: |- + Returns users with usernames that match the given query, via case-insensitive partial match. + For example, `username_query=CoolUser` will match a user with the username `SomeCoolUser`. + schema: + type: string + - name: name_query + in: query + description: Returns users with names that match the given query, via case-insensitive partial match. + schema: + type: string + - name: last_active_at_before + in: query + description: |- + Returns users whose last session activity was before the given date (with millisecond precision). + Example: use 1700690400000 to retrieve users whose last session activity was before 2023-11-23. + example: 1700690400000 + schema: + type: integer + - name: last_active_at_after + in: query + description: |- + Returns users whose last session activity was after the given date (with millisecond precision). + Example: use 1700690400000 to retrieve users whose last session activity was after 2023-11-23. + example: 1700690400000 + schema: + type: integer + - name: created_at_before + in: query + description: |- + Returns users who have been created before the given date (with millisecond precision). + Example: use 1730160000000 to retrieve users who have been created before 2024-10-29. + example: 1730160000000 + schema: + type: integer + - name: created_at_after + in: query + description: |- + Returns users who have been created after the given date (with millisecond precision). + Example: use 1730160000000 to retrieve users who have been created after 2024-10-29. + example: 1730160000000 + schema: + type: integer + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' + responses: + '200': + $ref: '#/components/responses/OrganizationMemberships' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /organizations/{organization_id}/memberships/{user_id}: + patch: + operationId: UpdateOrganizationMembership + x-speakeasy-group: organizationMemberships + x-speakeasy-name-override: update + summary: Update an organization membership + description: Updates the properties of an existing organization membership + tags: + - Organization Memberships + parameters: + - in: path + required: true + name: organization_id + schema: + type: string + description: The ID of the organization the membership belongs to + - in: path + required: true + name: user_id + schema: + type: string + description: The ID of the user that this membership belongs to + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + role: + type: string + description: The new role of the given membership. + required: + - role + responses: + '200': + $ref: '#/components/responses/OrganizationMembership' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + delete: + operationId: DeleteOrganizationMembership + x-speakeasy-group: organizationMemberships + x-speakeasy-name-override: delete + summary: Remove a member from an organization + description: Removes the given membership from the organization + tags: + - Organization Memberships + parameters: + - in: path + required: true + name: organization_id + schema: + type: string + description: The ID of the organization the membership belongs to + - in: path + required: true + name: user_id + schema: + type: string + description: The ID of the user that this membership belongs to + responses: + '200': + $ref: '#/components/responses/OrganizationMembership' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /organizations/{organization_id}/memberships/{user_id}/metadata: + patch: + operationId: UpdateOrganizationMembershipMetadata + x-speakeasy-group: organizationMemberships + x-speakeasy-name-override: updateMetadata + summary: Merge and update organization membership metadata + description: |- + Update an organization membership's metadata attributes by merging existing values with the provided parameters. + Metadata values will be updated via a deep merge. Deep means that any nested JSON objects will be merged as well. + You can remove metadata keys at any level by setting their value to `null`. + tags: + - Organization Memberships + parameters: + - in: path + required: true + name: organization_id + schema: + type: string + description: The ID of the organization the membership belongs to + - in: path + required: true + name: user_id + schema: + type: string + description: The ID of the user that this membership belongs to + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + public_metadata: + type: object + description: |- + Metadata saved on the organization membership, that is visible to both your frontend and backend. + The new object will be merged with the existing value. + additionalProperties: true + private_metadata: + type: object + description: |- + Metadata saved on the organization membership that is only visible to your backend. + The new object will be merged with the existing value. + additionalProperties: true + responses: + '200': + $ref: '#/components/responses/OrganizationMembership' + '400': + $ref: '#/components/responses/ClerkErrors' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /organizations/{organization_id}/domains: + post: + operationId: CreateOrganizationDomain + x-speakeasy-group: organizationDomains + x-speakeasy-name-override: create + summary: Create a new organization domain. + description: Creates a new organization domain. By default the domain is verified, but can be optionally set to unverified. + tags: + - Organization Domains + parameters: + - in: path + required: true + name: organization_id + schema: + type: string + description: The ID of the organization where the new domain will be created. + requestBody: + required: true + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + name: + type: string + description: The name of the new domain + nullable: false + enrollment_mode: + type: string + description: The enrollment_mode for the new domain. This can be `automatic_invitation`, `automatic_suggestion` or `manual_invitation` + nullable: false + verified: + type: boolean + description: The status of domain's verification. Defaults to true + nullable: true + responses: + '200': + $ref: '#/components/responses/OrganizationDomain' + '400': + $ref: '#/components/responses/ClerkErrors' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + get: + operationId: ListOrganizationDomains + x-speakeasy-group: organizationDomains + x-speakeasy-name-override: list + summary: Get a list of all domains of an organization. + description: Get a list of all domains of an organization. + tags: + - Organization Domains + parameters: + - in: path + required: true + name: organization_id + schema: + type: string + description: The organization ID. + - in: query + required: false + name: verified + description: Filter domains by their verification status. `true` or `false` + schema: + type: string + - in: query + required: false + name: enrollment_mode + description: Filter domains by their enrollment mode + schema: + type: string + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' + responses: + '200': + $ref: '#/components/responses/OrganizationDomains' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /organizations/{organization_id}/domains/{domain_id}: + patch: + operationId: UpdateOrganizationDomain + x-speakeasy-group: organizationDomains + x-speakeasy-name-override: update + summary: Update an organization domain. + description: Updates the properties of an existing organization domain. + tags: + - Organization Domains + parameters: + - in: path + required: true + name: organization_id + schema: + type: string + description: The ID of the organization the domain belongs to + - in: path + required: true + name: domain_id + schema: + type: string + description: The ID of the domain + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + enrollment_mode: + type: string + description: The enrollment_mode for the new domain. This can be `automatic_invitation`, `automatic_suggestion` or `manual_invitation` + nullable: true + verified: + type: boolean + description: The status of the domain's verification + nullable: true + responses: + '200': + $ref: '#/components/responses/OrganizationDomain' + '400': + $ref: '#/components/responses/ClerkErrors' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + delete: + operationId: DeleteOrganizationDomain + x-speakeasy-group: organizationDomains + x-speakeasy-name-override: delete + summary: Remove a domain from an organization. + description: Removes the given domain from the organization. + tags: + - Organization Domains + parameters: + - in: path + required: true + name: organization_id + schema: + type: string + description: The ID of the organization the domain belongs to + - in: path + required: true + name: domain_id + schema: + type: string + description: The ID of the domain + responses: + '200': + $ref: '#/components/responses/DeletedObject' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + /organization_domains: + get: + operationId: ListAllOrganizationDomains + x-speakeasy-group: organizationDomains + x-speakeasy-name-override: listAll + summary: List all organization domains + description: | + Retrieves a list of all organization domains within the current instance. + This endpoint can be used to list all domains across all organizations + or filter domains by organization, verification status, enrollment mode, or search query. + + The response includes pagination information and details about each domain + including its verification status, enrollment mode, and associated counts. + tags: + - Organization Domains + parameters: + - in: query + name: organization_id + description: The ID of the organization to filter domains by + required: false + schema: + type: string + - in: query + name: verified + description: Filter by verification status + required: false + schema: + type: string + enum: + - 'true' + - 'false' + - in: query + name: enrollment_mode + description: Filter by enrollment mode + required: false + style: form + explode: false + schema: + type: array + items: + type: string + enum: + - manual_invitation + - automatic_invitation + - automatic_suggestion + - in: query + name: query + description: | + Search domains by name or organization ID. + If the query starts with "org_", it will search by exact organization ID match. + Otherwise, it performs a case-insensitive partial match on the domain name. + + Note: An empty string or whitespace-only value is not allowed and will result in a validation error. + required: false + schema: + type: string + - in: query + name: order_by + description: | + Allows to return organization domains in a particular order. + At the moment, you can order the returned domains by their `name` or `created_at`. + In order to specify the direction, you can use the `+/-` symbols prepended to the property to order by. + For example, if you want domains to be returned in descending order according to their `created_at` property, you can use `-created_at`. + If you don't use `+` or `-`, then `+` is implied. + Defaults to `-created_at`. + required: false + schema: + type: string + default: '-created_at' + - $ref: '#/components/parameters/OffsetParameter' + - $ref: '#/components/parameters/LimitParameter' + responses: + '200': + $ref: '#/components/responses/OrganizationDomains' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /proxy_checks: + post: + summary: Verify the proxy configuration for your domain + x-speakeasy-group: proxyChecks + x-speakeasy-name-override: verify + description: |- + This endpoint can be used to validate that a proxy-enabled domain is operational. + It tries to verify that the proxy URL provided in the parameters maps to a functional proxy that can reach the Clerk Frontend API. + + You can use this endpoint before you set a proxy URL for a domain. This way you can ensure that switching to proxy-based + configuration will not lead to downtime for your instance. + + The `proxy_url` parameter allows for testing proxy configurations for domains that don't have a proxy URL yet, or operate on + a different proxy URL than the one provided. It can also be used to re-validate a domain that is already configured to work with a proxy. + operationId: VerifyDomainProxy + tags: + - Proxy Checks + requestBody: + content: + application/json: + schema: + type: object + properties: + domain_id: + type: string + description: The ID of the domain that will be updated. + proxy_url: + type: string + description: The full URL of the proxy which will forward requests to the Clerk Frontend API for this domain. e.g. https://example.com/__clerk + responses: + '200': + $ref: '#/components/responses/ProxyCheck' + '400': + $ref: '#/components/responses/ClerkErrors' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /redirect_urls: + get: + summary: List all redirect URLs + x-speakeasy-group: redirectUrls + x-speakeasy-name-override: list + description: Lists all whitelisted redirect_urls for the instance + operationId: ListRedirectURLs + tags: + - Redirect URLs + parameters: + - $ref: '#/components/parameters/Paginated' + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' + responses: + '200': + $ref: '#/components/responses/RedirectURL.List' + post: + summary: Create a redirect URL + x-speakeasy-group: redirectUrls + x-speakeasy-name-override: create + description: Create a redirect URL + operationId: CreateRedirectURL + tags: + - Redirect URLs + requestBody: + content: + application/json: + schema: + type: object + properties: + url: + type: string + description: The full url value prefixed with `https://` or a custom scheme e.g. `"https://my-app.com/oauth-callback"` or `"my-app://oauth-callback"` + required: + - url + responses: + '200': + $ref: '#/components/responses/RedirectURL' + '400': + $ref: '#/components/responses/ClerkErrors' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /redirect_urls/{id}: + get: + summary: Retrieve a redirect URL + x-speakeasy-group: redirectUrls + x-speakeasy-name-override: get + description: Retrieve the details of the redirect URL with the given ID + operationId: GetRedirectURL + tags: + - Redirect URLs + parameters: + - name: id + in: path + description: The ID of the redirect URL + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/RedirectURL' + '404': + $ref: '#/components/responses/ResourceNotFound' + delete: + summary: Delete a redirect URL + x-speakeasy-group: redirectUrls + x-speakeasy-name-override: delete + description: Remove the selected redirect URL from the whitelist of the instance + operationId: DeleteRedirectURL + tags: + - Redirect URLs + parameters: + - name: id + in: path + description: The ID of the redirect URL + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/DeletedObject' + '404': + $ref: '#/components/responses/ResourceNotFound' + /sign_in_tokens: + post: + summary: Create sign-in token + x-speakeasy-group: signInTokens + x-speakeasy-name-override: create + description: |- + Creates a new sign-in token and associates it with the given user. + By default, sign-in tokens expire in 30 days. + You can optionally supply a different duration in seconds using the `expires_in_seconds` property. + operationId: CreateSignInToken + tags: + - Sign-in Tokens + requestBody: + content: + application/json: + schema: + type: object + properties: + user_id: + type: string + description: The ID of the user that can use the newly created sign in token + expires_in_seconds: + type: integer + description: |- + Optional parameter to specify the life duration of the sign in token in seconds. + By default, the duration is 30 days. + minimum: 1 + default: 2592000 + nullable: true + required: + - user_id + responses: + '200': + $ref: '#/components/responses/SignInToken' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /sign_in_tokens/{sign_in_token_id}/revoke: + post: + operationId: RevokeSignInToken + x-speakeasy-group: signInTokens + x-speakeasy-name-override: revoke + summary: Revoke the given sign-in token + description: Revokes a pending sign-in token + tags: + - Sign-in Tokens + parameters: + - name: sign_in_token_id + in: path + description: The ID of the sign-in token to be revoked + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/SignInToken' + '400': + $ref: '#/components/responses/ClerkErrors' + '404': + $ref: '#/components/responses/ResourceNotFound' + /sign_ups/{id}: + get: + operationId: GetSignUp + x-speakeasy-group: signUps + x-speakeasy-name-override: get + summary: Retrieve a sign-up by ID + description: Retrieve the details of the sign-up with the given ID + tags: + - Sign Ups + parameters: + - name: id + in: path + description: The ID of the sign-up to retrieve + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/SignUp' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + patch: + operationId: UpdateSignUp + x-speakeasy-group: signUps + x-speakeasy-name-override: update + summary: Update a sign-up + description: Update the sign-up with the given ID + tags: + - Sign Ups + parameters: + - name: id + in: path + description: The ID of the sign-up to update + required: true + schema: + type: string + requestBody: + content: + application/json: + schema: + type: object + properties: + external_id: + type: string + description: |- + The ID of the guest attempting to sign up as used in your external systems or your previous authentication solution. + This will be copied to the resulting user when the sign-up is completed. + nullable: true + custom_action: + type: boolean + description: If true, the sign-up will be marked as a custom action. + nullable: true + responses: + '200': + $ref: '#/components/responses/SignUp' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + /oauth_applications: + get: + operationId: ListOAuthApplications + x-speakeasy-group: oauthApplications + x-speakeasy-name-override: list + summary: Get a list of OAuth applications for an instance + description: |- + This request returns the list of OAuth applications for an instance. + Results can be paginated using the optional `limit` and `offset` query parameters. + The OAuth applications are ordered by descending creation date. + Most recent OAuth applications will be returned first. + tags: + - OAuth Applications + parameters: + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' + - name: order_by + in: query + description: |- + Allows to return OAuth applications in a particular order. + At the moment, you can order the returned OAuth applications by their `created_at` and `name`. + In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by. + For example, if you want OAuth applications to be returned in descending order according to their `created_at` property, you can use `-created_at`. + If you don't use `+` or `-`, then `+` is implied. We only support one `order_by` parameter, and if multiple `order_by` parameters are provided, we will only keep the first one. For example, + if you pass `order_by=name&order_by=created_at`, we will consider only the first `order_by` parameter, which is `name`. The `created_at` parameter will be ignored in this case. + required: false + schema: + type: string + default: +created_at + - name: name_query + in: query + description: Returns OAuth applications with names that match the given query, via case-insensitive partial match. + required: false + schema: + type: string + responses: + '200': + $ref: '#/components/responses/OAuthApplications' + '400': + $ref: '#/components/responses/ClerkErrors' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + post: + operationId: CreateOAuthApplication + x-speakeasy-group: oauthApplications + x-speakeasy-name-override: create + summary: Create an OAuth application + description: |- + Creates a new OAuth application with the given name and callback URL for an instance. + The callback URL must be a valid url. + All URL schemes are allowed such as `http://`, `https://`, `myapp://`, etc... + tags: + - OAuth Applications + requestBody: + content: + application/json: + schema: + type: object + properties: + name: + type: string + description: |- + The name of the new OAuth application. + Max length: 256 + redirect_uris: + type: array + items: + type: string + description: An array of redirect URIs of the new OAuth application + nullable: true + callback_url: + type: string + maxLength: 1024 + description: The callback URL of the new OAuth application + nullable: true + deprecated: true + scopes: + type: string + maxLength: 1024 + description: Define the allowed scopes for the new OAuth applications that dictate the user payload of the OAuth user info endpoint. Available scopes are `profile`, `email`, `public_metadata`, `private_metadata`. Provide the requested scopes as a string, separated by spaces. + default: profile email + example: profile email public_metadata + nullable: true + consent_screen_enabled: + type: boolean + default: true + description: True to enable a consent screen to display in the authentication flow. + nullable: true + pkce_required: + type: boolean + default: false + description: True to require the Proof Key of Code Exchange (PKCE) flow. + nullable: true + public: + type: boolean + description: If true, this client is public and you can use the Proof Key of Code Exchange (PKCE) flow. + nullable: true + required: + - name + responses: + '200': + $ref: '#/components/responses/OAuthApplicationWithSecret' + '400': + $ref: '#/components/responses/ClerkErrors' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /oauth_applications/{oauth_application_id}: + get: + operationId: GetOAuthApplication + x-speakeasy-group: oauthApplications + x-speakeasy-name-override: get + summary: Retrieve an OAuth application by ID + description: Fetches the OAuth application whose ID matches the provided `id` in the path. + tags: + - OAuth Applications + parameters: + - in: path + name: oauth_application_id + required: true + schema: + type: string + description: The ID of the OAuth application + responses: + '200': + $ref: '#/components/responses/OAuthApplication' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + patch: + operationId: UpdateOAuthApplication + x-speakeasy-group: oauthApplications + x-speakeasy-name-override: update + summary: Update an OAuth application + description: Updates an existing OAuth application + tags: + - OAuth Applications + parameters: + - in: path + name: oauth_application_id + required: true + schema: + type: string + description: The ID of the OAuth application to update + requestBody: + required: true + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + name: + type: string + description: |- + The new name of the OAuth application. + Max length: 256 + nullable: true + redirect_uris: + type: array + items: + type: string + description: An array of redirect URIs of the new OAuth application + nullable: true + callback_url: + type: string + maxLength: 1024 + description: The new callback URL of the OAuth application + nullable: true + deprecated: true + scopes: + type: string + maxLength: 1024 + description: Define the allowed scopes for the new OAuth applications that dictate the user payload of the OAuth user info endpoint. Available scopes are `profile`, `email`, `public_metadata`, `private_metadata`. Provide the requested scopes as a string, separated by spaces. + default: profile email + example: profile email public_metadata private_metadata + nullable: true + consent_screen_enabled: + type: boolean + description: True to enable a consent screen to display in the authentication flow. This cannot be disabled for dynamically registered OAuth Applications. + nullable: true + pkce_required: + type: boolean + description: True to require the Proof Key of Code Exchange (PKCE) flow. + nullable: true + public: + type: boolean + description: If true, this client is public and you can use the Proof Key of Code Exchange (PKCE) flow. + nullable: true + responses: + '200': + $ref: '#/components/responses/OAuthApplication' + '400': + $ref: '#/components/responses/ClerkErrors' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + delete: + operationId: DeleteOAuthApplication + x-speakeasy-group: oauthApplications + x-speakeasy-name-override: delete + summary: Delete an OAuth application + description: |- + Deletes the given OAuth application. + This is not reversible. + tags: + - OAuth Applications + parameters: + - in: path + name: oauth_application_id + required: true + schema: + type: string + description: The ID of the OAuth application to delete + responses: + '200': + $ref: '#/components/responses/DeletedObject' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + /oauth_applications/{oauth_application_id}/rotate_secret: + post: + operationId: RotateOAuthApplicationSecret + x-speakeasy-group: oauthApplications + x-speakeasy-name-override: rotateSecret + summary: Rotate the client secret of the given OAuth application + description: |- + Rotates the OAuth application's client secret. + When the client secret is rotated, make sure to update it in authorized OAuth clients. + tags: + - OAuth Applications + parameters: + - name: oauth_application_id + in: path + description: The ID of the OAuth application for which to rotate the client secret + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/OAuthApplicationWithSecret' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + /saml_connections: + get: + operationId: ListSAMLConnections + x-speakeasy-group: samlConnections + x-speakeasy-name-override: list + summary: Get a list of SAML Connections for an instance + description: |- + Returns the list of SAML Connections for an instance. + Results can be paginated using the optional `limit` and `offset` query parameters. + The SAML Connections are ordered by descending creation date and the most recent will be returned first. + tags: + - SAML Connections + parameters: + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' + - name: query + in: query + required: false + description: Returns SAML connections that have a name that matches the given query, via case-insensitive partial match. + schema: + type: string + - name: order_by + in: query + required: false + description: |- + Sorts organizations memberships by phone_number, email_address, created_at, first_name, last_name or username. + By prepending one of those values with + or -, + we can choose to sort in ascending (ASC) or descending (DESC) order. + schema: + type: string + - name: organization_id + in: query + schema: + type: array + items: + type: string + description: |- + Returns SAML connections that have an associated organization ID to the + given organizations. + For each organization id, the `+` and `-` can be + prepended to the id, which denote whether the + respective organization should be included or + excluded from the result set. + Accepts up to 100 organization ids. + responses: + '200': + $ref: '#/components/responses/SAMLConnections' + '402': + $ref: '#/components/responses/PaymentRequired' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + post: + operationId: CreateSAMLConnection + x-speakeasy-group: samlConnections + x-speakeasy-name-override: create + summary: Create a SAML Connection + description: Create a new SAML Connection. + tags: + - SAML Connections + requestBody: + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + name: + type: string + description: The name to use as a label for this SAML Connection + domain: + type: string + deprecated: true + description: The domain of your organization. Sign in flows using an email with this domain, will use this SAML Connection. + domains: + type: array + items: + type: string + description: The domains of your organization. Sign in flows using an email with one of these domains, will use this SAML Connection. + provider: + type: string + description: The IdP provider of the connection. + enum: + - saml_custom + - saml_okta + - saml_google + - saml_microsoft + idp_entity_id: + type: string + description: The Entity ID as provided by the IdP + nullable: true + idp_sso_url: + type: string + description: The Single-Sign On URL as provided by the IdP + nullable: true + idp_certificate: + type: string + description: The X.509 certificate as provided by the IdP + nullable: true + idp_metadata_url: + type: string + description: The URL which serves the IdP metadata. If present, it takes priority over the corresponding individual properties + nullable: true + idp_metadata: + type: string + description: The XML content of the IdP metadata file. If present, it takes priority over the corresponding individual properties + nullable: true + organization_id: + type: string + description: The ID of the organization to which users of this SAML Connection will be added + nullable: true + attribute_mapping: + type: object + description: Define the attribute name mapping between Identity Provider and Clerk's user properties + nullable: true + additionalProperties: false + properties: + user_id: + type: string + email_address: + type: string + first_name: + type: string + last_name: + type: string + required: + - name + - provider + anyOf: + - required: + - domain + - required: + - domains + responses: + '200': + $ref: '#/components/responses/SAMLConnection' + '402': + $ref: '#/components/responses/PaymentRequired' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /saml_connections/{saml_connection_id}: + get: + operationId: GetSAMLConnection + x-speakeasy-group: samlConnections + x-speakeasy-name-override: get + summary: Retrieve a SAML Connection by ID + description: Fetches the SAML Connection whose ID matches the provided `saml_connection_id` in the path. + tags: + - SAML Connections + parameters: + - in: path + name: saml_connection_id + required: true + schema: + type: string + description: The ID of the SAML Connection + responses: + '200': + $ref: '#/components/responses/SAMLConnection' + '402': + $ref: '#/components/responses/PaymentRequired' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + patch: + operationId: UpdateSAMLConnection + x-speakeasy-group: samlConnections + x-speakeasy-name-override: update + summary: Update a SAML Connection + description: Updates the SAML Connection whose ID matches the provided `id` in the path. + tags: + - SAML Connections + parameters: + - in: path + name: saml_connection_id + required: true + schema: + type: string + description: The ID of the SAML Connection to update + requestBody: + required: true + content: + application/json: + schema: + type: object + additionalProperties: false + properties: + name: + type: string + description: The name of the new SAML Connection + nullable: true + domain: + type: string + description: The domain to use for the new SAML Connection + deprecated: true + nullable: true + domains: + type: array + items: + type: string + nullable: true + description: A list of the domains on use for the SAML connection + idp_entity_id: + type: string + description: The entity id as provided by the IdP + nullable: true + idp_sso_url: + type: string + description: The SSO url as provided by the IdP + nullable: true + idp_certificate: + type: string + description: The x509 certificated as provided by the IdP + nullable: true + idp_metadata_url: + type: string + description: The URL which serves the IdP metadata. If present, it takes priority over the corresponding individual properties and replaces them + nullable: true + idp_metadata: + type: string + description: The XML content of the IdP metadata file. If present, it takes priority over the corresponding individual properties + nullable: true + organization_id: + type: string + description: The ID of the organization to which users of this SAML Connection will be added + nullable: true + attribute_mapping: + type: object + description: Define the atrtibute name mapping between Identity Provider and Clerk's user properties + nullable: true + additionalProperties: false + properties: + user_id: + type: string + email_address: + type: string + first_name: + type: string + last_name: + type: string + active: + type: boolean + description: Activate or de-activate the SAML Connection + nullable: true + sync_user_attributes: + type: boolean + description: Controls whether to update the user's attributes in each sign-in + nullable: true + allow_subdomains: + type: boolean + description: Allow users with an email address subdomain to use this connection in order to authenticate + nullable: true + allow_idp_initiated: + type: boolean + description: Enable or deactivate IdP-initiated flows + nullable: true + disable_additional_identifications: + type: boolean + description: Enable or deactivate additional identifications + nullable: true + responses: + '200': + $ref: '#/components/responses/SAMLConnection' + '402': + $ref: '#/components/responses/PaymentRequired' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + '422': + $ref: '#/components/responses/UnprocessableEntity' + delete: + operationId: DeleteSAMLConnection + x-speakeasy-group: samlConnections + x-speakeasy-name-override: delete + summary: Delete a SAML Connection + description: Deletes the SAML Connection whose ID matches the provided `id` in the path. + tags: + - SAML Connections + parameters: + - in: path + name: saml_connection_id + required: true + schema: + type: string + description: The ID of the SAML Connection to delete + responses: + '200': + $ref: '#/components/responses/DeletedObject' + '402': + $ref: '#/components/responses/PaymentRequired' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '404': + $ref: '#/components/responses/ResourceNotFound' + /testing_tokens: + post: + operationId: CreateTestingToken + x-speakeasy-group: testingTokens + x-speakeasy-name-override: create + summary: Retrieve a new testing token + description: Retrieve a new testing token. + tags: + - Testing Tokens + responses: + '200': + $ref: '#/components/responses/TestingToken' + /organization_memberships: + get: + operationId: InstanceGetOrganizationMemberships + x-speakeasy-group: users + x-speakeasy-name-override: getInstanceOrganizationMemberships + summary: Get a list of all organization memberships within an instance. + description: Retrieves all organization user memberships for the given instance. + tags: + - Organization Memberships + parameters: + - name: order_by + in: query + required: false + description: |- + Sorts organizations memberships by phone_number, email_address, created_at, first_name, last_name or username. + By prepending one of those values with + or -, + we can choose to sort in ascending (ASC) or descending (DESC) order. + schema: + type: string + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' + responses: + '200': + $ref: '#/components/responses/OrganizationMemberships' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + '500': + $ref: '#/components/responses/ClerkErrors' + /waitlist_entries: + get: + operationId: ListWaitlistEntries + x-speakeasy-group: waitlistEntries + x-speakeasy-name-override: list + summary: List all waitlist entries + description: |- + Retrieve a list of waitlist entries for the instance. + Entries are ordered by creation date in descending order by default. + Supports filtering by email address or status and pagination with limit and offset parameters. + tags: + - Waitlist Entries + parameters: + - $ref: '#/components/parameters/LimitParameter' + - $ref: '#/components/parameters/OffsetParameter' + - in: query + name: query + description: Filter waitlist entries by `email_address` or `id` + required: false + schema: + type: string + - in: query + name: status + description: Filter waitlist entries by their status + required: false + schema: + type: string + enum: + - pending + - invited + - completed + - rejected + - in: query + name: order_by + required: false + description: |- + Specify the order of results. Supported values are: + - `created_at` + - `email_address` + - `invited_at` + + Use `+` for ascending or `-` for descending order. Defaults to `-created_at`. + schema: + type: string + default: '-created_at' + responses: + '200': + $ref: '#/components/responses/WaitlistEntries' + post: + operationId: CreateWaitlistEntry + x-speakeasy-group: waitlistEntries + x-speakeasy-name-override: create + summary: Create a waitlist entry + description: |- + Creates a new waitlist entry for the given email address. + If the email address is already on the waitlist, no new entry will be created and the existing waitlist entry will be returned. + tags: + - Waitlist Entries + requestBody: + content: + application/json: + schema: + type: object + properties: + email_address: + type: string + description: The email address to add to the waitlist + notify: + type: boolean + description: |- + Optional flag which denotes whether a confirmation email should be sent to the given email address. + Defaults to `true`. + default: true + nullable: true + required: + - email_address + responses: + '200': + $ref: '#/components/responses/WaitlistEntry' + '400': + $ref: '#/components/responses/ClerkErrors' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /accountless_applications: + post: + operationId: CreateAccountlessApplication + x-speakeasy-group: experimentalAccountlessApplications + x-speakeasy-name-override: create + summary: Create an accountless application [EXPERIMENTAL] + description: Creates a new accountless application. [EXPERIMENTAL] + tags: + - Accountless Applications + responses: + '200': + $ref: '#/components/responses/AccountlessApplication' + '500': + $ref: '#/components/responses/ClerkErrors' + /accountless_applications/complete: + post: + operationId: CompleteAccountlessApplication + x-speakeasy-group: experimentalAccountlessApplications + x-speakeasy-name-override: complete + summary: Complete an accountless application [EXPERIMENTAL] + description: Completes an accountless application. [EXPERIMENTAL] + tags: + - Accountless Applications + responses: + '200': + $ref: '#/components/responses/AccountlessApplication' + '500': + $ref: '#/components/responses/ClerkErrors' + /management/users: + x-internal: true + post: + operationId: ManagementUpsertUser + x-speakeasy-group: management + x-speakeasy-name-override: upsertUser + tags: + - Management + summary: Upsert a user + description: | + Upsert a user using the provided information. If a user with the same email_address exists, it will be updated. Otherwise, a new user will be created. + This endpoint is internal and requires a specific management token for authorization. + security: + - managementToken: [] + requestBody: + description: User data to upsert. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ManagementUpsertUserRequest' + responses: + '200': + $ref: '#/components/responses/User' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /management/organizations: + x-internal: true + post: + operationId: ManagementCreateOrganization + x-speakeasy-group: management + x-speakeasy-name-override: createOrganization + tags: + - Management + summary: Create an organization + description: | + Create a new organization. + This endpoint is internal and requires a specific management token for authorization. + security: + - managementToken: [] + requestBody: + description: Organization data to create. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ManagementCreateOrganizationRequest' + responses: + '200': + $ref: '#/components/responses/Organization' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /management/applications: + x-internal: true + post: + operationId: ManagementCreateApplication + x-speakeasy-group: management + x-speakeasy-name-override: createApplication + tags: + - Management + summary: Create an application (instance) + description: | + Create a new application (instance). + This endpoint is internal and requires a specific management token for authorization. + security: + - managementToken: [] + requestBody: + description: Application data to create. + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ManagementCreateApplicationRequest' + responses: + '200': + description: Application created successfully. + content: + application/json: + schema: + $ref: '#/components/schemas/ManagementApplicationResponse' + '400': + $ref: '#/components/responses/ClerkErrors' + '401': + $ref: '#/components/responses/AuthenticationInvalid' + '403': + $ref: '#/components/responses/AuthorizationInvalid' + '422': + $ref: '#/components/responses/UnprocessableEntity' + /oauth_applications/access_tokens/verify: + post: + x-speakeasy-group: oauthAccessTokens + x-speakeasy-name-override: verify + operationId: verifyOAuthAccessToken + summary: Verify an OAuth Access Token + tags: + - OAuth Access Tokens + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + access_token: + type: string + description: The access token to verify. + example: XXXXXXXXXXXXXX + secret: + type: string + description: The access token to verify. This is deprecated, use `access_token` instead. + deprecated: true + example: XXXXXXXXXXXXXX + responses: + '200': + description: 200 OK + content: + application/json: + schema: + type: object + properties: + object: + type: string + enum: + - clerk_idp_oauth_access_token + example: clerk_idp_oauth_access_token + id: + type: string + pattern: ^oat_[0-9A-Fa-f]{32}$ + example: oat_0ef5a7a33d87ed87ee7954c845d80450 + client_id: + type: string + example: client_2xhFjEI5X2qWRvtV13BzSj8H6Dk + subject: + type: string + pattern: ^user_\w{27}$ + example: user_2xhFjEI5X2qWRvtV13BzSj8H6Dk + scopes: + type: array + items: + type: string + example: + - read + - write + revoked: + type: boolean + example: false + revocation_reason: + type: string + nullable: true + example: Revoked by user + expired: + type: boolean + example: false + expiration: + type: number + nullable: true + example: 1716883200 + created_at: + type: number + example: 1716883200 + updated_at: + type: number + example: 1716883200 + required: + - object + - id + - client_id + - subject + - scopes + - revoked + - revocation_reason + - expired + - expiration + - created_at + - updated_at + additionalProperties: false + '400': + description: 400 Bad Request + content: + application/json: + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + example: Bad Request + long_message: + type: string + example: 'Invalid ''url_parameter.example'': Failed regex check' + code: + type: string + example: bad_request + required: + - message + - long_message + - code + required: + - errors + '404': + description: 404 Not Found + content: + application/json: + schema: + type: object + properties: + errors: + type: array + items: + type: object + properties: + message: + type: string + example: some details about the error + long_message: + type: string + example: some details about the error + code: + type: string + example: some_error_code + required: + - message + - long_message + - code + required: + - errors +components: + securitySchemes: + bearerAuth: + type: http + scheme: bearer + description: Secret key, obtained under "API Keys" in the Clerk Dashboard. + bearerFormat: sk__ + managementToken: + type: http + scheme: bearer + description: Internal management token. + schemas: + JWKS.ed25519.PublicKey: + type: object + properties: + kid: + type: string + alg: + type: string + use: + type: string + kty: + type: string + enum: + - OKP + crv: + type: string + enum: + - Ed25519 + x: + type: string + x5c: + type: array + items: + type: string + x5t: + type: string + x5t#S256: + type: string + x5u: + type: string + required: + - kid + - alg + - use + - kty + - crv + - x + JWKS.ecdsa.PublicKey: + type: object + properties: + kid: + type: string + alg: + type: string + use: + type: string + kty: + type: string + enum: + - EC + crv: + type: string + x: + type: string + 'y': + type: string + x5c: + type: array + items: + type: string + x5t: + type: string + x5t#S256: + type: string + x5u: + type: string + required: + - kid + - alg + - use + - kty + - crv + - x + - 'y' + JWKS.rsa.PublicKey: + type: object + properties: + kid: + type: string + alg: + type: string + use: + type: string + kty: + type: string + enum: + - RSA + 'n': + type: string + e: + type: string + x5c: + type: array + items: + type: string + x5t: + type: string + x5t#S256: + type: string + x5u: + type: string + required: + - kid + - alg + - use + - kty + - 'n' + - e + JWKS.ed25519.PrivateKey: + type: object + properties: + kid: + type: string + alg: + type: string + use: + type: string + kty: + type: string + enum: + - OKP + crv: + type: string + enum: + - Ed25519 + x: + type: string + d: + type: string + x5c: + type: array + items: + type: string + x5t: + type: string + x5t#S256: + type: string + x5u: + type: string + required: + - kid + - alg + - use + - kty + - crv + - x + - d + JWKS.ecdsa.PrivateKey: + type: object + properties: + kid: + type: string + alg: + type: string + use: + type: string + kty: + type: string + enum: + - EC + crv: + type: string + x: + type: string + 'y': + type: string + d: + type: string + x5c: + type: array + items: + type: string + x5t: + type: string + x5t#S256: + type: string + x5u: + type: string + required: + - kid + - alg + - use + - kty + - crv + - x + - 'y' + - d + JWKS.rsa.PrivateKey: + type: object + properties: + kid: + type: string + alg: + type: string + use: + type: string + kty: + type: string + enum: + - RSA + 'n': + type: string + e: + type: string + d: + type: string + p: + type: string + q: + type: string + dp: + type: string + dq: + type: string + qi: + type: string + x5c: + type: array + items: + type: string + x5t: + type: string + x5t#S256: + type: string + x5u: + type: string + required: + - kid + - alg + - use + - kty + - crv + - 'n' + - e + - d + - p + - q + JWKS.symmetric.Key: + type: object + properties: + kid: + type: string + alg: + type: string + use: + type: string + kty: + type: string + enum: + - oct + k: + type: string + x5c: + type: array + items: + type: string + x5t: + type: string + x5t#S256: + type: string + x5u: + type: string + required: + - kid + - alg + - use + - kty + - k + JWKS: + type: object + additionalProperties: false + properties: + keys: + type: array + items: + oneOf: + - $ref: '#/components/schemas/JWKS.ed25519.PublicKey' + - $ref: '#/components/schemas/JWKS.ecdsa.PublicKey' + - $ref: '#/components/schemas/JWKS.rsa.PublicKey' + - $ref: '#/components/schemas/JWKS.ed25519.PrivateKey' + - $ref: '#/components/schemas/JWKS.ecdsa.PrivateKey' + - $ref: '#/components/schemas/JWKS.rsa.PrivateKey' + - $ref: '#/components/schemas/JWKS.symmetric.Key' + AWSCredential: + 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: + - aws_credential + access_key_id: + type: string + user_pool_ids: + type: array + items: + type: string + 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 + - access_key_id + - user_pool_ids + - created_at + - updated_at + ClerkError: + type: object + properties: + message: + type: string + long_message: + type: string + code: + type: string + meta: + type: object + clerk_trace_id: + type: string + 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 + DeletedObject: + type: object + additionalProperties: false + properties: + object: + type: string + id: + type: string + slug: + type: string + deleted: + type: boolean + required: + - object + - deleted + SessionActivityResponse: + type: object + nullable: true + properties: + object: + type: string + id: + type: string + device_type: + type: string + is_mobile: + type: boolean + browser_name: + type: string + browser_version: + type: string + ip_address: + type: string + city: + type: string + country: + type: string + required: + - id + - object + - is_mobile + SessionTask: + type: object + properties: + key: + type: string + required: + - key + Session: + type: object + additionalProperties: false + properties: + object: + type: string + description: | + String representing the object's type. Objects of the same type share the same value. + enum: + - session + id: + type: string + user_id: + type: string + client_id: + type: string + actor: + type: object + nullable: true + status: + type: string + enum: + - active + - revoked + - ended + - expired + - removed + - abandoned + - replaced + - pending + last_active_organization_id: + type: string + nullable: true + last_active_at: + type: integer + latest_activity: + $ref: '#/components/schemas/SessionActivityResponse' + expire_at: + type: integer + format: int64 + description: | + Unix timestamp of expiration. + abandon_at: + type: integer + format: int64 + description: | + Unix timestamp of abandonment. + updated_at: + type: integer + format: int64 + description: | + Unix timestamp of last update. + created_at: + type: integer + format: int64 + description: | + Unix timestamp of creation. + tasks: + type: array + nullable: true + items: + $ref: '#/components/schemas/SessionTask' + required: + - object + - id + - user_id + - client_id + - status + - last_active_at + - expire_at + - abandon_at + - updated_at + - created_at + Client: + type: object + additionalProperties: false + properties: + object: + type: string + description: | + String representing the object's type. Objects of the same type share the same value. + enum: + - client + id: + type: string + description: | + String representing the identifier of the session. + session_ids: + type: array + items: + type: string + sessions: + type: array + items: + $ref: '#/components/schemas/Session' + sign_in_id: + type: string + nullable: true + sign_up_id: + type: string + nullable: true + last_active_session_id: + nullable: true + type: string + description: | + Last active session_id. + updated_at: + type: integer + format: int64 + description: | + Unix timestamp of last update. + created_at: + type: integer + format: int64 + description: | + Unix timestamp of creation. + required: + - object + - id + - session_ids + - sessions + - sign_in_id + - sign_up_id + - last_active_session_id + - updated_at + - created_at + OTP: + type: object + additionalProperties: false + properties: + status: + type: string + enum: + - unverified + - verified + - failed + - expired + strategy: + x-speakeasy-unknown-values: allow + type: string + enum: + - phone_code + - email_code + - reset_password_email_code + attempts: + type: integer + nullable: true + expire_at: + type: integer + nullable: true + verified_at_client: + type: string + nullable: true + required: + - status + - strategy + - attempts + - expire_at + Admin: + type: object + additionalProperties: false + properties: + status: + type: string + enum: + - verified + strategy: + x-speakeasy-unknown-values: allow + type: string + enum: + - admin + attempts: + type: integer + nullable: true + expire_at: + type: integer + nullable: true + verified_at_client: + type: string + nullable: true + required: + - status + - strategy + - attempts + - expire_at + FromOAuth: + type: object + additionalProperties: false + properties: + status: + type: string + enum: + - unverified + - verified + strategy: + type: string + pattern: ^from_oauth_(?:(?:token_)|(?:custom_))?[a-z]+$ + error: + type: object + nullable: true + oneOf: + - $ref: '#/components/schemas/ClerkError' + expire_at: + type: integer + nullable: true + attempts: + type: integer + nullable: true + verified_at_client: + type: string + nullable: true + required: + - status + - strategy + - attempts + - expire_at + Ticket: + type: object + additionalProperties: false + properties: + status: + type: string + enum: + - unverified + - verified + - expired + strategy: + x-speakeasy-unknown-values: allow + type: string + enum: + - ticket + attempts: + type: integer + nullable: true + expire_at: + type: integer + nullable: true + verified_at_client: + type: string + nullable: true + required: + - status + - strategy + - attempts + - expire_at + IdentificationLink: + type: object + additionalProperties: false + properties: + type: + type: string + pattern: ^oauth_[a-z]+$ + id: + type: string + required: + - type + - id + EmailAddress: + type: object + additionalProperties: false + properties: + id: + type: string + object: + type: string + x-speakeasy-unknown-values: allow + description: | + String representing the object's type. Objects of the same type share the same value. + enum: + - email_address + email_address: + type: string + reserved: + type: boolean + verification: + type: object + nullable: true + oneOf: + - $ref: '#/components/schemas/OTP' + - $ref: '#/components/schemas/Admin' + - $ref: '#/components/schemas/FromOAuth' + - $ref: '#/components/schemas/Ticket' + linked_to: + type: array + items: + $ref: '#/components/schemas/IdentificationLink' + matches_sso_connection: + description: | + Indicates whether this email address domain matches an active enterprise connection. + type: boolean + created_at: + type: integer + format: int64 + description: | + Unix timestamp of creation + updated_at: + type: integer + format: int64 + description: | + Unix timestamp of creation + required: + - object + - email_address + - verification + - linked_to + - reserved + - created_at + - updated_at + PhoneNumber: + type: object + additionalProperties: false + properties: + id: + type: string + object: + type: string + description: | + String representing the object's type. Objects of the same type share the same value. + enum: + - phone_number + phone_number: + type: string + reserved_for_second_factor: + type: boolean + default_second_factor: + type: boolean + reserved: + type: boolean + verification: + type: object + nullable: true + oneOf: + - $ref: '#/components/schemas/OTP' + - $ref: '#/components/schemas/Admin' + linked_to: + type: array + items: + $ref: '#/components/schemas/IdentificationLink' + backup_codes: + type: array + items: + type: string + nullable: true + created_at: + type: integer + format: int64 + description: | + Unix timestamp of creation + updated_at: + type: integer + format: int64 + description: | + Unix timestamp of creation + required: + - object + - phone_number + - verification + - linked_to + - reserved + - created_at + - updated_at + Token: + type: object + additionalProperties: false + properties: + object: + type: string + description: | + String representing the object's type. Objects of the same type share the same value. + enum: + - token + jwt: + type: string + description: | + String representing the encoded jwt value. + required: + - object + - jwt + Cookies: + type: object + additionalProperties: false + properties: + object: + type: string + description: String representing the object's type. Objects of the same type share the same value. + enum: + - cookies + cookies: + type: array + description: Array of cookie directives. + items: + type: string + required: + - object + - cookies + SessionRefresh: + oneOf: + - $ref: '#/components/schemas/Token' + - $ref: '#/components/schemas/Cookies' + Template: + type: object + additionalProperties: false + properties: + id: + type: string + object: + type: string + description: | + String representing the object's type. Objects of the same type share the same value. + enum: + - template + instance_id: + nullable: true + type: string + description: the id of the instance the template belongs to + resource_type: + type: string + description: whether this is a system (default) or user overridden) template + template_type: + type: string + description: whether this is an email or SMS template + name: + type: string + description: user-friendly name of the template + slug: + type: string + description: machine-friendly name of the template + position: + type: integer + description: position with the listing of templates + can_revert: + type: boolean + description: whether this template can be reverted to the corresponding system default + can_delete: + type: boolean + description: whether this template can be deleted + can_edit_body: + type: boolean + description: whether the body of this template can be edited + can_toggle: + type: boolean + description: whether this template can be enabled or disabled, true only for notification SMS templates + subject: + type: string + description: email subject + nullable: true + markup: + type: string + description: the editor markup used to generate the body of the template + body: + type: string + description: the template body before variable interpolation + available_variables: + type: array + description: list of variables that are available for use in the template body + items: + type: string + required_variables: + type: array + description: list of variables that must be contained in the template body + items: + type: string + from_email_name: + type: string + reply_to_email_name: + type: string + delivered_by_clerk: + type: boolean + enabled: + type: boolean + updated_at: + type: integer + format: int64 + description: | + Unix timestamp of last update. + created_at: + type: integer + format: int64 + description: | + Unix timestamp of creation. + Web3Signature: + type: object + additionalProperties: false + properties: + status: + type: string + enum: + - unverified + - verified + - failed + - expired + strategy: + type: string + enum: + - web3_metamask_signature + - web3_coinbase_wallet_signature + - web3_okx_wallet_signature + nonce: + type: string + nullable: true + message: + type: string + nullable: true + attempts: + type: integer + nullable: true + expire_at: + type: integer + nullable: true + verified_at_client: + type: string + nullable: true + required: + - status + - strategy + - attempts + - expire_at + Web3Wallet: + type: object + additionalProperties: false + properties: + id: + type: string + object: + type: string + description: | + String representing the object's type. Objects of the same type share the same value. + enum: + - web3_wallet + web3_wallet: + type: string + verification: + type: object + nullable: true + oneOf: + - $ref: '#/components/schemas/Web3Signature' + - $ref: '#/components/schemas/Admin' + created_at: + type: integer + format: int64 + description: | + Unix timestamp of creation + updated_at: + type: integer + format: int64 + description: | + Unix timestamp of creation + required: + - object + - web3_wallet + - verification + - created_at + - updated_at + Passkey: + type: object + additionalProperties: false + properties: + status: + type: string + enum: + - verified + strategy: + type: string + enum: + - passkey + nonce: + type: string + enum: + - nonce + message: + type: string + nullable: true + attempts: + type: integer + nullable: true + expire_at: + type: integer + nullable: true + verified_at_client: + type: string + nullable: true + required: + - status + - strategy + - attempts + - expire_at + schemas-Passkey: + type: object + additionalProperties: false + properties: + id: + type: string + object: + type: string + description: | + String representing the object's type. Objects of the same type share the same value. + enum: + - passkey + name: + type: string + last_used_at: + type: integer + format: int64 + description: | + Unix timestamp of when the passkey was last used. + verification: + type: object + nullable: true + oneOf: + - $ref: '#/components/schemas/Passkey' + required: + - object + - name + - last_used_at + - verification + Oauth: + type: object + additionalProperties: false + properties: + 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 + GoogleOneTap: + type: object + additionalProperties: false + properties: + 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 + 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/Oauth' + - $ref: '#/components/schemas/GoogleOneTap' + required: + - object + - id + - provider + - identification_id + - provider_user_id + - approved_scopes + - email_address + - first_name + - last_name + - public_metadata + - created_at + - updated_at + - verification + SAML: + type: object + additionalProperties: false + properties: + status: + type: string + enum: + - unverified + - verified + - failed + - expired + - transferable + strategy: + type: string + enum: + - saml + external_verification_redirect_url: + nullable: true + type: string + error: + nullable: true + type: object + oneOf: + - $ref: '#/components/schemas/ClerkError' + expire_at: + type: integer + attempts: + type: integer + nullable: true + verified_at_client: + type: string + nullable: true + required: + - status + - strategy + - external_verification_redirect_url + - attempts + - expire_at + SAMLConnection: + type: object + additionalProperties: false + properties: + id: + type: string + name: + type: string + domain: + type: string + deprecated: true + domains: + type: array + items: + type: string + active: + type: boolean + provider: + type: string + sync_user_attributes: + type: boolean + allow_subdomains: + type: boolean + allow_idp_initiated: + type: boolean + disable_additional_identifications: + type: boolean + created_at: + type: integer + format: int64 + description: | + Unix timestamp of creation. + updated_at: + type: integer + format: int64 + description: | + Unix timestamp of last update. + required: + - id + - name + - active + - provider + - sync_user_attributes + - created_at + - updated_at + anyOf: + - required: + - domain + - required: + - domains + SAMLAccount: + type: object + additionalProperties: false + properties: + id: + type: string + object: + type: string + description: | + String representing the object's type. Objects of the same type share the same value. + enum: + - saml_account + provider: + type: string + active: + type: boolean + email_address: + type: string + first_name: + type: string + nullable: true + last_name: + type: string + nullable: true + provider_user_id: + type: string + nullable: true + public_metadata: + type: object + additionalProperties: true + verification: + type: object + nullable: true + oneOf: + - $ref: '#/components/schemas/SAML' + - $ref: '#/components/schemas/Ticket' + saml_connection: + type: object + nullable: true + oneOf: + - $ref: '#/components/schemas/SAMLConnection' + required: + - id + - object + - provider + - active + - email_address + - verification + User: + type: object + additionalProperties: false + properties: + id: + type: string + object: + type: string + description: | + String representing the object's type. Objects of the same type share the same value. + enum: + - user + external_id: + nullable: true + type: string + primary_email_address_id: + nullable: true + type: string + primary_phone_number_id: + nullable: true + type: string + primary_web3_wallet_id: + nullable: true + type: string + username: + nullable: true + type: string + first_name: + nullable: true + type: string + last_name: + nullable: true + type: string + profile_image_url: + type: string + deprecated: true + image_url: + type: string + has_image: + type: boolean + public_metadata: + type: object + additionalProperties: true + private_metadata: + nullable: true + type: object + additionalProperties: true + unsafe_metadata: + type: object + additionalProperties: true + email_addresses: + type: array + items: + $ref: '#/components/schemas/EmailAddress' + phone_numbers: + type: array + items: + $ref: '#/components/schemas/PhoneNumber' + web3_wallets: + type: array + items: + $ref: '#/components/schemas/Web3Wallet' + passkeys: + type: array + items: + $ref: '#/components/schemas/schemas-Passkey' + password_enabled: + type: boolean + two_factor_enabled: + type: boolean + totp_enabled: + type: boolean + backup_code_enabled: + type: boolean + mfa_enabled_at: + type: integer + format: int64 + description: | + Unix timestamp of when MFA was last enabled for this user. It should be noted that this field is not nullified if MFA is disabled. + nullable: true + mfa_disabled_at: + type: integer + format: int64 + description: | + Unix timestamp of when MFA was last disabled for this user. It should be noted that this field is not nullified if MFA is enabled again. + nullable: true + external_accounts: + type: array + items: + $ref: '#/components/schemas/ExternalAccountWithVerification' + saml_accounts: + type: array + items: + $ref: '#/components/schemas/SAMLAccount' + last_sign_in_at: + type: integer + format: int64 + nullable: true + description: | + Unix timestamp of last sign-in. + banned: + type: boolean + description: | + Flag to denote whether user is banned or not. + locked: + type: boolean + description: | + Flag to denote whether user is currently locked, i.e. restricted from signing in or not. + lockout_expires_in_seconds: + type: integer + format: int64 + nullable: true + description: | + The number of seconds remaining until the lockout period expires for a locked user. A null value for a locked user indicates that lockout never expires. + verification_attempts_remaining: + type: integer + format: int64 + nullable: true + description: | + The number of verification attempts remaining until the user is locked. Null if account lockout is not enabled. Note: if a user is locked explicitly via the Backend API, they may still have verification attempts remaining. + updated_at: + type: integer + format: int64 + description: | + Unix timestamp of last update. + created_at: + type: integer + format: int64 + description: | + Unix timestamp of creation. + delete_self_enabled: + type: boolean + description: | + If enabled, user can delete themselves via FAPI. + create_organization_enabled: + type: boolean + description: | + If enabled, user can create organizations via FAPI. + create_organizations_limit: + type: integer + description: | + The maximum number of organizations the user can create. 0 means unlimited. + nullable: true + last_active_at: + type: integer + format: int64 + nullable: true + description: | + Unix timestamp of the latest session activity, with day precision. + example: 1700690400000 + legal_accepted_at: + type: integer + format: int64 + nullable: true + description: | + Unix timestamp of when the user accepted the legal requirements. + example: 1700690400000 + PasswordHasher: + type: string + description: |- + The hashing algorithm that was used to generate the password digest. + + The algorithms we support at the moment are [`bcrypt`](https://en.wikipedia.org/wiki/Bcrypt), [`bcrypt_sha256_django`](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/), [`md5`](https://en.wikipedia.org/wiki/MD5), `pbkdf2_sha1`, `pbkdf2_sha256`, [`pbkdf2_sha256_django`](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/), + [`phpass`](https://www.openwall.com/phpass/), `md5_phpass`, [`scrypt_firebase`](https://firebaseopensource.com/projects/firebase/scrypt/), + [`scrypt_werkzeug`](https://werkzeug.palletsprojects.com/en/3.0.x/utils/#werkzeug.security.generate_password_hash), [`sha256`](https://en.wikipedia.org/wiki/SHA-2), + [`ldap_ssha`](https://www.openldap.org/faq/data/cache/347.html) and the [`argon2`](https://argon2.online/) variants: `argon2i` and `argon2id`. + + Each of the supported hashers expects the incoming digest to be in a particular format. See the [Clerk docs](https://clerk.com/docs/references/backend/user/create-user) for more information. + TotalCount: + type: object + additionalProperties: false + properties: + object: + type: string + description: | + String representing the object's type. Objects of the same type share the same value. + enum: + - total_count + total_count: + type: integer + format: int64 + required: + - object + - total_count + OAuthAccessToken: + type: array + items: + type: object + additionalProperties: false + properties: + object: + type: string + enum: + - oauth_access_token + external_account_id: + type: string + description: External account ID + provider_user_id: + type: string + description: The unique ID of the user in the external provider's system + token: + type: string + description: The access token + expires_at: + type: integer + format: int64 + nullable: true + description: Unix timestamp of the access token expiration. + provider: + type: string + description: The ID of the provider + public_metadata: + type: object + additionalProperties: true + label: + type: string + nullable: true + scopes: + type: array + items: + type: string + description: The list of scopes that the token is valid for. Only present for OAuth 2.0 tokens. + token_secret: + type: string + description: The token secret. Only present for OAuth 1.0 tokens. + required: + - object + - external_account_id + - provider_user_id + - token + - expires_at + - provider + - public_metadata + - label + Organization: + type: object + properties: + object: + type: string + enum: + - organization + id: + type: string + name: + type: string + slug: + type: string + image_url: + type: string + has_image: + type: boolean + members_count: + type: integer + missing_member_with_elevated_permissions: + type: boolean + pending_invitations_count: + type: integer + max_allowed_memberships: + type: integer + admin_delete_enabled: + type: boolean + public_metadata: + type: object + additionalProperties: true + private_metadata: + type: object + additionalProperties: true + created_by: + type: string + created_at: + type: integer + format: int64 + description: | + Unix timestamp of creation. + updated_at: + type: integer + format: int64 + description: | + Unix timestamp of last update. + required: + - object + - id + - name + - slug + - has_image + - max_allowed_memberships + - admin_delete_enabled + - public_metadata + - created_at + - updated_at + OrganizationMembershipPublicUserData: + description: An organization membership with public user data populated + type: object + additionalProperties: false + properties: + user_id: + type: string + nullable: false + first_name: + type: string + nullable: true + last_name: + type: string + nullable: true + profile_image_url: + type: string + nullable: true + deprecated: true + image_url: + type: string + has_image: + type: boolean + identifier: + type: string + nullable: true + required: + - user_id + - first_name + - last_name + - profile_image_url + - image_url + - has_image + OrganizationMembership: + description: Hello world + type: object + properties: + id: + type: string + object: + type: string + description: | + String representing the object's type. Objects of the same type share the same value. + enum: + - organization_membership + role: + type: string + role_name: + type: string + permissions: + type: array + items: + type: string + public_metadata: + type: object + description: Metadata saved on the organization membership, accessible from both Frontend and Backend APIs + additionalProperties: true + private_metadata: + type: object + description: Metadata saved on the organization membership, accessible only from the Backend API + additionalProperties: true + organization: + type: object + nullable: false + allOf: + - $ref: '#/components/schemas/Organization' + public_user_data: + $ref: '#/components/schemas/OrganizationMembershipPublicUserData' + created_at: + type: integer + format: int64 + description: Unix timestamp of creation. + updated_at: + type: integer + format: int64 + description: Unix timestamp of last update. + required: + - object + - id + - role + - permissions + - public_metadata + - created_at + - updated_at + - organization + OrganizationMemberships: + type: object + additionalProperties: false + properties: + data: + type: array + items: + $ref: '#/components/schemas/OrganizationMembership' + total_count: + type: integer + format: int64 + description: | + Total number of organization memberships + required: + - data + - total_count + OrganizationInvitationPublicOrganizationData: + type: object + additionalProperties: false + properties: + id: + type: string + name: + type: string + slug: + type: string + image_url: + type: string + has_image: + type: boolean + required: + - id + - name + - slug + - has_image + OrganizationInvitationWithPublicOrganizationData: + description: An organization invitation with public organization data populated + type: object + allOf: + - properties: + object: + type: string + description: | + String representing the object's type. Objects of the same type share the same value. + enum: + - organization_invitation + id: + type: string + email_address: + type: string + role: + type: string + role_name: + type: string + organization_id: + type: string + status: + type: string + public_metadata: + type: object + additionalProperties: true + private_metadata: + type: object + additionalProperties: true + url: + type: string + nullable: true + expires_at: + type: integer + format: int64 + nullable: true + description: Unix timestamp of expiration. + created_at: + type: integer + format: int64 + description: Unix timestamp of creation. + updated_at: + type: integer + format: int64 + description: Unix timestamp of last update. + - properties: + public_organization_data: + $ref: '#/components/schemas/OrganizationInvitationPublicOrganizationData' + required: + - object + - id + - email_address + - role + - role_name + - public_metadata + - url + - expires_at + - created_at + - updated_at + OrganizationInvitationsWithPublicOrganizationData: + type: object + additionalProperties: false + properties: + data: + type: array + items: + $ref: '#/components/schemas/OrganizationInvitationWithPublicOrganizationData' + total_count: + type: integer + format: int64 + description: | + Total number of organization invitations + required: + - data + - total_count + Invitation: + type: object + additionalProperties: false + properties: + object: + type: string + enum: + - invitation + id: + type: string + email_address: + type: string + format: email + public_metadata: + type: object + additionalProperties: true + revoked: + type: boolean + example: false + status: + type: string + enum: + - pending + - accepted + - revoked + - expired + example: pending + url: + type: string + expires_at: + type: integer + format: int64 + nullable: true + description: | + Unix timestamp of expiration. + created_at: + type: integer + format: int64 + description: | + Unix timestamp of creation. + updated_at: + type: integer + format: int64 + description: | + Unix timestamp of last update. + required: + - object + - id + - email_address + - public_metadata + - status + - created_at + - updated_at + AllowlistIdentifier: + type: object + additionalProperties: false + properties: + object: + type: string + description: | + String representing the object's type. Objects of the same type share the same value. + enum: + - allowlist_identifier + id: + type: string + invitation_id: + type: string + identifier: + type: string + description: | + An email address or a phone number. + identifier_type: + type: string + enum: + - email_address + - phone_number + - web3_wallet + instance_id: + type: string + created_at: + type: integer + format: int64 + description: | + Unix timestamp of creation + updated_at: + type: integer + format: int64 + description: | + Unix timestamp of last update. + BlocklistIdentifier: + type: object + additionalProperties: false + properties: + object: + type: string + description: | + String representing the object's type. Objects of the same type share the same value. + enum: + - blocklist_identifier + id: + type: string + identifier: + type: string + description: | + An email address, email domain, phone number or web3 wallet. + identifier_type: + type: string + enum: + - email_address + - phone_number + - web3_wallet + instance_id: + type: string + created_at: + type: integer + format: int64 + description: | + Unix timestamp of creation + updated_at: + type: integer + format: int64 + description: | + Unix timestamp of last update. + BlocklistIdentifiers: + type: object + additionalProperties: false + properties: + data: + type: array + items: + $ref: '#/components/schemas/BlocklistIdentifier' + total_count: + type: integer + format: int64 + description: | + Total number of blocklist identifiers + required: + - data + - total_count + ActorToken: + type: object + additionalProperties: false + properties: + object: + type: string + enum: + - actor_token + id: + type: string + status: + type: string + enum: + - pending + - accepted + - revoked + user_id: + type: string + actor: + type: object + token: + type: string + url: + type: string + created_at: + type: integer + format: int64 + description: | + Unix timestamp of creation. + updated_at: + type: integer + format: int64 + description: | + Unix timestamp of last update. + required: + - object + - id + - user_id + - actor + - status + - created_at + - updated_at + CNameTarget: + type: object + additionalProperties: false + properties: + host: + type: string + value: + type: string + required: + description: | + Denotes whether this CNAME target is required to be set in order for the domain to be considered deployed. + type: boolean + required: + - host + - value + - required + Domain: + type: object + properties: + object: + type: string + enum: + - domain + id: + type: string + name: + type: string + is_satellite: + type: boolean + frontend_api_url: + type: string + accounts_portal_url: + type: string + nullable: true + description: | + Null for satellite domains. + proxy_url: + type: string + nullable: true + development_origin: + type: string + cname_targets: + type: array + items: + $ref: '#/components/schemas/CNameTarget' + nullable: true + required: + - object + - id + - name + - is_satellite + - frontend_api_url + - development_origin + Domains: + type: object + additionalProperties: false + properties: + data: + type: array + items: + $ref: '#/components/schemas/Domain' + total_count: + type: integer + format: int64 + description: | + Total number of domains + required: + - data + - total_count + Instance: + type: object + properties: + object: + type: string + description: String representing the object's type. Objects of the same type share the same value. + enum: + - instance + id: + type: string + environment_type: + type: string + example: development + allowed_origins: + type: array + nullable: true + items: + type: string + example: + - http://localhost:3000 + - https://some-domain + required: + - object + - id + - environment_type + - allowed_origins + InstanceRestrictions: + type: object + properties: + object: + type: string + description: String representing the object's type. Objects of the same type share the same value. + enum: + - instance_restrictions + allowlist: + type: boolean + blocklist: + type: boolean + block_email_subaddresses: + type: boolean + block_disposable_email_domains: + type: boolean + required: + - object + - allowlist + - blocklist + - block_email_subaddresses + - block_disposable_email_domains + OrganizationSettings: + type: object + additionalProperties: false + properties: + object: + type: string + description: String representing the object's type. Objects of the same type share the same value. + enum: + - organization_settings + enabled: + type: boolean + max_allowed_memberships: + type: integer + max_allowed_roles: + type: integer + max_allowed_permissions: + type: integer + creator_role: + type: string + description: The role key that a user will be assigned after creating an organization. + admin_delete_enabled: + type: boolean + description: The default for whether an admin can delete an organization with the Frontend API. + domains_enabled: + type: boolean + domains_enrollment_modes: + type: array + items: + type: string + enum: + - manual_invitation + - automatic_invitation + - automatic_suggestion + domains_default_role: + type: string + description: The role key that it will be used in order to create an organization invitation or suggestion. + required: + - object + - enabled + - max_allowed_memberships + - max_allowed_roles + - max_allowed_permissions + - creator_role + - admin_delete_enabled + - domains_enabled + - domains_enrollment_modes + - domains_default_role + SvixURL: + type: object + additionalProperties: false + properties: + svix_url: + type: string + required: + - svix_url + JWTTemplate: + type: object + additionalProperties: false + properties: + object: + type: string + enum: + - jwt_template + id: + type: string + name: + type: string + claims: + type: object + lifetime: + type: integer + allowed_clock_skew: + type: integer + custom_signing_key: + type: boolean + signing_algorithm: + type: string + created_at: + type: integer + format: int64 + description: | + Unix timestamp of creation. + updated_at: + type: integer + format: int64 + description: | + Unix timestamp of last update. + required: + - object + - id + - name + - claims + - lifetime + - allowed_clock_skew + - custom_signing_key + - signing_algorithm + - created_at + - updated_at + MachineToken: + type: object + additionalProperties: false + properties: + object: + type: string + enum: + - token + jwt: + type: string + required: + - object + - jwt + MachineWithoutScopedMachines: + type: object + required: + - object + - id + - name + - instance_id + - created_at + - updated_at + properties: + object: + type: string + enum: + - machine + id: + type: string + description: Unique identifier for the machine. + name: + type: string + description: The name of the machine. + maxLength: 255 + minLength: 1 + instance_id: + type: string + description: The ID of the instance this machine belongs to. + created_at: + type: integer + format: int64 + description: Unix timestamp of creation. + updated_at: + type: integer + format: int64 + description: Unix timestamp of last update. + Machine: + allOf: + - $ref: '#/components/schemas/MachineWithoutScopedMachines' + - type: object + required: + - scoped_machines + properties: + scoped_machines: + type: array + items: + $ref: '#/components/schemas/MachineWithoutScopedMachines' + description: Array of machines this machine has access to. + MachineScope: + type: object + required: + - object + - from_machine_id + - to_machine_id + - created_at + properties: + object: + type: string + enum: + - machine_scope + from_machine_id: + type: string + description: The ID of the machine that has access to the target machine. + to_machine_id: + type: string + description: The ID of the machine that is being accessed. + created_at: + type: integer + format: int64 + description: Unix timestamp of creation. + Organizations: + type: object + additionalProperties: false + properties: + data: + type: array + items: + $ref: '#/components/schemas/Organization' + total_count: + type: integer + format: int64 + description: | + Total number of organizations + required: + - data + - total_count + OrganizationWithLogo: + type: object + allOf: + - $ref: '#/components/schemas/Organization' + - type: object + properties: + logo_url: + type: string + deprecated: true + image_url: + type: string + has_image: + type: boolean + required: + - image_url + - has_image + OrganizationInvitation: + description: An organization invitation + type: object + properties: + object: + type: string + description: | + String representing the object's type. Objects of the same type share the same value. + enum: + - organization_invitation + id: + type: string + email_address: + type: string + role: + type: string + role_name: + type: string + organization_id: + type: string + status: + type: string + public_metadata: + type: object + additionalProperties: true + private_metadata: + type: object + additionalProperties: true + url: + type: string + nullable: true + expires_at: + type: integer + format: int64 + nullable: true + description: Unix timestamp of expiration. + created_at: + type: integer + format: int64 + description: Unix timestamp of creation. + updated_at: + type: integer + format: int64 + description: Unix timestamp of last update. + required: + - object + - id + - email_address + - role + - role_name + - public_metadata + - url + - expires_at + - created_at + - updated_at + OrganizationInvitations: + type: object + additionalProperties: false + properties: + data: + type: array + items: + $ref: '#/components/schemas/OrganizationInvitation' + total_count: + type: integer + format: int64 + description: | + Total number of organization invitations + required: + - data + - total_count + OrganizationDomainVerification: + description: The verification object from an organization domain + type: object + properties: + status: + type: string + description: Status of the verification. It can be `unverified` or `verified` + enum: + - unverified + - verified + strategy: + type: string + description: Name of the strategy used to verify the domain + attempts: + type: integer + description: How many attempts have been made to verify the domain + nullable: true + expire_at: + type: integer + nullable: true + format: int64 + description: Unix timestamp of when the verification will expire + required: + - status + - strategy + - attempts + - expire_at + OrganizationDomain: + description: An organization domain + type: object + properties: + object: + type: string + description: | + String representing the object's type. Objects of the same type share the same value. Always `organization_domain` + enum: + - organization_domain + id: + type: string + description: Unique identifier for the organization domain + organization_id: + type: string + description: Unique identifier for the organization + name: + type: string + description: Name of the organization domain + enrollment_mode: + type: string + description: Mode of enrollment for the domain + enum: + - manual_invitation + - automatic_invitation + - automatic_suggestion + affiliation_email_address: + type: string + nullable: true + description: Affiliation email address for the domain, if available. + verification: + type: object + nullable: true + allOf: + - $ref: '#/components/schemas/OrganizationDomainVerification' + description: Verification details for the domain + total_pending_invitations: + type: integer + format: int32 + description: Total number of pending invitations associated with this domain + total_pending_suggestions: + type: integer + format: int32 + description: Total number of pending suggestions associated with this domain + created_at: + type: integer + format: int64 + description: Unix timestamp when the domain was created + updated_at: + type: integer + format: int64 + description: Unix timestamp of the last update to the domain + required: + - object + - id + - organization_id + - name + - enrollment_mode + - affiliation_email_address + - verification + - total_pending_invitations + - total_pending_suggestions + - created_at + - updated_at + OrganizationDomains: + type: object + additionalProperties: false + properties: + data: + type: array + items: + $ref: '#/components/schemas/OrganizationDomain' + total_count: + type: integer + format: int64 + description: | + Total number of organization domains + required: + - data + - total_count + ProxyCheck: + type: object + additionalProperties: false + properties: + object: + type: string + enum: + - proxy_check + id: + type: string + domain_id: + type: string + last_run_at: + type: integer + format: int64 + nullable: true + description: | + Unix timestamp of last run. + proxy_url: + type: string + successful: + type: boolean + created_at: + type: integer + format: int64 + description: | + Unix timestamp of creation. + updated_at: + type: integer + format: int64 + description: | + Unix timestamp of last update. + required: + - object + - id + - domain_id + - last_run_at + - proxy_url + - successful + - created_at + - updated_at + RedirectURL: + type: object + additionalProperties: false + properties: + object: + type: string + enum: + - redirect_url + id: + type: string + url: + type: string + created_at: + type: integer + format: int64 + description: | + Unix timestamp of creation. + updated_at: + type: integer + format: int64 + description: | + Unix timestamp of last update. + required: + - object + - id + - url + - created_at + - updated_at + SignInToken: + type: object + additionalProperties: false + properties: + object: + type: string + enum: + - sign_in_token + id: + type: string + status: + type: string + enum: + - pending + - accepted + - revoked + user_id: + type: string + token: + type: string + url: + type: string + nullable: true + created_at: + type: integer + format: int64 + description: | + Unix timestamp of creation. + updated_at: + type: integer + format: int64 + description: | + Unix timestamp of last update. + required: + - object + - id + - user_id + - status + - created_at + - updated_at + SignUpVerification: + type: object + nullable: true + additionalProperties: true + properties: + next_action: + type: string + enum: + - needs_prepare + - needs_attempt + - '' + supported_strategies: + type: array + items: + type: string + SignUpVerifications: + type: object + additionalProperties: false + properties: + email_address: + $ref: '#/components/schemas/SignUpVerification' + phone_number: + $ref: '#/components/schemas/SignUpVerification' + web3_wallet: + $ref: '#/components/schemas/SignUpVerification' + external_account: + type: object + nullable: true + required: + - email_address + - phone_number + - web3_wallet + - external_account + SignUp: + type: object + additionalProperties: false + properties: + object: + type: string + enum: + - sign_up_attempt + id: + type: string + status: + type: string + enum: + - missing_requirements + - complete + - abandoned + required_fields: + type: array + items: + type: string + optional_fields: + type: array + items: + type: string + missing_fields: + type: array + items: + type: string + unverified_fields: + type: array + items: + type: string + verifications: + $ref: '#/components/schemas/SignUpVerifications' + username: + type: string + nullable: true + email_address: + type: string + nullable: true + phone_number: + type: string + nullable: true + web3_wallet: + type: string + nullable: true + password_enabled: + type: boolean + first_name: + type: string + nullable: true + last_name: + type: string + nullable: true + unsafe_metadata: + type: object + additionalProperties: true + public_metadata: + type: object + additionalProperties: true + custom_action: + type: boolean + external_id: + type: string + nullable: true + created_session_id: + type: string + nullable: true + created_user_id: + type: string + nullable: true + abandon_at: + type: integer + format: int64 + description: | + Unix timestamp at which the user abandoned the sign up attempt. + example: 1700690400000 + legal_accepted_at: + type: integer + format: int64 + nullable: true + description: | + Unix timestamp at which the user accepted the legal requirements. + example: 1700690400000 + external_account: + type: object + deprecated: true + required: + - object + - id + - status + - required_fields + - optional_fields + - missing_fields + - unverified_fields + - verifications + - username + - email_address + - phone_number + - web3_wallet + - password_enabled + - first_name + - last_name + - custom_action + - external_id + - created_session_id + - created_user_id + - abandon_at + - legal_accepted_at + OAuthApplication: + type: object + properties: + object: + type: string + enum: + - oauth_application + id: + type: string + instance_id: + type: string + name: + type: string + client_id: + type: string + client_uri: + type: string + nullable: true + client_image_url: + type: string + nullable: true + dynamically_registered: + type: boolean + consent_screen_enabled: + type: boolean + pkce_required: + type: boolean + public: + type: boolean + scopes: + type: string + redirect_uris: + type: array + items: + type: string + callback_url: + type: string + deprecated: true + description: | + Deprecated: Use redirect_uris instead. + authorize_url: + type: string + token_fetch_url: + type: string + user_info_url: + type: string + discovery_url: + type: string + token_introspection_url: + type: string + created_at: + type: integer + format: int64 + description: | + Unix timestamp of creation. + updated_at: + type: integer + format: int64 + description: | + Unix timestamp of last update. + required: + - object + - id + - instance_id + - name + - dynamically_registered + - consent_screen_enabled + - pkce_required + - public + - client_id + - client_uri + - client_image_url + - scopes + - redirect_uris + - callback_url + - authorize_url + - token_fetch_url + - user_info_url + - discovery_url + - token_introspection_url + - created_at + - updated_at + OAuthApplications: + type: object + additionalProperties: false + properties: + data: + type: array + items: + $ref: '#/components/schemas/OAuthApplication' + total_count: + type: integer + format: int64 + description: | + Total number of OAuth applications + required: + - data + - total_count + OAuthApplicationWithSecret: + allOf: + - $ref: '#/components/schemas/OAuthApplication' + - type: object + properties: + client_secret: + type: string + description: | + Empty if public client. + SAMLConnectionAttributeMapping: + type: object + additionalProperties: false + properties: + user_id: + type: string + email_address: + type: string + first_name: + type: string + last_name: + type: string + required: + - user_id + - email_address + - first_name + - last_name + schemas-SAMLConnection: + type: object + properties: + object: + type: string + enum: + - saml_connection + id: + type: string + name: + type: string + domain: + type: string + deprecated: true + domains: + type: array + items: + type: string + idp_entity_id: + type: string + nullable: true + idp_sso_url: + type: string + nullable: true + idp_certificate: + type: string + nullable: true + idp_metadata_url: + type: string + nullable: true + idp_metadata: + type: string + nullable: true + acs_url: + type: string + sp_entity_id: + type: string + sp_metadata_url: + type: string + organization_id: + type: string + nullable: true + attribute_mapping: + $ref: '#/components/schemas/SAMLConnectionAttributeMapping' + active: + type: boolean + provider: + type: string + user_count: + type: integer + sync_user_attributes: + type: boolean + allow_subdomains: + type: boolean + allow_idp_initiated: + type: boolean + disable_additional_identifications: + type: boolean + created_at: + type: integer + format: int64 + description: | + Unix timestamp of creation. + updated_at: + type: integer + format: int64 + description: | + Unix timestamp of last update. + required: + - object + - id + - name + - idp_entity_id + - idp_sso_url + - idp_certificate + - acs_url + - sp_entity_id + - sp_metadata_url + - active + - provider + - user_count + - sync_user_attributes + - created_at + - updated_at + anyOf: + - required: + - domain + - required: + - domains + SAMLConnections: + type: object + additionalProperties: false + properties: + data: + type: array + items: + $ref: '#/components/schemas/schemas-SAMLConnection' + total_count: + type: integer + format: int64 + description: | + Total number of SAML Connections + required: + - data + - total_count + TestingToken: + type: object + properties: + object: + type: string + enum: + - testing_token + token: + type: string + description: The actual token. This value is meant to be passed in the `__clerk_testing_token` query parameter with requests to the Frontend API. + example: 1713877200-c_2J2MvPu9PnXcuhbPZNao0LOXqK9A7YrnBn0HmIWxy + expires_at: + type: integer + format: int64 + description: | + Unix timestamp of the token's expiration time. + example: 1713880800 + required: + - object + - token + - expires_at + WaitlistEntry: + type: object + additionalProperties: false + properties: + object: + type: string + enum: + - waitlist_entry + id: + type: string + email_address: + type: string + format: email + status: + type: string + enum: + - pending + - invited + - rejected + - completed + example: pending + is_locked: + type: boolean + description: | + Indicates if the waitlist entry is locked. Locked entries are being processed in a batch action and are unavailable for other actions. + created_at: + type: integer + format: int64 + description: | + Unix timestamp of creation. + updated_at: + type: integer + format: int64 + description: | + Unix timestamp of last update. + invitation: + type: object + nullable: true + allOf: + - $ref: '#/components/schemas/Invitation' + required: + - object + - id + - email_address + - status + - created_at + - updated_at + AccountlessApplication: + type: object + additionalProperties: false + properties: + object: + type: string + enum: + - accountless_application + publishable_key: + type: string + secret_key: + type: string + claim_url: + type: string + api_keys_url: + type: string + required: + - object + - publishable_key + ManagementUpsertUserRequest: + type: object + additionalProperties: false + properties: + email_address: + type: string + description: The email address of the user. + first_name: + type: string + description: The first name of the user. + last_name: + type: string + description: The last name of the user. + required: + - email_address + - first_name + - last_name + ManagementCreateOrganizationRequest: + type: object + additionalProperties: false + properties: + name: + type: string + description: The name of the organization. + slug: + type: string + description: The slug of the organization. + created_by: + type: string + description: The ID of the user who created the organization. + max_allowed_memberships: + type: integer + description: The maximum allowed memberships for the organization. + public_metadata: + type: object + description: Public metadata for the organization. + private_metadata: + type: object + description: Private metadata for the organization. + created_at: + type: string + format: date-time + description: The creation timestamp in RFC3339 format. + required: + - name + - slug + ManagementCreateApplicationRequest: + type: object + additionalProperties: false + properties: + name: + type: string + description: The name of the application. + owner_id: + type: string + description: The owner ID (organization ID) of the application. + plan_id: + type: string + description: The plan ID for the application (e.g., "free_2022_06", "pro_2023_11"). + addon_ids: + type: array + items: + type: string + description: List of add-on IDs (e.g., ["enhanced_auth_2023_11", "enhanced_orgs_2023_11"]). + paid_externally: + type: boolean + description: Whether the application is paid externally. + test_mode: + type: boolean + description: Whether the application is in test mode. + max_allowed_users: + type: integer + description: Maximum allowed users for the application. + max_allowed_organizations: + type: integer + description: Maximum allowed organizations for the application. + subscription_metadata: + type: object + additionalProperties: + type: string + description: Subscription metadata for the application. + environment_types: + type: array + items: + type: string + enum: + - development + - staging + - production + description: List of environment types to create instances for. + required: + - name + - owner_id + - plan_id + ManagementApplicationSubscription: + type: object + additionalProperties: false + properties: + id: + type: string + stripe_subscription_id: + type: string + nullable: true + required: + - id + ManagementApplicationInstance: + type: object + additionalProperties: false + properties: + instance_id: + type: string + description: The ID of the instance. + environment_type: + type: string + description: The environment type of the instance. + secret_key: + type: string + description: The secret key of the instance. + publishable_key: + type: string + description: The publishable key of the instance. + required: + - instance_id + - environment_type + - secret_key + - publishable_key + ManagementApplicationResponse: + type: object + additionalProperties: false + properties: + application_id: + type: string + description: The ID of the application. + subscription: + $ref: '#/components/schemas/ManagementApplicationSubscription' + instances: + type: array + description: List of instances associated with this application. + items: + $ref: '#/components/schemas/ManagementApplicationInstance' + required: + - application_id + - instances + responses: + WellKnown.JWKS: + description: Get the JSON Web Key Set + content: + application/json: + schema: + $ref: '#/components/schemas/JWKS' + AWSCredential.List: + description: Success + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/AWSCredential' + AWSCredential: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/AWSCredential' + ClerkErrors: + description: Request was not successful + content: + application/json: + schema: + $ref: '#/components/schemas/ClerkErrors' + AuthenticationInvalid: + description: Authentication invalid + content: + application/json: + schema: + $ref: '#/components/schemas/ClerkErrors' + AuthorizationInvalid: + description: Authorization invalid + content: + application/json: + schema: + $ref: '#/components/schemas/ClerkErrors' + ResourceNotFound: + description: Resource not found + content: + application/json: + schema: + $ref: '#/components/schemas/ClerkErrors' + UnprocessableEntity: + description: Invalid request parameters + content: + application/json: + schema: + $ref: '#/components/schemas/ClerkErrors' + DeletedObject: + description: Deleted Object + content: + application/json: + schema: + $ref: '#/components/schemas/DeletedObject' + Client.List: + description: Success + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Client' + DeprecatedEndpoint: + description: The endpoint is considered deprecated and is pending removal. + content: + application/json: + schema: + $ref: '#/components/schemas/ClerkErrors' + Client: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/Client' + EmailAddress: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/EmailAddress' + PhoneNumber: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/PhoneNumber' + Session.List: + description: Success + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Session' + Session: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/Session' + Session.Refresh: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/SessionRefresh' + Template.List: + description: Success + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Template' + Template: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/Template' + PaymentRequired: + description: Payment required + content: + application/json: + schema: + $ref: '#/components/schemas/ClerkErrors' + User.List: + description: Success + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/User' + User: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/User' + User.Count: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/TotalCount' + OAuthAccessToken: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/OAuthAccessToken' + OrganizationMemberships: + description: A list of organization memberships + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationMemberships' + OrganizationInvitationsWithPublicOrganizationData: + description: A list of organization invitations with public organization data + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationInvitationsWithPublicOrganizationData' + Invitation.List: + description: List of invitations + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Invitation' + Invitation: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/Invitation' + Invitation.Revoked: + description: Success + content: + application/json: + schema: + allOf: + - $ref: '#/components/schemas/Invitation' + - type: object + properties: + revoked: + type: boolean + enum: + - true + example: true + status: + type: string + enum: + - revoked + example: revoked + AllowlistIdentifier.List: + description: Success + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/AllowlistIdentifier' + AllowlistIdentifier: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/AllowlistIdentifier' + BlocklistIdentifier.List: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/BlocklistIdentifiers' + BlocklistIdentifier: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/BlocklistIdentifier' + InstanceSettings: + description: InstanceSettings Server API + content: + application/json: + schema: + type: object + properties: + object: + type: string + description: String representing the object's type. Objects of the same type share the same value. + enum: + - instance_settings + id: + type: string + restricted_to_allowlist: + type: boolean + from_email_address: + type: string + progressive_sign_up: + type: boolean + enhanced_email_deliverability: + type: boolean + ActorToken: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/ActorToken' + Domains: + description: A list of domains + content: + application/json: + schema: + $ref: '#/components/schemas/Domains' + Domain: + description: A domain + content: + application/json: + schema: + $ref: '#/components/schemas/Domain' + Instance: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/Instance' + InstanceRestrictions: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/InstanceRestrictions' + OrganizationSettings: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationSettings' + SvixURL: + description: Response that contains a temporary Svix URL to access management dashboard + content: + application/json: + schema: + $ref: '#/components/schemas/SvixURL' + JWTTemplate.List: + description: List of JWT templates + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/JWTTemplate' + JWTTemplate: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/JWTTemplate' + MachineToken: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/MachineToken' + Machine.List: + description: Success + content: + application/json: + schema: + type: object + required: + - data + - total_count + properties: + data: + type: array + items: + $ref: '#/components/schemas/Machine' + total_count: + type: integer + description: Total number of machines + Machine: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/Machine' + Machine.Deleted: + description: Success + content: + application/json: + schema: + type: object + required: + - object + - id + - deleted + properties: + object: + type: string + enum: + - machine + description: String representing the object's type. + id: + type: string + description: The ID of the deleted machine + deleted: + type: boolean + enum: + - true + description: Whether the machine was successfully deleted + MachineScope: + description: Machine scope created successfully for a machine + content: + application/json: + schema: + $ref: '#/components/schemas/MachineScope' + Conflict: + description: Conflict + content: + application/json: + schema: + $ref: '#/components/schemas/ClerkErrors' + MachineScope.Deleted: + description: Machine scope deleted successfully for a machine + content: + application/json: + schema: + type: object + required: + - object + - from_machine_id + - to_machine_id + - deleted + properties: + object: + type: string + enum: + - machine_scope + description: String representing the object's type. + from_machine_id: + type: string + description: The ID of the machine that had access to the target machine + to_machine_id: + type: string + description: The ID of the machine that was being accessed + deleted: + type: boolean + enum: + - true + description: Whether the machine scope was successfully deleted + Organizations: + description: A list of organizations + content: + application/json: + schema: + $ref: '#/components/schemas/Organizations' + Organization: + description: An organization + content: + application/json: + schema: + $ref: '#/components/schemas/Organization' + OrganizationWithLogo: + description: An organization with a logo URL. + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationWithLogo' + OrganizationInvitations: + description: A list of organization invitations + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationInvitations' + OrganizationInvitation: + description: An organization invitation + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationInvitation' + OrganizationMembership: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationMembership' + OrganizationDomains: + description: A list of organization domains + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationDomains' + OrganizationDomain: + description: An organization domain + content: + application/json: + schema: + $ref: '#/components/schemas/OrganizationDomain' + ProxyCheck: + description: Health check information about a domain's proxy configuration validation attempt. + content: + application/json: + schema: + $ref: '#/components/schemas/ProxyCheck' + RedirectURL.List: + description: List of Redirect URLs + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/RedirectURL' + RedirectURL: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/RedirectURL' + SignInToken: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/SignInToken' + SignUp: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/SignUp' + OAuthApplications: + description: A list of OAuth applications + content: + application/json: + schema: + $ref: '#/components/schemas/OAuthApplications' + OAuthApplicationWithSecret: + description: An OAuth application with client secret + content: + application/json: + schema: + $ref: '#/components/schemas/OAuthApplicationWithSecret' + OAuthApplication: + description: An OAuth application + content: + application/json: + schema: + $ref: '#/components/schemas/OAuthApplication' + SAMLConnections: + description: A list of SAML Connections + content: + application/json: + schema: + $ref: '#/components/schemas/SAMLConnections' + SAMLConnection: + description: A SAML Connection + content: + application/json: + schema: + $ref: '#/components/schemas/schemas-SAMLConnection' + TestingToken: + description: A Testing Token + content: + application/json: + schema: + $ref: '#/components/schemas/TestingToken' + WaitlistEntries: + description: List of waitlist entries + content: + application/json: + schema: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/WaitlistEntry' + total_count: + type: integer + description: Total number of waitlist entries + required: + - data + - total_count + WaitlistEntry: + description: A Waitlist Entry + content: + application/json: + schema: + $ref: '#/components/schemas/WaitlistEntry' + AccountlessApplication: + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/AccountlessApplication' + parameters: + Paginated: + name: paginated + in: query + description: |- + Whether to paginate the results. + If true, the results will be paginated. + If false, the results will not be paginated. + required: false + schema: + type: boolean + LimitParameter: + name: limit + in: query + description: |- + Applies a limit to the number of results returned. + Can be used for paginating the results together with `offset`. + required: false + schema: + type: integer + default: 10 + minimum: 1 + maximum: 500 + OffsetParameter: + name: offset + in: query + description: |- + Skip the first `offset` results when paginating. + Needs to be an integer greater or equal to zero. + To be used in conjunction with `limit`. + required: false + schema: + type: integer + default: 0 + minimum: 0 +x-speakeasy-retries: + strategy: backoff + backoff: + initialInterval: 500 + maxInterval: 60000 + maxElapsedTime: 3600000 + exponent: 1.5 + statusCodes: + - 5XX + retryConnectionErrors: true diff --git a/fapi/2021-02-05.yml b/fapi/2021-02-05.yml index a6c82eb..2b7212d 100644 --- a/fapi/2021-02-05.yml +++ b/fapi/2021-02-05.yml @@ -146,6 +146,17 @@ paths: 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 @@ -271,6 +282,81 @@ paths: 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. + operationId: revokeOAuthToken + security: [] + tags: + - OAuth2 Identify 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/ClerkErrors' + '401': + $ref: '#/components/responses/ClerkErrors' + '403': + $ref: '#/components/responses/ClerkErrors' + '404': + $ref: '#/components/responses/ClerkErrors' + '422': + $ref: '#/components/responses/ClerkErrors' + /v1/me/oauth/consent/{client_id}: + get: + summary: Get consent information + description: Get required consent information for a given OAuth Application Client ID + operationId: getOAuthConsent + security: + - {} + - DevBrowser: [] + tags: + - OAuth2 Identify 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: _clerk_session_id + schema: + type: string + description: The session_id associated with the requesting user. + 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' /v1/account_portal: get: summary: Get account portal @@ -1405,6 +1491,17 @@ paths: 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: @@ -1719,7 +1816,11 @@ paths: /v1/client/sessions/{session_id}/tokens: post: summary: Create Session Token - description: Create a session jwt for the authenticated requested user. + 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 workspace. operationId: createSessionToken tags: - Sessions @@ -1738,7 +1839,13 @@ paths: 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 workspace will be set as active. If absent, the previous active organization for the session will be used. + description: |- + The organization id to associate with the token. The user must be a member of the organization. + If present but empty, the personal workspace 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 workspace. nullable: true responses: '200': @@ -3404,6 +3511,8 @@ paths: $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 @@ -3617,6 +3726,8 @@ paths: $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' + '422': + $ref: '#/components/responses/ClerkErrors' /v1/organizations/{organization_id}/logo: put: summary: Update Organization Logo @@ -4067,6 +4178,8 @@ paths: $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' + '422': + $ref: '#/components/responses/ClerkErrors' /v1/organizations/{organization_id}/domains: post: summary: Create Organization Domain @@ -4619,6 +4732,7 @@ components: type: string enum: - delegate_permission/common.handle_all_urls + - delegate_permission/common.get_login_creds target: type: object properties: @@ -5025,6 +5139,73 @@ components: - 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 + 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 + - 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.Token: type: object additionalProperties: false @@ -5039,6 +5220,8 @@ components: type: string scope: type: string + id_token: + type: string required: - access_token - token_type @@ -5122,6 +5305,37 @@ components: 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 + client_id: + type: string + scopes: + type: array + items: + $ref: '#/components/schemas/OAuth.ScopeWithDescription' + required: + - oauth_application_name + - client_id + - scopes Client.AccountPortal: type: object additionalProperties: false @@ -5731,14 +5945,11 @@ components: $ref: '#/components/schemas/UserSettings.Restrictions.Enabled' block_disposable_email_domains: $ref: '#/components/schemas/UserSettings.Restrictions.Enabled' - ignore_dots_for_gmail_addresses: - $ref: '#/components/schemas/UserSettings.Restrictions.Enabled' required: - allowlist - blocklist - block_email_subaddresses - block_disposable_email_domains - - ignore_dots_for_gmail_addresses UserSettings.PasswordSettings: type: object additionalProperties: false @@ -5791,9 +6002,12 @@ components: max_length: type: integer nullable: true + allow_extended_special_characters: + type: boolean required: - min_length - max_length + - allow_extended_special_characters UserSettings.ActionsSettings: type: object additionalProperties: false @@ -5985,14 +6199,47 @@ components: required: - native Client.CommerceSettings: + type: object + additionalProperties: false + properties: + billing: + type: object + additionalProperties: false + properties: + enabled: + type: boolean + stripe_publishable_key: + type: string + nullable: true + has_paid_user_plans: + type: boolean + has_paid_org_plans: + 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 - stripe_publishable_key: - type: string - nullable: true + description: Indicates whether the API Keys feature is enabled. required: - enabled Client.Environment: @@ -6011,6 +6258,8 @@ components: $ref: '#/components/schemas/Client.FraudSettings' commerce_settings: $ref: '#/components/schemas/Client.CommerceSettings' + api_keys_settings: + $ref: '#/components/schemas/Client.ApiKeysSettings' maintenance_mode: type: boolean Token: @@ -6753,6 +7002,9 @@ components: username: type: string nullable: true + phone_number: + type: string + nullable: true public_metadata: type: object additionalProperties: true @@ -6799,6 +7051,11 @@ components: type: string domain: type: string + deprecated: true + domains: + type: array + items: + type: string active: type: boolean provider: @@ -6824,12 +7081,16 @@ components: required: - id - name - - domain - active - provider - sync_user_attributes - created_at - updated_at + anyOf: + - required: + - domain + - required: + - domains Client.SAMLAccount: type: object additionalProperties: false @@ -8666,6 +8927,12 @@ components: 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.Token: description: Fetch token for OAuth2 flow content: @@ -8684,6 +8951,12 @@ components: application/json: schema: $ref: '#/components/schemas/OAuth.TokenInfo' + OAuth.ConsentInfo: + description: OAuth2 consent information for a given OAuth Application Client ID and State + content: + application/json: + schema: + $ref: '#/components/schemas/OAuth.ConsentInfo' Client.AccountPortal: description: Returns the account portal. content: diff --git a/fapi/2024-10-01.yml b/fapi/2024-10-01.yml index a6c82eb..48276b4 100644 --- a/fapi/2024-10-01.yml +++ b/fapi/2024-10-01.yml @@ -146,6 +146,17 @@ paths: 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 @@ -271,6 +282,41 @@ paths: 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. + /v1/oauth/consent/{client_id}: + get: + summary: Get consent information + description: Get required consent information for a given OAuth Application Client ID + operationId: getOAuthConsent + security: + - {} + - DevBrowser: [] + tags: + - OAuth2 Identify 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: _clerk_session_id + schema: + type: string + description: The session_id associated with the requesting user. + 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' /v1/account_portal: get: summary: Get account portal @@ -1405,6 +1451,17 @@ paths: 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: @@ -1719,7 +1776,11 @@ paths: /v1/client/sessions/{session_id}/tokens: post: summary: Create Session Token - description: Create a session jwt for the authenticated requested user. + 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 workspace. operationId: createSessionToken tags: - Sessions @@ -1738,7 +1799,13 @@ paths: 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 workspace will be set as active. If absent, the previous active organization for the session will be used. + description: |- + The organization id to associate with the token. The user must be a member of the organization. + If present but empty, the personal workspace 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 workspace. nullable: true responses: '200': @@ -3404,6 +3471,8 @@ paths: $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 @@ -3617,6 +3686,8 @@ paths: $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' + '422': + $ref: '#/components/responses/ClerkErrors' /v1/organizations/{organization_id}/logo: put: summary: Update Organization Logo @@ -4067,6 +4138,8 @@ paths: $ref: '#/components/responses/ClerkErrors' '404': $ref: '#/components/responses/ClerkErrors' + '422': + $ref: '#/components/responses/ClerkErrors' /v1/organizations/{organization_id}/domains: post: summary: Create Organization Domain @@ -4619,6 +4692,7 @@ components: type: string enum: - delegate_permission/common.handle_all_urls + - delegate_permission/common.get_login_creds target: type: object properties: @@ -5025,6 +5099,73 @@ components: - 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 + 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 + - 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.Token: type: object additionalProperties: false @@ -5039,6 +5180,8 @@ components: type: string scope: type: string + id_token: + type: string required: - access_token - token_type @@ -5122,6 +5265,37 @@ components: 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 + client_id: + type: string + scopes: + type: array + items: + $ref: '#/components/schemas/OAuth.ScopeWithDescription' + required: + - oauth_application_name + - client_id + - scopes Client.AccountPortal: type: object additionalProperties: false @@ -5731,14 +5905,11 @@ components: $ref: '#/components/schemas/UserSettings.Restrictions.Enabled' block_disposable_email_domains: $ref: '#/components/schemas/UserSettings.Restrictions.Enabled' - ignore_dots_for_gmail_addresses: - $ref: '#/components/schemas/UserSettings.Restrictions.Enabled' required: - allowlist - blocklist - block_email_subaddresses - block_disposable_email_domains - - ignore_dots_for_gmail_addresses UserSettings.PasswordSettings: type: object additionalProperties: false @@ -5791,9 +5962,12 @@ components: max_length: type: integer nullable: true + allow_extended_special_characters: + type: boolean required: - min_length - max_length + - allow_extended_special_characters UserSettings.ActionsSettings: type: object additionalProperties: false @@ -5985,14 +6159,47 @@ components: required: - native Client.CommerceSettings: + type: object + additionalProperties: false + properties: + billing: + type: object + additionalProperties: false + properties: + enabled: + type: boolean + stripe_publishable_key: + type: string + nullable: true + has_paid_user_plans: + type: boolean + has_paid_org_plans: + 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 - stripe_publishable_key: - type: string - nullable: true + description: Indicates whether the API Keys feature is enabled. required: - enabled Client.Environment: @@ -6011,6 +6218,8 @@ components: $ref: '#/components/schemas/Client.FraudSettings' commerce_settings: $ref: '#/components/schemas/Client.CommerceSettings' + api_keys_settings: + $ref: '#/components/schemas/Client.ApiKeysSettings' maintenance_mode: type: boolean Token: @@ -6753,6 +6962,9 @@ components: username: type: string nullable: true + phone_number: + type: string + nullable: true public_metadata: type: object additionalProperties: true @@ -6799,6 +7011,11 @@ components: type: string domain: type: string + deprecated: true + domains: + type: array + items: + type: string active: type: boolean provider: @@ -6824,12 +7041,16 @@ components: required: - id - name - - domain - active - provider - sync_user_attributes - created_at - updated_at + anyOf: + - required: + - domain + - required: + - domains Client.SAMLAccount: type: object additionalProperties: false @@ -8666,6 +8887,12 @@ components: 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.Token: description: Fetch token for OAuth2 flow content: @@ -8684,6 +8911,12 @@ components: application/json: schema: $ref: '#/components/schemas/OAuth.TokenInfo' + OAuth.ConsentInfo: + description: OAuth2 consent information for a given OAuth Application Client ID and State + content: + application/json: + schema: + $ref: '#/components/schemas/OAuth.ConsentInfo' Client.AccountPortal: description: Returns the account portal. content: diff --git a/fapi/2025-04-10.yml b/fapi/2025-04-10.yml new file mode 100644 index 0000000..b448859 --- /dev/null +++ b/fapi/2025-04-10.yml @@ -0,0 +1,9460 @@ +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: 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 Identify 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 the an organization and its properties. The current user must be an administrator to access them. + - 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. +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 Identify Provider + 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 Identify Provider + 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/token: + post: + summary: Get OAuth2 token + description: Get OAuth2 token in exchange for a valid authorization grant. + operationId: getOAuthToken + security: [] + tags: + - OAuth2 Identify Provider + responses: + '200': + $ref: '#/components/responses/OAuth.Token' + '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/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 Identify 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 Identify 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 Identify 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. + operationId: revokeOAuthToken + security: [] + tags: + - OAuth2 Identify 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/ClerkErrors' + '401': + $ref: '#/components/responses/ClerkErrors' + '403': + $ref: '#/components/responses/ClerkErrors' + '404': + $ref: '#/components/responses/ClerkErrors' + '422': + $ref: '#/components/responses/ClerkErrors' + /v1/me/oauth/consent/{client_id}: + get: + summary: Get consent information + description: Get required consent information for a given OAuth Application Client ID + operationId: getOAuthConsent + security: + - {} + - DevBrowser: [] + tags: + - OAuth2 Identify 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: _clerk_session_id + schema: + type: string + description: The session_id associated with the requesting user. + 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' + /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: The origin of the request + required: true + schema: + type: string + responses: + '200': + $ref: '#/components/responses/Client.Environment' + '400': + $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': + description: Bad request + $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' + 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_coinbase_wallet_signature`, + `web3_okx_wallet_signature`, `reset_password_phone_code`, `reset_password_email_code`, + `oauth_[provider]`, `saml`, `passkey` + 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_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_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 the 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_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`. + 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 + phone_number_id: + type: string + description: Used with the `phone_code` strategy. + 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`, 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 first 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.SignIn' + '307': + description: Redirect, no body. + '400': + $ref: '#/components/responses/ClerkErrors' + '403': + $ref: '#/components/responses/ClerkErrors' + '422': + $ref: '#/components/responses/ClerkErrors' + /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 `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 + 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 `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 + 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_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_coinbase_wallet_signature + - web3_okx_wallet_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 + '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 returns 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 workspace 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/dev_browser: + post: + summary: Create a Dev Browser token + description: |- + Generate an 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 Broswer 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/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 workspace. + 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 workspace. + nullable: true + 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' + '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 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 workspace. + 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 workspace 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 workspace. + nullable: true + 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}/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 fallback 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 + 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 the 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/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 containg a link to the verification attempt endpoint. * for `enterprise_sso`, the API will send an external redirect URL to the browser containg 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 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 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. + 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-z]+$ + 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 + required: + - strategy + 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' + '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 authenitcation 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 medata 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/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' + '422': + $ref: '#/components/responses/ClerkErrors' + /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. + 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 + - 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 a 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 role that 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 domains 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/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' +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 an 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 authentication 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 `Authorization` header authentication strategy. + 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 + clerk_trace_id: + type: string + 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 + 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 + required: + - issuer + - authorization_endpoint + - token_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 + 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 + - 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.Token: + type: object + additionalProperties: false + properties: + access_token: + type: string + token_type: + type: string + expires_in: + type: integer + refresh_token: + type: string + scope: + type: string + id_token: + type: string + 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 + client_id: + type: string + scopes: + type: array + items: + $ref: '#/components/schemas/OAuth.ScopeWithDescription' + required: + - oauth_application_name + - client_id + - scopes + 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 + required: + - enabled + - required + - used_for_first_factor + - first_factors + - used_for_second_factor + - second_factors + - verifications + - verify_at_sign_up + 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 + 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' + block_email_subaddresses: + $ref: '#/components/schemas/UserSettings.Restrictions.Enabled' + block_disposable_email_domains: + $ref: '#/components/schemas/UserSettings.Restrictions.Enabled' + required: + - allowlist + - blocklist + - 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 + required: + - min_length + - max_length + - allow_extended_special_characters + 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: + 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' + required: + - user_lockout + - pii + - email_link + 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 + 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' + 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: + enabled: + type: boolean + stripe_publishable_key: + type: string + nullable: true + has_paid_user_plans: + type: boolean + has_paid_org_plans: + 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. + required: + - enabled + 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' + maintenance_mode: + type: boolean + 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.SessionTask: + type: object + properties: + key: + type: string + required: + - key + 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 + Stubs.Verification.OTP: + type: object + additionalProperties: false + properties: + 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: + 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 + additionalProperties: false + properties: + status: + type: string + enum: + - unverified + - verified + - failed + - expired + 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 + additionalProperties: false + properties: + 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: + status: + type: string + enum: + - verified + strategy: + type: string + enum: + - admin + attempts: + type: integer + nullable: true + expire_at: + type: integer + nullable: true + required: + - status + - strategy + Stubs.Verification.FromOauth: + type: object + additionalProperties: false + properties: + 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 + additionalProperties: false + properties: + 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 + additionalProperties: false + properties: + status: + type: string + enum: + - unverified + - verified + - failed + - expired + strategy: + type: string + enum: + - web3_metamask_signature + - web3_coinbase_wallet_signature + - web3_okx_wallet_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: + 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 + 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 + Oauth: + type: object + additionalProperties: false + properties: + 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 + GoogleOneTap: + type: object + additionalProperties: false + properties: + 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 + 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/Oauth' + - $ref: '#/components/schemas/GoogleOneTap' + 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 + 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 + 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. + 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_coinbase_wallet_signature + - web3_okx_wallet_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 + 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: + 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: + status: + type: string + enum: + - unverified + - verified + - failed + - expired + - transferable + strategy: + type: string + pattern: ^oauth_(?:(?:token_)|(?:custom_))?[a-z]+$ + 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: + 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: + 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: + 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_new_password + - 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 + 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: + 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: + - $ref: '#/components/schemas/Stubs.SignUpVerification' + phone_number: + type: object + nullable: true + oneOf: + - $ref: '#/components/schemas/Stubs.SignUpVerification' + web3_wallet: + type: object + nullable: true + oneOf: + - $ref: '#/components/schemas/Stubs.SignUpVerification' + 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. + 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 + - 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/Client.Client' + client: + type: object + nullable: true + allOf: + - $ref: '#/components/schemas/Client.Client' + required: + - response + - client + Client.DeleteSession: + type: object + additionalProperties: false + properties: + response: + type: object + nullable: true + allOf: + - $ref: '#/components/schemas/Client.Client' + client: + type: object + nullable: true + required: + - response + - client + Client.ClientWrappedSignIn: + type: object + additionalProperties: false + properties: + response: + $ref: '#/components/schemas/Client.SignIn' + client: + $ref: '#/components/schemas/Client.Client' + required: + - response + - client + 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 + 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 + 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.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/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. + 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 + - cookie_expires_at + - captcha_bypass + - created_at + - updated_at + schemas-Client.ClientWrappedSignIn: + type: object + additionalProperties: false + properties: + response: + $ref: '#/components/schemas/Client.SignIn' + client: + $ref: '#/components/schemas/schemas-Client.Client' + required: + - response + - client + Client.ClientWrappedSignUp: + type: object + additionalProperties: false + properties: + response: + $ref: '#/components/schemas/Client.SignUp' + client: + $ref: '#/components/schemas/Client.Client' + required: + - response + - client + Client.ClientWrappedSession: + type: object + additionalProperties: false + properties: + response: + $ref: '#/components/schemas/Client.Session' + client: + $ref: '#/components/schemas/Client.Client' + 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/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' + 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/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/Client.Client' + required: + - response + - client + Server.Sessions: + type: array + items: + $ref: '#/components/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/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/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/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/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/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/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/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/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/Client.Client' + required: + - response + - client + Client.ClientWrappedImage: + type: object + properties: + response: + $ref: '#/components/schemas/Image' + client: + $ref: '#/components/schemas/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/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/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 + - 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/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/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/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/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/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/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/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/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/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 + 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/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/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/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/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 + client: + type: object + nullable: false + allOf: + - $ref: '#/components/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.Token: + description: Fetch token for OAuth2 flow + content: + application/json: + schema: + $ref: '#/components/schemas/OAuth.Token' + 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 for a given OAuth Application Client ID and State + content: + application/json: + schema: + $ref: '#/components/schemas/OAuth.ConsentInfo' + 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.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.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 + - name: Organizations + tags: + - Organization + - Invitations + - Membership Requests + - Members + - Domains + - Roles + - name: Other + tags: + - Well Known + - DevBrowser + - Health + - OAuth2 Identify Provider + - OAuth2 Callbacks + - SAML + - Waitlist