lib/swagger/clerk.yaml

---
openapi: 3.0.3
info:
  title: Clerk Backend API
  x-logo:
    url: https://clerk.com/_next/image?url=%2Fimages%2Fclerk-logo.svg&w=96&q=75
    altText: Clerk docs
    href: https://clerk.com/docs
  contact:
    email: support@clerk.com
    name: Clerk Platform Team
    url: https://clerk.com/support
  description:
    The Clerk REST Backend API, meant to be accessed by backend servers.
    Please see https://clerk.com/docs for more information.
  version: v1
  termsOfService: https://clerk.com/terms
  license:
    name: MIT
    url: https://github.com/clerkinc/clerk-sdk-go/blob/main/LICENSE
externalDocs:
  url: https://clerk.com/docs
servers:
  - url: https://api.clerk.dev/v1
  - url: https://api.clerk.com/v1
security:
  - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  parameters:
    LimitParameter:
      name: limit
      in: query
      description: |-
        Applies a limit to the number of results returned.
        Can be used for paginating the results together with `offset`.
        Must be an integer greater than zero and less than 500.
        By default, if not supplied, a limit of 10 is used.
      required: false
      schema:
        type: number
        default: 10
        minimum: 1
        maximum: 500
    OffsetParameter:
      name: offset
      in: query
      description: |-
        Skip the first `offset` results when paginating.
        Needs to be an integer greater or equal to zero.
        To be used in conjunction with `limit`.
      required: false
      schema:
        type: number
        default: 0
        minimum: 0
  schemas:
    Session:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          description:
            "String representing the object's type. Objects of the same
            type share the same value.

            "
          enum:
            - session
        id:
          type: string
        user_id:
          type: string
        client_id:
          type: string
        actor:
          type: object
          nullable: true
        status:
          type: string
          enum:
            - active
            - revoked
            - ended
            - expired
            - removed
            - abandoned
        last_active_organization_id:
          type: string
          nullable: true
        last_active_at:
          type: integer
        expire_at:
          type: integer
        abandon_at:
          type: integer
        updated_at:
          type: integer
          format: int64
          description: "Unix timestamp of last update.

            "
        created_at:
          type: integer
          format: int64
          description: "Unix timestamp of creation.

            "
      required:
        - object
        - id
        - user_id
        - client_id
        - status
        - last_active_at
        - expire_at
        - abandon_at
        - updated_at
        - created_at
    Client:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          description:
            "String representing the object's type. Objects of the same
            type share the same value.

            "
          enum:
            - client
        id:
          type: string
          description: "String representing the identifier of the session.

            "
        session_ids:
          type: array
          items:
            type: string
        sessions:
          type: array
          items:
            "$ref": "#/components/schemas/Session"
        sign_in_attempt_id:
          type: string
          nullable: true
          deprecated: true
        sign_up_attempt_id:
          type: string
          nullable: true
          deprecated: true
        sign_in_id:
          type: string
          nullable: true
        sign_up_id:
          type: string
          nullable: true
        last_active_session_id:
          nullable: true
          type: string
          description: "Last active session_id.

            "
        updated_at:
          type: integer
          format: int64
          description: "Unix timestamp of last update.

            "
        created_at:
          type: integer
          format: int64
          description: "Unix timestamp of creation.

            "
      required:
        - object
        - id
        - session_ids
        - sessions
        - sign_in_attempt_id
        - sign_up_attempt_id
        - sign_in_id
        - sign_up_id
        - last_active_session_id
        - updated_at
        - created_at
    ClerkError:
      type: object
      properties:
        message:
          type: string
        long_message:
          type: string
        code:
          type: string
        meta:
          type: object
      required:
        - message
        - long_message
        - code
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            "$ref": "#/components/schemas/ClerkError"
        meta:
          type: object
      required:
        - errors
    OTP:
      type: object
      additionalProperties: false
      properties:
        status:
          type: string
          enum:
            - unverified
            - verified
            - failed
            - expired
        strategy:
          type: string
          enum:
            - phone_code
            - email_code
        attempts:
          type: integer
        expire_at:
          type: integer
      required:
        - status
        - attempts
        - strategy
        - expire_at
    Admin:
      type: object
      additionalProperties: false
      properties:
        status:
          type: string
          enum:
            - verified
        strategy:
          type: string
          enum:
            - admin
        attempts:
          type: integer
          nullable: true
        expire_at:
          type: integer
          nullable: true
      required:
        - status
        - strategy
    IdentificationLink:
      type: object
      additionalProperties: false
      properties:
        type:
          type: string
          enum:
            - oauth_google
            - oauth_mock
        id:
          type: string
      required:
        - type
        - id
    EmailAddress:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        object:
          type: string
          description:
            "String representing the object's type. Objects of the same
            type share the same value.

            "
          enum:
            - email_address
        email_address:
          type: string
        reserved:
          type: boolean
        verification:
          type: object
          nullable: true
          oneOf:
            - "$ref": "#/components/schemas/OTP"
            - "$ref": "#/components/schemas/Admin"
        linked_to:
          type: array
          items:
            "$ref": "#/components/schemas/IdentificationLink"
      required:
        - object
        - email_address
        - verification
        - linked_to
        - reserved
    DeletedObject:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
        id:
          type: string
        slug:
          type: string
        deleted:
          type: boolean
      required:
        - object
        - deleted
    PhoneNumber:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        object:
          type: string
          description:
            "String representing the object's type. Objects of the same
            type share the same value.

            "
          enum:
            - phone_number
        phone_number:
          type: string
        reserved_for_second_factor:
          type: boolean
        default_second_factor:
          type: boolean
        reserved:
          type: boolean
        verification:
          type: object
          nullable: true
          oneOf:
            - "$ref": "#/components/schemas/OTP"
            - "$ref": "#/components/schemas/Admin"
        linked_to:
          type: array
          items:
            "$ref": "#/components/schemas/IdentificationLink"
        backup_codes:
          type: array
          items:
            type: string
          nullable: true
      required:
        - object
        - phone_number
        - verification
        - linked_to
        - reserved
    Template:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        object:
          type: string
          description:
            "String representing the object's type. Objects of the same
            type share the same value.

            "
          enum:
            - template
        instance_id:
          nullable: true
          type: string
          description: the id of the instance the template belongs to
        resource_type:
          type: string
          description: whether this is a system (default) or user overridden) template
        template_type:
          type: string
          description: whether this is an email or SMS template
        name:
          type: string
          description: user-friendly name of the template
        slug:
          type: string
          description: machine-friendly name of the template
        position:
          type: integer
          description: position with the listing of templates
        can_revert:
          type: boolean
          description:
            whether this template can be reverted to the corresponding
            system default
        can_delete:
          type: boolean
          description: whether this template can be deleted
        subject:
          type: string
          description: email subject
          nullable: true
        markup:
          type: string
          description: the editor markup used to generate the body of the template
        body:
          type: string
          description: the template body before variable interpolation
        available_variables:
          type: array
          description:
            list of variables that are available for use in the template
            body
          items:
            type: string
        required_variables:
          type: array
          description: list of variables that must be contained in the template body
          items:
            type: string
        from_email_name:
          type: string
        delivered_by_clerk:
          type: boolean
        updated_at:
          type: integer
          format: int64
          description: "Unix timestamp of last update.

            "
        created_at:
          type: integer
          format: int64
          description: "Unix timestamp of creation.

            "
    Web3Signature:
      type: object
      additionalProperties: false
      properties:
        status:
          type: string
          enum:
            - verified
        strategy:
          type: string
          enum:
            - web3_metamask_signature
        nonce:
          type: string
          enum:
            - nonce
        attempts:
          type: integer
          nullable: true
        expire_at:
          type: integer
          nullable: true
      required:
        - status
        - strategy
        - nonce
    Web3Wallet:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        object:
          type: string
          description:
            "String representing the object's type. Objects of the same
            type share the same value.

            "
          enum:
            - web3_wallet
        web3_wallet:
          type: string
        verification:
          type: object
          nullable: true
          oneOf:
            - "$ref": "#/components/schemas/Web3Signature"
            - "$ref": "#/components/schemas/Admin"
      required:
        - object
        - web3_wallet
        - verification
    User:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        object:
          type: string
          description:
            "String representing the object's type. Objects of the same
            type share the same value.

            "
          enum:
            - user
        external_id:
          nullable: true
          type: string
        primary_email_address_id:
          nullable: true
          type: string
        primary_phone_number_id:
          nullable: true
          type: string
        primary_web3_wallet_id:
          nullable: true
          type: string
        username:
          nullable: true
          type: string
        first_name:
          nullable: true
          type: string
        last_name:
          nullable: true
          type: string
        profile_image_url:
          type: string
          deprecated: true
        image_url:
          type: string
        public_metadata:
          type: object
        private_metadata:
          nullable: true
          type: object
        unsafe_metadata:
          type: object
        gender:
          nullable: true
          type: string
        birthday:
          nullable: true
          type: string
        email_addresses:
          type: array
          items:
            "$ref": "#/components/schemas/EmailAddress"
        phone_numbers:
          type: array
          items:
            "$ref": "#/components/schemas/PhoneNumber"
        web3_wallets:
          type: array
          items:
            "$ref": "#/components/schemas/Web3Wallet"
        password_enabled:
          type: boolean
        two_factor_enabled:
          type: boolean
        totp_enabled:
          type: boolean
        backup_code_enabled:
          type: boolean
        external_accounts:
          type: array
          items:
            type: object
        last_sign_in_at:
          type: integer
          format: int64
          nullable: true
          description: "Unix timestamp of last sign-in.

            "
        banned:
          type: boolean
          description: "Flag to denote whether user is banned or not.

            "
        updated_at:
          type: integer
          format: int64
          description: "Unix timestamp of last update.

            "
        created_at:
          type: integer
          format: int64
          description: "Unix timestamp of creation.

            "
    TotalCount:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          description:
            "String representing the object's type. Objects of the same
            type share the same value.

            "
          enum:
            - total_count
        total_count:
          type: integer
          format: int64
      required:
        - object
        - total_count
    Organization:
      type: object
      properties:
        object:
          type: string
          enum:
            - organization
        id:
          type: string
        name:
          type: string
        slug:
          type: string
        members_count:
          type: integer
          nullable: true
        max_allowed_memberships:
          type: integer
        public_metadata:
          type: object
        private_metadata:
          type: object
        created_by:
          type: string
        created_at:
          type: integer
          format: int64
          description: "Unix timestamp of creation.

            "
        updated_at:
          type: integer
          format: int64
          description: "Unix timestamp of last update.

            "
      required:
        - object
        - id
        - name
        - slug
        - max_allowed_memberships
        - public_metadata
        - private_metadata
        - created_at
        - updated_at
    OrganizationMembership:
      description: Hello world
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          description:
            "String representing the object's type. Objects of the same
            type share the same value.

            "
          enum:
            - organization_membership
        role:
          type: string
          enum:
            - admin
            - basic_member
        created_at:
          type: integer
          format: int64
          description: Unix timestamp of creation.
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp of last update.
        organization:
          type: object
          nullable: false
          allOf:
            - "$ref": "#/components/schemas/Organization"
        public_user_data:
          type: object
          additionalProperties: false
          properties:
            user_id:
              type: string
              nullable: false
            first_name:
              type: string
              nullable: true
            last_name:
              type: string
              nullable: true
            profile_image_url:
              type: string
              nullable: true
              deprecated: true
            image_url:
              type: string
              nullable: true
            identifier:
              type: string
              nullable: true
    OrganizationMemberships:
      type: object
      additionalProperties: false
      properties:
        data:
          type: array
          items:
            "$ref": "#/components/schemas/OrganizationMembership"
        total_count:
          type: integer
          format: int64
          description: "Total number of organization memberships

            "
      required:
        - data
        - total_count
    Email:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
            - email
        id:
          type: string
        slug:
          type: string
          nullable: true
        from_email_name:
          type: string
        email_address_id:
          type: string
          nullable: true
        to_email_address:
          type: string
        user_id:
          type: string
          nullable: true
        subject:
          type: string
        body:
          type: string
        body_plain:
          type: string
          nullable: true
        status:
          type: string
        data:
          type: object
          nullable: true
        delivered_by_clerk:
          type: boolean
      required:
        - object
        - id
        - from_email_name
        - email_address_id
        - to_email_address
        - subject
        - body
        - status
        - delivered_by_clerk
    SMSMessage:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
            - sms_message
        id:
          type: string
        slug:
          type: string
          nullable: true
        from_phone_number:
          type: string
        to_phone_number:
          type: string
        phone_number_id:
          type: string
          nullable: true
        user_id:
          type: string
          nullable: true
        message:
          type: string
        status:
          type: string
        data:
          type: object
          nullable: true
        delivered_by_clerk:
          type: boolean
      required:
        - object
        - id
        - from_phone_number
        - to_phone_number
        - phone_number_id
        - message
        - status
        - delivered_by_clerk
    Invitation:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
            - invitation
        id:
          type: string
        email_address:
          type: string
          format: email
        public_metadata:
          type: object
        revoked:
          type: boolean
          example: true
        status:
          type: string
          enum:
            - pending
            - accepted
            - revoked
          example: revoked
        created_at:
          type: integer
          format: int64
          description: "Unix timestamp of creation.

            "
        updated_at:
          type: integer
          format: int64
          description: "Unix timestamp of last update.

            "
      required:
        - object
        - id
        - email_address
        - status
        - created_at
        - updated_at
    AllowlistIdentifier:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          description:
            "String representing the object's type. Objects of the same
            type share the same value.

            "
          enum:
            - allowlist_identifier
        id:
          type: string
        invitation_id:
          type: string
        identifier:
          type: string
          description: "An email address or a phone number.

            "
        identifier_type:
          type: string
          enum:
            - email_address
            - phone_number
            - web3_wallet
        instance_id:
          type: string
        created_at:
          type: integer
          format: int64
          description: "Unix timestamp of creation

            "
        updated_at:
          type: integer
          format: int64
          description: "Unix timestamp of last update.

            "
    BlocklistIdentifier:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          description:
            "String representing the object's type. Objects of the same
            type share the same value.

            "
          enum:
            - blocklist_identifier
        id:
          type: string
        identifier:
          type: string
          description:
            "An email address, email domain, phone number or web3 wallet.

            "
        identifier_type:
          type: string
          enum:
            - email_address
            - phone_number
            - web3_wallet
        instance_id:
          type: string
        created_at:
          type: integer
          format: int64
          description: "Unix timestamp of creation

            "
        updated_at:
          type: integer
          format: int64
          description: "Unix timestamp of last update.

            "
    BlocklistIdentifiers:
      type: object
      additionalProperties: false
      properties:
        data:
          type: array
          items:
            "$ref": "#/components/schemas/BlocklistIdentifier"
        total_count:
          type: integer
          format: int64
          description: "Total number of blocklist identifiers

            "
      required:
        - data
        - total_count
    ActorToken:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
            - actor_token
        id:
          type: string
        status:
          type: string
          enum:
            - pending
            - accepted
            - revoked
        user_id:
          type: string
        actor:
          type: object
        token:
          type: string
          nullable: true
        url:
          type: string
          nullable: true
        created_at:
          type: integer
          format: int64
          description: "Unix timestamp of creation.

            "
        updated_at:
          type: integer
          format: int64
          description: "Unix timestamp of last update.

            "
      required:
        - object
        - id
        - user_id
        - actor
        - status
        - created_at
        - updated_at
    InstanceRestrictions:
      type: object
      properties:
        object:
          type: string
          description:
            String representing the object's type. Objects of the same
            type share the same value.
          enum:
            - instance_restrictions
        allowlist:
          type: boolean
        blocklist:
          type: boolean
    OrganizationSettings:
      type: object
      properties:
        object:
          type: string
          description:
            String representing the object's type. Objects of the same
            type share the same value.
          enum:
            - organization_settings
        enabled:
          type: boolean
        max_allowed_memberships:
          type: integer
      required:
        - object
        - enabled
        - max_allowed_memberships
    SvixURL:
      type: object
      additionalProperties: false
      properties:
        svix_url:
          type: string
      required:
        - svix_url
    JWTTemplate:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
            - jwt_template
        id:
          type: string
        name:
          type: string
        claims:
          type: object
        lifetime:
          type: integer
        allowed_clock_skew:
          type: integer
        custom_signing_key:
          type: boolean
        signing_algorithm:
          type: string
        created_at:
          type: integer
          format: int64
          description: "Unix timestamp of creation.

            "
        updated_at:
          type: integer
          format: int64
          description: "Unix timestamp of last update.

            "
      required:
        - object
        - id
        - name
        - claims
        - lifetime
        - allowed_clock_skew
        - created_at
        - updated_at
    Organizations:
      type: object
      additionalProperties: false
      properties:
        data:
          type: array
          items:
            "$ref": "#/components/schemas/Organization"
        total_count:
          type: integer
          format: int64
          description: "Total number of organizations

            "
      required:
        - data
        - total_count
    OrganizationWithLogo:
      type: object
      allOf:
        - "$ref": "#/components/schemas/Organization"
        - type: object
          properties:
            logo_url:
              type: string
              deprecated: true
            image_url:
              type: string
          required:
            - logo_url
            - image_url
    OrganizationInvitation:
      description: An organization invitation
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          description:
            "String representing the object's type. Objects of the same
            type share the same value.

            "
          enum:
            - organization_invitation
        email_address:
          type: string
        role:
          type: string
          enum:
            - admin
            - basic_member
        organization_id:
          type: string
        status:
          type: string
        created_at:
          type: integer
          format: int64
          description: Unix timestamp of creation.
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp of last update.
    OrganizationInvitations:
      type: object
      additionalProperties: false
      properties:
        data:
          type: array
          items:
            "$ref": "#/components/schemas/OrganizationInvitation"
        total_count:
          type: integer
          format: int64
          description: "Total number of organization invitations

            "
      required:
        - data
        - total_count
    RedirectURL:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
            - redirect_url
        id:
          type: string
        url:
          type: string
        created_at:
          type: integer
          format: int64
          description: "Unix timestamp of creation.

            "
        updated_at:
          type: integer
          format: int64
          description: "Unix timestamp of last update.

            "
      required:
        - object
        - id
        - url
        - created_at
        - updated_at
    SignInToken:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
            - sign_in_token
        id:
          type: string
        status:
          type: string
          enum:
            - pending
            - accepted
            - revoked
        user_id:
          type: string
        token:
          type: string
        url:
          type: string
          nullable: true
        created_at:
          type: integer
          format: int64
          description: "Unix timestamp of creation.

            "
        updated_at:
          type: integer
          format: int64
          description: "Unix timestamp of last update.

            "
      required:
        - object
        - id
        - user_id
        - status
        - created_at
        - updated_at
    SignUp:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
            - sign_up_attempt
        id:
          type: string
        status:
          type: string
          enum:
            - missing_requirements
            - complete
            - abandoned
        required_fields:
          type: array
          items:
            type: string
        optional_fields:
          type: array
          items:
            type: string
        missing_fields:
          type: array
          items:
            type: string
        unverified_fields:
          type: array
          items:
            type: string
        verifications:
          type: object
        username:
          type: string
          nullable: true
        email_address:
          type: string
          nullable: true
        phone_number:
          type: string
          nullable: true
        web3_wallet:
          type: string
          nullable: true
        password_enabled:
          type: boolean
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        unsafe_metadata:
          type: object
        public_metadata:
          type: object
        custom_action:
          type: boolean
        external_id:
          type: string
          nullable: true
        created_session_id:
          type: string
          nullable: true
        created_user_id:
          type: string
          nullable: true
        abandon_at:
          type: integer
        identification_requirements:
          type: array
          items:
            type: array
            items:
              type: string
        missing_requirements:
          type: array
          items:
            type: string
        email_address_verification:
          type: object
          nullable: true
          deprecated: true
        phone_number_verification:
          type: object
          nullable: true
          deprecated: true
        external_account_strategy:
          type: string
          nullable: true
        external_account_verification:
          type: object
          nullable: true
          deprecated: true
        external_account:
          type: object
      required:
        - object
        - id
        - status
        - password_enabled
        - custom_action
        - abandon_at
    OAuthApplication:
      type: object
      properties:
        object:
          type: string
          enum:
            - oauth_application
        id:
          type: string
        instance_id:
          type: string
        name:
          type: string
        client_id:
          type: string
        scopes:
          type: string
        callback_url:
          type: string
        authorize_url:
          type: string
        token_fetch_url:
          type: string
        user_info_url:
          type: string
        created_at:
          type: integer
          format: int64
          description: "Unix timestamp of creation.

            "
        updated_at:
          type: integer
          format: int64
          description: "Unix timestamp of last update.

            "
      required:
        - object
        - id
        - instance_id
        - name
        - client_id
        - scopes
        - callback_url
        - authorize_url
        - token_fetch_url
        - user_info_url
        - created_at
        - updated_at
    OAuthApplications:
      type: object
      additionalProperties: false
      properties:
        data:
          type: array
          items:
            "$ref": "#/components/schemas/OAuthApplication"
        total_count:
          type: integer
          format: int64
          description: "Total number of OAuth applications

            "
      required:
        - data
        - total_count
    OAuthApplicationWithSecret:
      allOf:
        - "$ref": "#/components/schemas/OAuthApplication"
        - type: object
          properties:
            client_secret:
              type: string
          required:
            - client_secret
  responses:
    Client.List:
      description: Success
      content:
        application/json:
          schema:
            type: array
            items:
              "$ref": "#/components/schemas/Client"
    ClerkErrors:
      description: Request was not successful
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/ClerkErrors"
    AuthenticationInvalid:
      description: Authentication invalid
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/ClerkErrors"
    UnprocessableEntity:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/ClerkErrors"
    Client:
      description: Success
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/Client"
    ResourceNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/ClerkErrors"
    Session:
      description: Success
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/Session"
    EmailAddress:
      description: Success
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/EmailAddress"
    AuthorizationInvalid:
      description: Authorization invalid
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/ClerkErrors"
    DeletedObject:
      description: Deleted Object
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/DeletedObject"
    PhoneNumber:
      description: Success
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/PhoneNumber"
    Session.List:
      description: Success
      content:
        application/json:
          schema:
            type: array
            items:
              "$ref": "#/components/schemas/Session"
    Template.List:
      description: Success
      content:
        application/json:
          schema:
            type: array
            items:
              "$ref": "#/components/schemas/Template"
    Template:
      description: Success
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/Template"
    PaymentRequired:
      description: Payment required
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/ClerkErrors"
    User.List:
      description: Success
      content:
        application/json:
          schema:
            type: array
            items:
              "$ref": "#/components/schemas/User"
    User:
      description: Success
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/User"
    User.Count:
      description: Success
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/TotalCount"
    OrganizationMemberships:
      description: A list of organization memberships
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/OrganizationMemberships"
    Email:
      description: Success
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/Email"
    SMSMessage:
      description: Success
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/SMSMessage"
    Invitation.List:
      description: List of invitations
      content:
        application/json:
          schema:
            type: array
            items:
              "$ref": "#/components/schemas/Invitation"
    Invitation:
      description: Success
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/Invitation"
    AllowlistIdentifier.List:
      description: Success
      content:
        application/json:
          schema:
            type: array
            items:
              "$ref": "#/components/schemas/AllowlistIdentifier"
    AllowlistIdentifier:
      description: Success
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/AllowlistIdentifier"
    BlocklistIdentifier.List:
      description: Success
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/BlocklistIdentifiers"
    BlocklistIdentifier:
      description: Success
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/BlocklistIdentifier"
    InstanceSettings:
      description: InstanceSettings Server API
      content:
        application/json:
          schema:
            type: object
            properties:
              object:
                type: string
                description:
                  String representing the object's type. Objects of the
                  same type share the same value.
                enum:
                  - instance_settings
              id:
                type: string
              restricted_to_allowlist:
                type: boolean
              from_email_address:
                type: string
              progressive_sign_up:
                type: boolean
              enhanced_email_deliverability:
                type: boolean
    ActorToken:
      description: Success
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/ActorToken"
    InstanceRestrictions:
      description: Success
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/InstanceRestrictions"
    OrganizationSettings:
      description: Success
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/OrganizationSettings"
    SvixURL:
      description:
        Response that contains a temporary Svix URL to access management
        dashboard
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/SvixURL"
    JWTTemplate.List:
      description: List of JWT templates
      content:
        application/json:
          schema:
            type: array
            items:
              "$ref": "#/components/schemas/JWTTemplate"
    JWTTemplate:
      description: Success
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/JWTTemplate"
    Organizations:
      description: A list of organizations
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/Organizations"
    Organization:
      description: An organization
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/Organization"
    OrganizationWithLogo:
      description: An organization with a logo URL.
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/OrganizationWithLogo"
    OrganizationInvitation:
      description: An organization invitation
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/OrganizationInvitation"
    OrganizationInvitations:
      description: A list of organization invitations
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/OrganizationInvitations"
    OrganizationMembership:
      description: Success
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/OrganizationMembership"
    RedirectURL.List:
      description: List of Redirect URLs
      content:
        application/json:
          schema:
            type: array
            items:
              "$ref": "#/components/schemas/RedirectURL"
    RedirectURL:
      description: Success
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/RedirectURL"
    SignInToken:
      description: Success
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/SignInToken"
    SignUp:
      description: Success
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/SignUp"
    OAuthApplications:
      description: A list of OAuth applications
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/OAuthApplications"
    OAuthApplicationWithSecret:
      description: An OAuth application with client secret
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/OAuthApplicationWithSecret"
    OAuthApplication:
      description: An OAuth application
      content:
        application/json:
          schema:
            "$ref": "#/components/schemas/OAuthApplication"
tags:
  - name: Actor Tokens
    description: Allow your users to sign in on behalf of other users.
    externalDocs:
      url: https://clerk.com/docs/authentication/user-impersonation#actor-tokens
  - name: Allow-list / Block-list
    description: |-
      Allow-lists and Block-lists allow you to control who can sign up or sign in
      to your application, by restricting access based on the user's email
      address or phone number.
    externalDocs:
      url: https://clerk.com/docs/authentication/allowlist
  - name: Clients
    description:
      The Client object tracks sessions, as well as the state of any sign
      in and sign up attempts, for a given device.
    externalDocs:
      url: https://clerk.com/docs/reference/clerkjs/client
  - name: Email Addresses
    description:
      A user can be associated with one or more email addresses and allows
      them to be contacted via email.
    externalDocs:
      url: https://clerk.com/docs/reference/clerkjs/emailaddress
  - name: Emails
    description: |-
      The email object represents an email that has been sent to an email address.
      You can only send an email to email addresses that have been verified by a user.
      Only recommended for transactional emails.
  - name: Email & SMS Templates
    description:
      Email & SMS templates allow you to customize the theming and wording
      of emails & SMS messages that are sent by your instance.
    externalDocs:
      url: https://clerk.com/docs/authentication/email-sms-templates
  - name: Instance Settings
    description: Modify the settings of your instance.
  - name: Invitations
    description:
      Invitations allow you to invite someone to sign up to your application,
      via email.
    externalDocs:
      url: https://clerk.com/docs/authentication/invitations
  - name: JWKS
    description:
      Retrieve the JSON Web Key Set which can be used to verify the token
      signatures of the instance.
  - name: JWT Templates
    description: |-
      JWT Templates allow you to generate custom authentication tokens
      tied to authenticated sessions, enabling you to integrate with third-party
      services.
    externalDocs:
      url: https://clerk.com/docs/request-authentication/jwt-templates
  - name: OAuth Applications
    description:
      OAuth applications contain data for clients using Clerk as an OAuth2
      identity provider.
  - name: Organizations
    description:
      Organizations are used to group members under a common entity and provide
      shared access to resources.
    externalDocs:
      url: https://clerk.com/docs/organizations/overview
  - name: Organization Invitations
    description: Invite users to an organization.
    externalDocs:
      url: https://clerk.com/docs/organizations/invite-users
  - name: Organization Memberships
    description: Manage member roles in an organization.
    externalDocs:
      url: https://clerk.com/docs/organizations/manage-member-roles
  - name: Phone Numbers
    description:
      A user can be associated with one or more email addresses and allows
      them to be contacted via SMS.
    externalDocs:
      url: https://clerk.com/docs/reference/clerkjs/phonenumber
  - name: Redirect URLs
    description: |-
      Redirect URLs are whitelisted URLs that facilitate secure authentication flows in native applications (e.g. React Native, Expo).
      In these contexts, Clerk ensures that security-critical nonces are passed only to the whitelisted URLs.
  - name: Sessions
    description: |-
      The Session object is an abstraction over an HTTP session.
      It models the period of information exchange between a user and the server.
      Sessions are created when a user successfully goes through the sign in or sign up flows.
    externalDocs:
      url: https://clerk.com/docs/reference/clerkjs/session
  - name: Sign-in Tokens
    description: |-
      Sign-in tokens are JWTs that can be used to sign in to an application without specifying any credentials.
      A sign-in token can be used at most once and they can be consumed from the Frontend API using the `ticket` strategy.
  - name: SMS Messages
    description: |-
      SMS messages can be sent to verified phone numbers that belong to users.
      This functionality is only recommended for transactional SMS messages.
  - name: Users
    description:
      The user object represents a user that has successfully signed up to
      your application.
    externalDocs:
      url: https://clerk.com/docs/reference/clerkjs/user
  - name: Webhooks
    description:
      You can configure webhooks to be notified about various events that
      happen on your instance.
    externalDocs:
      url: https://clerk.com/docs/integration/webhooks
  - name: Miscellaneous
    description: Various endpoints that do not belong in any particular category.
  - name: Beta Features
    description: Modify instance settings that are currently in beta.
paths:
  "/public/demo_instance":
    post:
      security: []
      operationId: CreateDemoInstance
      summary: Create a demo development instance
      description:
        Creates a demo development instance and returns the corresponding
        Frontend/Backend API keys.
      tags:
        - Miscellaneous
      responses:
        "200":
          description: The API keys of the created instance.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  object:
                    type: string
                    enum:
                      - demo_dev_instance
                  frontend_api_key:
                    type: string
                  backend_api_key:
                    type: string
                  jwt_verification_key:
                    type: string
                    description:
                      The public key that can be used to verify the session
                      tokens of the created instance.
                  accounts_url:
                    type: string
                    description:
                      The URL of the hosted Accounts Portal of the created
                      instance.
                    format: uri
  "/public/interstitial":
    get:
      security: []
      summary: Returns the markup for the interstitial page
      description: |-
        The Clerk interstitial endpoint serves an html page that loads clerk.js in order to check the user's authentication state.
        It is used by Clerk SDKs when the user's authentication state cannot be immediately determined.
      operationId: GetPublicInterstitial
      tags:
        - Miscellaneous
      parameters:
        - name: frontendApi
          in: query
          required: false
          description: The Frontend API key of your instance
          schema:
            type: string
        - name: publishable_key
          in: query
          required: false
          description: The publishable key of your instance
          schema:
            type: string
      responses:
        "200":
          description: The interstitial page markup
        "400":
          description: A required query parameter is missing
  "/jwks":
    get:
      operationId: GetJWKS
      summary: Retrieve the JSON Web Key Set of the instance
      description: Retrieve the JSON Web Key Set of the instance
      tags:
        - JWKS
      responses:
        "200":
          description: The JSON Web Key Set
  "/clients":
    get:
      operationId: GetClientList
      tags:
        - Clients
      summary: List all clients
      description: |-
        Returns a list of all clients. The clients are returned sorted by creation date,
        with the newest clients appearing first.
      parameters:
        - "$ref": "#/components/parameters/LimitParameter"
        - "$ref": "#/components/parameters/OffsetParameter"
      responses:
        "200":
          "$ref": "#/components/responses/Client.List"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/clients/verify":
    post:
      operationId: VerifyClient
      tags:
        - Clients
      summary: Verify a client
      description: Verifies the client in the provided token
      requestBody:
        description: Parameters.
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                token:
                  type: string
                  description: A JWT Token that represents the active client.
      responses:
        "200":
          "$ref": "#/components/responses/Client"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
  "/clients/{client_id}":
    get:
      operationId: GetClient
      tags:
        - Clients
      summary: Get a client
      description: Returns the details of a client.
      parameters:
        - name: client_id
          in: path
          description: Client ID.
          required: true
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/Client"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
  "/clients/{client_id}/last_active_session":
    get:
      operationId: GetClientLastActiveSession
      tags:
        - Clients
      summary: Get the last active session of a client
      description: Returns the details of the last active session of a client.
      parameters:
        - name: client_id
          in: path
          description: Client ID.
          required: true
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/Session"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
  "/email_addresses":
    post:
      operationId: CreateEmailAddress
      tags:
        - Email Addresses
      summary: Create an email address
      description: Create a new email address
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  description: The ID representing the user
                email_address:
                  type: string
                  description:
                    The new email address. Must adhere to the RFC 5322
                    specification for email address format.
                verified:
                  type: boolean
                  description: When created, the email address will be marked as verified.
                  nullable: true
                primary:
                  type: boolean
                  description: |-
                    Create this email address as the primary email address for the user.
                    Default: false, unless it is the first email address.
                  nullable: true
      responses:
        "200":
          "$ref": "#/components/responses/EmailAddress"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/email_addresses/{email_address_id}":
    get:
      operationId: GetEmailAddress
      tags:
        - Email Addresses
      summary: Retrieve an email address
      description: Returns the details of an email address.
      parameters:
        - name: email_address_id
          in: path
          description: The ID of the email address to retrieve
          required: true
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/EmailAddress"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
    delete:
      operationId: DeleteEmailAddress
      tags:
        - Email Addresses
      summary: Delete an email address
      description: Delete the email address with the given ID
      parameters:
        - name: email_address_id
          in: path
          description: The ID of the email address to delete
          required: true
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/DeletedObject"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
    patch:
      operationId: UpdateEmailAddress
      tags:
        - Email Addresses
      summary: Update an email address
      description: Updates an email address.
      parameters:
        - name: email_address_id
          in: path
          description: The ID of the email address to update
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                verified:
                  type: boolean
                  description: The email address will be marked as verified.
                  nullable: true
                primary:
                  type: boolean
                  description:
                    Set this email address as the primary email address
                    for the user.
                  nullable: true
      responses:
        "200":
          "$ref": "#/components/responses/EmailAddress"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
  "/phone_numbers":
    post:
      operationId: CreatePhoneNumber
      tags:
        - Phone Numbers
      summary: Create a phone number
      description: Create a new phone number
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  description: The ID representing the user
                phone_number:
                  type: string
                  description:
                    The new phone number. Must adhere to the E.164 standard
                    for phone number format.
                verified:
                  type: boolean
                  description: When created, the phone number will be marked as verified.
                  nullable: true
                primary:
                  type: boolean
                  description: |-
                    Create this phone number as the primary phone number for the user.
                    Default: false, unless it is the first phone number.
                  nullable: true
      responses:
        "200":
          "$ref": "#/components/responses/PhoneNumber"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/phone_numbers/{phone_number_id}":
    get:
      operationId: GetPhoneNumber
      tags:
        - Phone Numbers
      summary: Retrieve a phone number
      description: Returns the details of a phone number
      parameters:
        - name: phone_number_id
          in: path
          description: The ID of the phone number to retrieve
          required: true
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/PhoneNumber"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
    delete:
      operationId: DeletePhoneNumber
      tags:
        - Phone Numbers
      summary: Delete a phone number
      description: Delete the phone number with the given ID
      parameters:
        - name: phone_number_id
          in: path
          description: The ID of the phone number to delete
          required: true
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/DeletedObject"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
    patch:
      operationId: UpdatePhoneNumber
      tags:
        - Phone Numbers
      summary: Update a phone number
      description: Updates a phone number
      parameters:
        - name: phone_number_id
          in: path
          description: The ID of the phone number to update
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                verified:
                  type: boolean
                  description: The phone number will be marked as verified.
                  nullable: true
                primary:
                  type: boolean
                  description:
                    Set this phone number as the primary phone number for
                    the user.
                  nullable: true
      responses:
        "200":
          "$ref": "#/components/responses/PhoneNumber"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
  "/sessions":
    get:
      operationId: GetSessionList
      tags:
        - Sessions
      summary: List all sessions
      description: |-
        Returns a list of all sessions.
        The sessions are returned sorted by creation date, with the newest sessions appearing first.
      parameters:
        - name: client_id
          in: query
          required: false
          description: List sessions for the given client
          schema:
            type: string
        - name: user_id
          in: query
          required: false
          description: List sessions for the given user
          schema:
            type: string
        - name: status
          in: query
          required: false
          description: Filter sessions by the provided status
          schema:
            type: string
            enum:
              - abandoned
              - active
              - ended
              - expired
              - removed
              - replaced
              - revoked
        - "$ref": "#/components/parameters/LimitParameter"
        - "$ref": "#/components/parameters/OffsetParameter"
      responses:
        "200":
          "$ref": "#/components/responses/Session.List"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/sessions/{session_id}":
    get:
      operationId: GetSession
      tags:
        - Sessions
      summary: Retrieve a session
      description: Retrieve the details of a session
      parameters:
        - name: session_id
          in: path
          description: The ID of the session
          required: true
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/Session"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
  "/sessions/{session_id}/revoke":
    post:
      operationId: RevokeSession
      tags:
        - Sessions
      summary: Revoke a session
      description: |-
        Sets the status of a session as "revoked", which is an unauthenticated state.
        In multi-session mode, a revoked session will still be returned along with its client object, however the user will need to sign in again.
      parameters:
        - name: session_id
          in: path
          description: The ID of the session
          required: true
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/Session"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
  "/sessions/{session_id}/verify":
    post:
      operationId: VerifySession
      tags:
        - Sessions
      summary: Verify a session
      description:
        Returns the session if it is authenticated, otherwise returns an
        error.
      parameters:
        - name: session_id
          in: path
          description: The ID of the session
          required: true
          schema:
            type: string
      requestBody:
        description: Parameters.
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                token:
                  type: string
                  description: |-
                    The JWT that is sent via the `__session` cookie from your frontend.
                    Note: this JWT must be associated with the supplied session ID.
      responses:
        "200":
          "$ref": "#/components/responses/Session"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
  "/sessions/{session_id}/tokens/{template_name}":
    post:
      operationId: CreateSessionTokenFromTemplate
      tags:
        - Sessions
      summary: Create a session token from a jwt template
      description:
        Creates a JSON Web Token(JWT) based on a session and a JWT Template
        name defined for your instance
      parameters:
        - name: session_id
          in: path
          description: The ID of the session
          required: true
          schema:
            type: string
        - name: template_name
          in: path
          description: The name of the JWT Template defined in your instance (e.g. `custom_hasura`).
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                      - token
                  jwt:
                    type: string
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
  "/templates/{template_type}":
    get:
      operationId: GetTemplateList
      summary: List all templates
      description: |-
        Returns a list of all templates.
        The templates are returned sorted by position.
      tags:
        - Email & SMS Templates
      parameters:
        - name: template_type
          in: path
          description: The type of templates to list (email or SMS)
          required: true
          schema:
            type: string
            enum:
              - email
              - sms
      responses:
        "200":
          "$ref": "#/components/responses/Template.List"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/templates/{template_type}/{slug}":
    get:
      operationId: GetTemplate
      summary: Retrieve a template
      description: Returns the details of a template
      tags:
        - Email & SMS Templates
      parameters:
        - name: template_type
          in: path
          description: The type of templates to retrieve (email or SMS)
          required: true
          schema:
            type: string
            enum:
              - email
              - sms
        - name: slug
          in: path
          description: The slug (i.e. machine-friendly name) of the template to retrieve
          required: true
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/Template"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
    put:
      operationId: UpsertTemplate
      summary: Update a template for a given type and slug
      description: Updates the existing template of the given type and slug
      tags:
        - Email & SMS Templates
      parameters:
        - name: template_type
          in: path
          description: The type of template to update
          required: true
          schema:
            type: string
            enum:
              - email
              - sms
        - name: slug
          in: path
          description: The slug of the template to update
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                  description: The user-friendly name of the template
                subject:
                  type: string
                  description: |-
                    The email subject.
                    Applicable only to email templates.
                  nullable: true
                markup:
                  type: string
                  description:
                    The editor markup used to generate the body of the
                    template
                  nullable: true
                body:
                  type: string
                  description: The template body before variable interpolation
                delivered_by_clerk:
                  type: boolean
                  description:
                    Whether Clerk should deliver emails or SMS messages
                    based on the current template
                  nullable: true
                from_email_name:
                  type: string
                  description: |-
                    The local part of the From email address that will be used for emails.
                    For example, in the address 'hello@example.com', the local part is 'hello'.
                    Applicable only to email templates.
      responses:
        "200":
          "$ref": "#/components/responses/Template"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "402":
          "$ref": "#/components/responses/PaymentRequired"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/templates/{template_type}/{slug}/revert":
    post:
      operationId: RevertTemplate
      summary: Revert a template
      description: Reverts an updated template to its default state
      tags:
        - Email & SMS Templates
      parameters:
        - name: template_type
          in: path
          description: The type of template to revert
          required: true
          schema:
            type: string
            enum:
              - email
              - sms
        - name: slug
          in: path
          description: The slug of the template to revert
          required: true
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/Template"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "402":
          "$ref": "#/components/responses/PaymentRequired"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
  "/templates/{template_type}/{slug}/preview":
    post:
      operationId: PreviewTemplate
      summary: Preview changes to a template
      description:
        Returns a preview of a template for a given template_type, slug
        and body
      tags:
        - Email & SMS Templates
      parameters:
        - name: template_type
          in: path
          description: The type of template to preview
          required: true
          schema:
            type: string
        - name: slug
          in: path
          description: The slug of the template to preview
          required: true
          schema:
            type: string
      requestBody:
        description: Required parameters
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                subject:
                  type: string
                  description: |-
                    The email subject.
                    Applicable only to email templates.
                  nullable: true
                body:
                  type: string
                  description: The template body before variable interpolation
                from_email_name:
                  type: string
                  description: |-
                    The local part of the From email address that will be used for emails.
                    For example, in the address 'hello@example.com', the local part is 'hello'.
                    Applicable only to email templates.
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/users":
    get:
      operationId: GetUserList
      summary: List all users
      description: |-
        Returns a list of all users.
        The users are returned sorted by creation date, with the newest users appearing first.
      tags:
        - Users
      parameters:
        - name: email_address
          in: query
          schema:
            type: array
            items:
              type: string
          description: |-
            Returns users with the specified email addresses.
            Accepts up to 100 email addresses.
            Any email addresses not found are ignored.
          required: false
        - name: phone_number
          in: query
          schema:
            type: array
            items:
              type: string
          description: |-
            Returns users with the specified phone numbers.
            Accepts up to 100 phone numbers.
            Any phone numbers not found are ignored.
          required: false
        - name: external_id
          in: query
          schema:
            type: array
            items:
              type: string
          description: |-
            Returns users with the specified external ids.
            For each external id, the `+` and `-` can be
            prepended to the id, which denote whether the
            respective external id should be included or
            excluded from the result set.
            Accepts up to 100 external ids.
            Any external ids not found are ignored.
          required: false
        - name: username
          in: query
          schema:
            type: array
            items:
              type: string
          description: |-
            Returns users with the specified usernames.
            Accepts up to 100 usernames.
            Any usernames not found are ignored.
          required: false
        - name: web3_wallet
          in: query
          schema:
            type: array
            items:
              type: string
          description: |-
            Returns users with the specified web3 wallet addresses.
            Accepts up to 100 web3 wallet addresses.
            Any web3 wallet addressed not found are ignored.
          required: false
        - name: user_id
          in: query
          schema:
            type: array
            items:
              type: string
          description: |-
            Returns users with the user ids specified.
            For each user id, the `+` and `-` can be
            prepended to the id, which denote whether the
            respective user id should be included or
            excluded from the result set.
            Accepts up to 100 user ids.
            Any user ids not found are ignored.
          required: false
        - name: organization_id
          in: query
          schema:
            type: array
            items:
              type: string
          description: |-
            Returns users that have memberships to the
            given organizations.
            For each organization id, the `+` and `-` can be
            prepended to the id, which denote whether the
            respective organization should be included or
            excluded from the result set.
            Accepts up to 100 organization ids.
          required: false
        - name: query
          in: query
          description: |-
            Returns users that match the given query.
            For possible matches, we check the email addresses, phone numbers, usernames, web3 wallets, user ids, first and last names.
            The query value doesn't need to match the exact value you are looking for, it is capable of partial matches as well.
          schema:
            type: string
          required: false
        - "$ref": "#/components/parameters/LimitParameter"
        - "$ref": "#/components/parameters/OffsetParameter"
        - name: order_by
          in: query
          description: |-
            Allows to return users in a particular order.
            At the moment, you can order the returned users either by their `created_at` or `updated_at` timestamp.
            In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by.
            For example, if you want users to be returned in descending order according to their `created_at` property, you can use `-created_at`.
            If you don't use `+` or `-`, then `+` is implied.
            Defaults to `-created_at`.
          schema:
            type: string
            default: "-created_at"
          required: false
      responses:
        "200":
          "$ref": "#/components/responses/User.List"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
    post:
      operationId: CreateUser
      summary: Create a new user
      description: |-
        Creates a new user. Your user management settings determine how you should setup your user model.

        Any email address and phone number created using this method will be marked as verified.

        Note: If you are performing a migration, check out our guide on [zero downtime migrations](https://clerk.com/docs/deployments/import-users).

        A rate limit rule of 20 requests per 10 seconds is applied to this endpoint.
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                external_id:
                  type: string
                  description: |-
                    The ID of the user as used in your external systems or your previous authentication solution.
                    Must be unique across your instance.
                  nullable: true
                first_name:
                  type: string
                  description: The first name to assign to the user
                  nullable: true
                last_name:
                  type: string
                  description: The last name to assign to the user
                  nullable: true
                email_address:
                  type: array
                  items:
                    type: string
                  description: |-
                    Email addresses to add to the user.
                    Must be unique across your instance.
                    The first email address will be set as the user's primary email address.
                phone_number:
                  type: array
                  items:
                    type: string
                  description: |-
                    Phone numbers to add to the user.
                    Must be unique across your instance.
                    The first phone number will be set as the user's primary phone number.
                web3_wallet:
                  type: array
                  items:
                    type: string
                  description: |-
                    Web3 wallets to add to the user.
                    Must be unique across your instance.
                    The first wallet will be set as the user's primary wallet.
                username:
                  type: string
                  description: |-
                    The username to give to the user.
                    It must be unique across your instance.
                  nullable: true
                password:
                  type: string
                  description: |-
                    The plaintext password to give the user.
                    Must be at least 8 characters long, and can not be in any list of hacked passwords.
                  nullable: true
                password_digest:
                  type: string
                  description: |-
                    In case you already have the password digests and not the passwords, you can use them for the newly created user via this property.
                    The digests should be generated with one of the supported algorithms.
                    The hashing algorithm can be specified using the `password_hasher` property.
                password_hasher:
                  type: string
                  description: |-
                    The hashing algorithm that was used to generate the password digest.
                    The algorithms we support at the moment are [bcrypt](https://en.wikipedia.org/wiki/Bcrypt), md5, pbkdf2_sha256, [pbkdf2_sha256_django](https://docs.djangoproject.com/en/4.0/topics/auth/passwords/), [scrypt_firebase](https://firebaseopensource.com/projects/firebase/scrypt/) and 2 [argon2](https://argon2.online/) variants, argon2i and argon2id.
                    Each of the above expects the incoming digest to be of a particular format.

                    More specifically:

                    **bcrypt:** The digest should be of the following form:

                    `$<algorithm version>$<cost>$<salt & hash>`

                    **md5:** The digest should follow the regular form e.g.:

                    `5f4dcc3b5aa765d61d8327deb882cf99`

                    **pbkdf2_sha256:** This is the PBKDF2 algorithm using the SHA256 hashing function. The format should be as follows:

                    `pbkdf2_sha256$<iterations>$<salt>$<hash>`

                    Note: Both the salt and the hash are expected to be base64-encoded.

                    **pbkdf2_sha256_django:** This is the Django-specific variant of PBKDF2 and the digest should have the following format (as exported from Django):

                    `pbkdf2_sha256$<iterations>$<salt>$<hash>`

                    Note: The salt is expected to be un-encoded, the hash is expected base64-encoded.

                    **pbkdf2_sha1:** This is similar to pkbdf2_sha256_django, but with two differences:
                    1. uses sha1 instead of sha256
                    2. accepts the hash as a hex-encoded string

                    The format is the following:

                    `pbkdf2_sha1$<iterations>$<salt>$<hash-as-hex-string>`


                    **scrypt_firebase:** The Firebase-specific variant of scrypt.
                    The value is expected to have 6 segments separated by the $ character and include the following information:

                    _hash:_ The actual Base64 hash. This can be retrieved when exporting the user from Firebase.
                    _salt:_ The salt used to generate the above hash. Again, this is given when exporting the user.
                    _signer key:_ The base64 encoded signer key.
                    _salt separator:_ The base64 encoded salt separator.
                    _rounds:_ The number of rounds the algorithm needs to run.
                    _memory cost:_ The cost of the algorithm run

                    The first 2 (hash and salt) are per user and can be retrieved when exporting the user from Firebase.
                    The other 4 values (signer key, salt separator, rounds and memory cost) are project-wide settings and can be retrieved from the project's password hash parameters.

                    Once you have all these, you can combine it in the following format and send this as the digest in order for Clerk to accept it:

                    `<hash>$<salt>$<signer key>$<salt separator>$<rounds>$<memory cost>`

                    **argon2i:** Algorithms in the argon2 family generate digests that encode the following information:

                    _version (v):_ The argon version, version 19 is assumed
                    _memory (m):_ The memory used by the algorithm (in kibibytes)
                    _iterations (t):_ The number of iterations to perform
                    _parallelism (p):_ The number of threads to use

                    Parts are demarcated by the `$` character, with the first part identifying the algorithm variant.
                    The middle part is a comma-separated list of the encoding options (memory, iterations, parallelism).
                    The final part is the actual digest.

                    `$argon2i$v=19$m=4096,t=3,p=1$4t6CL3P7YiHBtwESXawI8Hm20zJj4cs7/4/G3c187e0$m7RQFczcKr5bIR0IIxbpO2P0tyrLjf3eUW3M3QSwnLc`

                    **argon2id:** See the previous algorithm for an explanation of the formatting.

                    For the argon2id case, the value of the algorithm in the first part of the digest is `argon2id`:

                    `$argon2id$v=19$m=64,t=4,p=8$Z2liZXJyaXNo$iGXEpMBTDYQ8G/71tF0qGjxRHEmR3gpGULcE93zUJVU`

                    If you need support for any particular hashing algorithm, [please let us know](https://clerk.com/support).
                  enum:
                    - bcrypt
                    - md5
                    - pbkdf2_sha256
                    - pbkdf2_sha256_django
                    - pbkdf2_sha1
                    - scrypt_firebase
                    - argon2i
                    - argon2id
                skip_password_checks:
                  type: boolean
                  description: |-
                    When set to `true` all password checks are skipped.
                    It is recommended to use this method only when migrating plaintext passwords to Clerk.
                    Upon migration the user base should be prompted to pick stronger password.
                skip_password_requirement:
                  type: boolean
                  description: |-
                    When set to `true`, `password` is not required anymore when creating the user and can be omitted.
                    This is useful when you are trying to create a user that doesn't have a password, in an instance that is using passwords.
                    Please note that you cannot use this flag if password is the only way for a user to sign into your instance.
                totp_secret:
                  type: string
                  description: |-
                    In case TOTP is configured on the instance, you can provide the secret to enable it on the newly created user without the need to reset it.
                    Please note that currently the supported options are:
                    * Period: 30 seconds
                    * Code length: 6 digits
                    * Algorithm: SHA1
                backup_codes:
                  type: array
                  items:
                    type: string
                  description: |-
                    If Backup Codes are configured on the instance, you can provide them to enable it on the newly created user without the need to reset them.
                    You must provide the backup codes in plain format or the corresponding bcrypt digest.
                public_metadata:
                  type: object
                  description:
                    Metadata saved on the user, that is visible to both
                    your Frontend and Backend APIs
                private_metadata:
                  type: object
                  description:
                    Metadata saved on the user, that is only visible to
                    your Backend API
                unsafe_metadata:
                  type: object
                  description: |-
                    Metadata saved on the user, that can be updated from both the Frontend and Backend APIs.
                    Note: Since this data can be modified from the frontend, it is not guaranteed to be safe.
                created_at:
                  type: string
                  description:
                    A custom date/time denoting _when_ the user signed
                    up to the application, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`).
      responses:
        "200":
          "$ref": "#/components/responses/User"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/users/count":
    get:
      operationId: GetUsersCount
      summary: Count users
      description:
        Returns a total count of all users that match the given filtering
        criteria.
      tags:
        - Users
      parameters:
        - name: email_address
          in: query
          schema:
            type: array
            items:
              type: string
          description: |-
            Counts users with the specified email addresses.
            Accepts up to 100 email addresses.
            Any email addresses not found are ignored.
          required: false
        - name: phone_number
          in: query
          schema:
            type: array
            items:
              type: string
          description: |-
            Counts users with the specified phone numbers.
            Accepts up to 100 phone numbers.
            Any phone numbers not found are ignored.
          required: false
        - name: external_id
          in: query
          schema:
            type: array
            items:
              type: string
          description: |-
            Counts users with the specified external ids.
            Accepts up to 100 external ids.
            Any external ids not found are ignored.
          required: false
        - name: username
          in: query
          schema:
            type: array
            items:
              type: string
          description: |-
            Counts users with the specified usernames.
            Accepts up to 100 usernames.
            Any usernames not found are ignored.
          required: false
        - name: web3_wallet
          in: query
          schema:
            type: array
            items:
              type: string
          description: |-
            Counts users with the specified web3 wallet addresses.
            Accepts up to 100 web3 wallet addresses.
            Any web3 wallet addressed not found are ignored.
          required: false
        - name: user_id
          in: query
          schema:
            type: array
            items:
              type: string
          description: |-
            Counts users with the user ids specified.
            Accepts up to 100 user ids.
            Any user ids not found are ignored.
          required: false
        - name: query
          in: query
          description: |-
            Counts users that match the given query.
            For possible matches, we check the email addresses, phone numbers, usernames, web3 wallets, user ids, first and last names.
            The query value doesn't need to match the exact value you are looking for, it is capable of partial matches as well.
          schema:
            type: string
          required: false
      responses:
        "200":
          "$ref": "#/components/responses/User.Count"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/users/{user_id}":
    get:
      operationId: GetUser
      summary: Retrieve a user
      description: Retrieve the details of a user
      tags:
        - Users
      parameters:
        - name: user_id
          in: path
          description: The ID of the user to retrieve
          required: true
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/User"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
    patch:
      operationId: UpdateUser
      summary: Update a user
      description: |-
        Update a user's attributes.

        You can set the user's primary contact identifiers (email address and phone numbers) by updating the `primary_email_address_id` and `primary_phone_number_id` attributes respectively.
        Both IDs should correspond to verified identifications that belong to the user.

        You can remove a user's username by setting the username attribute to null or the blank string "".
        This is a destructive action; the identification will be deleted forever.
        Usernames can be removed only if they are optional in your instance settings and there's at least one other identifier which can be used for authentication.
      tags:
        - Users
      parameters:
        - name: user_id
          in: path
          description: The ID of the user to update
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                external_id:
                  type: string
                  description: |-
                    The ID of the user as used in your external systems or your previous authentication solution.
                    Must be unique across your instance.
                  nullable: true
                first_name:
                  type: string
                  description: The first name to assign to the user
                  nullable: true
                last_name:
                  type: string
                  description: The last name to assign to the user
                  nullable: true
                primary_email_address_id:
                  type: string
                  description: |-
                    The ID of the email address to set as primary.
                    It must be verified, and present on the current user.
                primary_phone_number_id:
                  type: string
                  description: |-
                    The ID of the phone number to set as primary.
                    It must be verified, and present on the current user.
                primary_web3_wallet_id:
                  type: string
                  description: |-
                    The ID of the web3 wallets to set as primary.
                    It must be verified, and present on the current user.
                username:
                  type: string
                  description: |-
                    The username to give to the user.
                    It must be unique across your instance.
                  nullable: true
                profile_image_id:
                  type: string
                  description: The ID of the image to set as the user's profile image
                  nullable: true
                password:
                  type: string
                  description: |-
                    The plaintext password to give the user.
                    Must be at least 8 characters long, and can not be in any list of hacked passwords.
                  nullable: true
                totp_secret:
                  type: string
                  description: |-
                    In case TOTP is configured on the instance, you can provide the secret to enable it on the specific user without the need to reset it.
                    Please note that currently the supported options are:
                    * Period: 30 seconds
                    * Code length: 6 digits
                    * Algorithm: SHA1
                backup_codes:
                  type: array
                  items:
                    type: string
                  description: |-
                    If Backup Codes are configured on the instance, you can provide them to enable it on the specific user without the need to reset them.
                    You must provide the backup codes in plain format or the corresponding bcrypt digest.
                public_metadata:
                  type: object
                  description:
                    Metadata saved on the user, that is visible to both
                    your Frontend and Backend APIs
                private_metadata:
                  type: object
                  description:
                    Metadata saved on the user, that is only visible to
                    your Backend API
                unsafe_metadata:
                  type: object
                  description: |-
                    Metadata saved on the user, that can be updated from both the Frontend and Backend APIs.
                    Note: Since this data can be modified from the frontend, it is not guaranteed to be safe.
                created_at:
                  type: string
                  description:
                    A custom date/time denoting _when_ the user signed
                    up to the application, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`).
      responses:
        "200":
          "$ref": "#/components/responses/User"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
    delete:
      operationId: DeleteUser
      summary: Delete a user
      description: Delete the specified user
      tags:
        - Users
      parameters:
        - name: user_id
          in: path
          description: The ID of the user to delete
          required: true
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/DeletedObject"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
  "/users/{user_id}/ban":
    post:
      operationId: BanUser
      summary: Ban a user
      description:
        Marks the given user as banned, which means that all their sessions
        are revoked and they are not allowed to sign in again.
      tags:
        - Users
      parameters:
        - name: user_id
          in: path
          description: The ID of the user to ban
          required: true
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/User"
        "402":
          "$ref": "#/components/responses/PaymentRequired"
  "/users/{user_id}/unban":
    post:
      operationId: UnbanUser
      summary: Unban a user
      description: Removes the ban mark from the given user.
      tags:
        - Users
      parameters:
        - name: user_id
          in: path
          description: The ID of the user to unban
          required: true
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/User"
        "402":
          "$ref": "#/components/responses/PaymentRequired"
  "/users/{user_id}/metadata":
    patch:
      operationId: UpdateUserMetadata
      summary: Merge and update a user's metadata
      description: |-
        Update a user's metadata attributes by merging existing values with the provided parameters.

        This endpoint behaves differently than the *Update a user* endpoint.
        Metadata values will not be replaced entirely.
        Instead, a deep merge will be performed.
        Deep means that any nested JSON objects will be merged as well.

        You can remove metadata keys at any level by setting their value to `null`.
      tags:
        - Users
      parameters:
        - name: user_id
          in: path
          description: The ID of the user whose metadata will be updated and merged
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                public_metadata:
                  type: object
                  description: |-
                    Metadata saved on the user, that is visible to both your frontend and backend.
                    The new object will be merged with the existing value.
                private_metadata:
                  type: object
                  description: |-
                    Metadata saved on the user that is only visible to your backend.
                    The new object will be merged with the existing value.
                unsafe_metadata:
                  type: object
                  description: |-
                    Metadata saved on the user, that can be updated from both the Frontend and Backend APIs.
                    The new object will be merged with the existing value.

                    Note: Since this data can be modified from the frontend, it is not guaranteed to be safe.
      responses:
        "200":
          "$ref": "#/components/responses/User"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/users/{user_id}/oauth_access_tokens/{provider}":
    get:
      operationId: GetOAuthAccessToken
      summary: Retrieve the OAuth access token of a user
      description: |-
        Fetch the corresponding OAuth access token for a user that has previously authenticated with a particular OAuth provider.
        For OAuth 2.0, if the access token has expired and we have a corresponding refresh token, the access token will be refreshed transparently the new one will be returned.
      tags:
        - Users
      parameters:
        - name: user_id
          in: path
          description: The ID of the user for which to retrieve the OAuth access token
          required: true
          schema:
            type: string
        - name: provider
          in: path
          description: The ID of the OAuth provider (e.g. `oauth_google`)
          required: true
          schema:
            type: string
      responses:
        "200":
          description: The OAuth access token of the user, if any.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: false
                  properties:
                    object:
                      type: string
                    token:
                      type: string
                      description: The access token
                    provider:
                      type: string
                      description: The ID of the provider
                    public_metadata:
                      type: object
                    label:
                      type: string
                      nullable: true
                    scopes:
                      type: array
                      items:
                        type: string
                      description: |-
                        The list of scopes that the token is valid for.
                        Only present for OAuth 2.0 tokens.
                    token_secret:
                      type: string
                      description: The token secret. Only present for OAuth 1.0 tokens.
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/users/{user_id}/organization_memberships":
    get:
      operationId: UsersGetOrganizationMemberships
      summary: Retrieve all memberships for a user
      description: Retrieve a paginated list of the user's organization memberships
      tags:
        - Users
      parameters:
        - name: user_id
          in: path
          description:
            The ID of the user whose organization memberships we want to
            retrieve
          required: true
          schema:
            type: string
        - "$ref": "#/components/parameters/LimitParameter"
        - "$ref": "#/components/parameters/OffsetParameter"
      responses:
        "200":
          "$ref": "#/components/responses/OrganizationMemberships"
        "403":
          "$ref": "#/components/responses/ClerkErrors"
  "/users/{user_id}/verify_password":
    post:
      operationId: VerifyPassword
      summary: Verify the password of a user
      description: |-
        Check that the user's password matches the supplied input.
        Useful for custom auth flows and re-verification.
      tags:
        - Users
      parameters:
        - name: user_id
          in: path
          description: The ID of the user for whom to verify the password
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                password:
                  type: string
                  description: The user password to verify
              required:
                - password
      responses:
        "200":
          description: The provided password was correct.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  verified:
                    type: boolean
                    nullable: false
        "400":
          description: The user does not have a password set.
        "404":
          description: The user does not exist.
        "422":
          description: The provided password was incorrect.
        "500":
          "$ref": "#/components/responses/ClerkErrors"
  "/users/{user_id}/verify_totp":
    post:
      operationId: VerifyTOTP
      summary: Verify a TOTP or backup code for a user
      description: |-
        Verify that the provided TOTP or backup code is valid for the user.
        Verifying a backup code will result it in being consumed (i.e. it will
        become invalid).
        Useful for custom auth flows and re-verification.
      tags:
        - Users
      parameters:
        - name: user_id
          in: path
          description: The ID of the user for whom to verify the TOTP
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                code:
                  type: string
                  description: The TOTP or backup code to verify
              required:
                - code
      responses:
        "200":
          description: The provided TOTP or backup code was correct.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  verified:
                    type: boolean
                    nullable: false
                  code_type:
                    type: string
                    nullable: false
                    enum:
                      - totp
                      - backup_code
        "400":
          description: The user does not have TOTP configured for their account.
        "404":
          description: The user does not exist.
        "422":
          description: The provided TOTP or backup code was incorrect.
        "500":
          "$ref": "#/components/responses/ClerkErrors"
  "/users/{user_id}/mfa":
    delete:
      operationId: DisableMFA
      summary: Disable a user's MFA methods
      description:
        Disable all of a user's MFA methods (e.g. OTP sent via SMS, TOTP
        on their authenticator app) at once.
      tags:
        - Users
      parameters:
        - name: user_id
          in: path
          description: The ID of the user whose MFA methods are to be disabled
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Successful operation.
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  user_id:
                    type: string
                    nullable: false
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
        "500":
          "$ref": "#/components/responses/ClerkErrors"
  "/emails":
    post:
      operationId: CreateEmail
      summary: Create an email
      description: Create and send an email to the supplied email address ID.
      tags:
        - Emails
      requestBody:
        description: Required parameters
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                from_email_name:
                  type: string
                  description: |-
                    The email name portion of the sending email address.
                    <br/>e.g.: `from_email_name=info` will send from info@example.com
                subject:
                  type: string
                  description: The subject of the email.
                  nullable: true
                body:
                  type: string
                  description: The body of the email.
                  nullable: true
                email_address_id:
                  type: string
                  nullable: true
                  description: The ID of the email address to send to.
                template_slug:
                  type: string
                  nullable: true
                  description: The slug of the template to use for sending this email
      responses:
        "200":
          "$ref": "#/components/responses/Email"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/sms_messages":
    post:
      operationId: CreateSMSMessage
      summary: Create an SMS message
      description: Create and send an SMS message to the supplied phone number ID
      tags:
        - SMS Messages
      requestBody:
        description: Required parameters
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                message:
                  type: string
                  description: The message you would like to send
                  nullable: true
                phone_number_id:
                  type: string
                  description:
                    The ID of a verified phone number the SMS message should
                    be sent to
      responses:
        "200":
          "$ref": "#/components/responses/SMSMessage"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
  "/invitations":
    post:
      operationId: CreateInvitation
      summary: Create an invitation
      description: |-
        Creates a new invitation for the given email address and sends the invitation email.
        Keep in mind that you cannot create an invitation if there is already one for the given email address.
        Also, trying to create an invitation for an email address that already exists in your application will result to an error.
      tags:
        - Invitations
      requestBody:
        description: Required parameters
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                email_address:
                  type: string
                  description: The email address the invitation will be sent to
                public_metadata:
                  type: object
                  description: |-
                    Metadata that will be attached to the newly created invitation.
                    The value of this property should be a well-formed JSON object.
                    Once the user accepts the invitation and signs up, these metadata will end up in the user's public metadata.
                redirect_url:
                  type: string
                  description: |-
                    Optional URL which specifies where to redirect the user once they click the invitation link.
                    This is only required if you have implemented a [custom flow](https://clerk.com/docs/authentication/invitations#custom-flow) and you're not using Clerk Hosted Pages or Clerk Components.
              required:
                - email_address
      responses:
        "200":
          "$ref": "#/components/responses/Invitation"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
    get:
      summary: List all invitations
      description:
        Returns all non-revoked invitations for your application, sorted
        by creation date
      operationId: ListInvitations
      parameters:
        - in: query
          name: status
          description: Filter invitations based on their status
          required: false
          schema:
            type: string
            enum:
              - pending
              - accepted
              - revoked
      tags:
        - Invitations
      responses:
        "200":
          "$ref": "#/components/responses/Invitation.List"
  "/invitations/{invitation_id}/revoke":
    post:
      operationId: RevokeInvitation
      summary: Revokes an invitation
      description: |-
        Revokes the given invitation.
        Revoking an invitation will prevent the user from using the invitation link that was sent to them.
        However, it doesn't prevent the user from signing up if they follow the sign up flow.
        Only active (i.e. non-revoked) invitations can be revoked.
      tags:
        - Invitations
      parameters:
        - name: invitation_id
          in: path
          description: The ID of the invitation to be revoked
          required: true
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/Invitation"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
  "/allowlist_identifiers":
    get:
      operationId: ListAllowlistIdentifiers
      summary: List all identifiers on the allow-list
      description: Get a list of all identifiers allowed to sign up to an instance
      tags:
        - Allow-list / Block-list
      responses:
        "200":
          "$ref": "#/components/responses/AllowlistIdentifier.List"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "402":
          "$ref": "#/components/responses/PaymentRequired"
    post:
      operationId: CreateAllowlistIdentifier
      summary: Add identifier to the allow-list
      description: Create an identifier allowed to sign up to an instance
      tags:
        - Allow-list / Block-list
      responses:
        "200":
          "$ref": "#/components/responses/AllowlistIdentifier"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "402":
          "$ref": "#/components/responses/PaymentRequired"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/allowlist_identifiers/{identifier_id}":
    delete:
      operationId: DeleteAllowlistIdentifier
      summary: Delete identifier from allow-list
      description: Delete an identifier from the instance allow-list
      tags:
        - Allow-list / Block-list
      parameters:
        - name: identifier_id
          in: path
          description: The ID of the identifier to delete from the allow-list
          required: true
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/DeletedObject"
        "402":
          "$ref": "#/components/responses/PaymentRequired"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
  "/blocklist_identifiers":
    get:
      operationId: ListBlocklistIdentifiers
      summary: List all identifiers on the block-list
      description:
        Get a list of all identifiers which are not allowed to access an
        instance
      tags:
        - Allow-list / Block-list
      responses:
        "200":
          "$ref": "#/components/responses/BlocklistIdentifier.List"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "402":
          "$ref": "#/components/responses/PaymentRequired"
    post:
      operationId: CreateBlocklistIdentifier
      summary: Add identifier to the block-list
      description: Create an identifier that is blocked from accessing an instance
      tags:
        - Allow-list / Block-list
      responses:
        "200":
          "$ref": "#/components/responses/BlocklistIdentifier"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "402":
          "$ref": "#/components/responses/PaymentRequired"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/blocklist_identifiers/{identifier_id}":
    delete:
      operationId: DeleteBlocklistIdentifier
      summary: Delete identifier from block-list
      description: Delete an identifier from the instance block-list
      tags:
        - Allow-list / Block-list
      parameters:
        - name: identifier_id
          in: path
          description: The ID of the identifier to delete from the block-list
          required: true
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/DeletedObject"
        "402":
          "$ref": "#/components/responses/PaymentRequired"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
  "/beta_features/instance_settings":
    patch:
      operationId: UpdateInstanceAuthConfig
      summary: Update instance settings
      description: Updates the settings of an instance
      tags:
        - Beta Features
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                restricted_to_allowlist:
                  type: boolean
                  description:
                    Whether sign up is restricted to email addresses, phone
                    numbers and usernames that are on the allowlist.
                  nullable: true
                  default: false
                from_email_address:
                  type: string
                  description: |-
                    The local part of the email address from which authentication-related emails (e.g. OTP code, magic links) will be sent.
                    Only alphanumeric values are allowed.
                    Note that this value should contain only the local part of the address (e.g. `foo` for `foo@example.com`).
                  nullable: true
                progressive_sign_up:
                  type: boolean
                  description:
                    Enable the Progressive Sign Up algorithm. Refer to
                    the [docs](https://clerk.com/docs/upgrade-guides/progressive-sign-up)
                    for more info.
                  nullable: true
                session_token_template:
                  type: string
                  description:
                    The name of the JWT Template used to augment your session
                    tokens. To disable this, pass an empty string.
                  nullable: true
                enhanced_email_deliverability:
                  type: boolean
                  description: |-
                    The "enhanced_email_deliverability" feature will send emails from "verifications@clerk.dev" instead of your domain.
                    This can be helpful if you do not have a high domain reputation.
                  nullable: true
                test_mode:
                  type: boolean
                  description: |-
                    Toggles test mode for this instance, allowing the use of test email addresses and phone numbers.
                    Defaults to true for development instances.
                  nullable: true
      responses:
        "200":
          "$ref": "#/components/responses/InstanceSettings"
        "402":
          "$ref": "#/components/responses/PaymentRequired"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/beta_features/domain":
    put:
      operationId: UpdateProductionInstanceDomain
      summary: Update production instance domain
      description: |-
        Change the domain of a production instance.

        Changing the domain requires updating the [DNS records](https://clerk.com/docs/deployments/overview#dns-records) accordingly, deploying new [SSL certificates](https://clerk.com/docs/deployments/overview#deploy), updating your Social Connection's redirect URLs and setting the new keys in your code.

        WARNING: Changing your domain will invalidate all current user sessions (i.e. users will be logged out). Also, while your application is being deployed, a small downtime is expected to occur.
      tags:
        - Beta Features
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                home_url:
                  type: string
                  description: The new home URL of the production instance e.g. https://www.example.com
      responses:
        "202":
          description: Accepted
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "422":
          "$ref": "#/components/responses/ClerkErrors"
  "/actor_tokens":
    post:
      summary: Create actor token
      description:
        Create an actor token that can be used to impersonate the given
        user.
      operationId: CreateActorToken
      tags:
        - Actor Tokens
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                user_id:
                  type: string
                  description:
                    The ID of the user that can use the newly created sign
                    in token.
                actor:
                  type: object
                  description: |-
                    The actor payload. It needs to include a sub property which should contain the ID of the actor.
                    This whole payload will be also included in the JWT session token.
                expires_in_seconds:
                  type: integer
                  description: |-
                    Optional parameter to specify the life duration of the actor token in seconds.
                    By default, the duration is 1 hour.
                  default: 3600
                session_max_duration_in_seconds:
                  type: integer
                  description: |-
                    The maximum duration that the session which will be created by the generated actor token should last.
                    By default, the duration of a session created via an actor token, lasts 30 minutes.
                  default: 1800
              required:
                - user_id
                - actor
      responses:
        "200":
          "$ref": "#/components/responses/ActorToken"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "402":
          "$ref": "#/components/responses/PaymentRequired"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/actor_tokens/{actor_token_id}/revoke":
    post:
      summary: Revoke actor token
      description: Revokes a pending actor token.
      operationId: RevokeActorToken
      tags:
        - Actor Tokens
      parameters:
        - name: actor_token_id
          in: path
          description: The ID of the actor token to be revoked.
          required: true
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/ActorToken"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
  "/instance":
    patch:
      operationId: UpdateInstance
      summary: Update instance settings
      description: Updates the settings of an instance
      tags:
        - Instance Settings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                test_mode:
                  type: boolean
                  description: |-
                    Toggles test mode for this instance, allowing the use of test email addresses and phone numbers.
                    Defaults to true for development instances.
                  nullable: true
                hibp:
                  type: boolean
                  description:
                    Whether the instance should be using the HIBP service
                    to check passwords for breaches
                  nullable: true
                enhanced_email_deliverability:
                  type: boolean
                  description: |-
                    The "enhanced_email_deliverability" feature will send emails from "verifications@clerk.dev" instead of your domain.
                    This can be helpful if you do not have a high domain reputation.
                  nullable: true
                support_email:
                  type: string
                  nullable: true
                clerk_js_version:
                  type: string
                  nullable: true
                development_origin:
                  type: string
                  nullable: true
                experimental_allowed_origins:
                  type: array
                  items:
                    type: string
                  deprecated: true
                allowed_origins:
                  type: array
                  items:
                    type: string
                cookieless_dev:
                  type: boolean
                  description: |-
                    Whether the instance should operate in cookieless development mode (i.e. without third-party cookies).
                    Deprecated: Please use `url_based_session_syncing` instead.
                  deprecated: true
                url_based_session_syncing:
                  type: boolean
                  description:
                    Whether the instance should use URL-based session syncing
                    in development mode (i.e. without third-party cookies).
      responses:
        "204":
          description: Accepted
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/instance/restrictions":
    patch:
      operationId: UpdateInstanceRestrictions
      summary: Update instance restrictions
      description: Updates the restriction settings of an instance
      tags:
        - Instance Settings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                allowlist:
                  type: boolean
                  nullable: true
                blocklist:
                  type: boolean
                  nullable: true
      responses:
        "200":
          "$ref": "#/components/responses/InstanceRestrictions"
        "402":
          "$ref": "#/components/responses/PaymentRequired"
  "/instance/organization_settings":
    patch:
      operationId: UpdateInstanceOrganizationSettings
      summary: Update instance organization settings
      description: Updates the organization settings of the instance
      tags:
        - Instance Settings
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                enabled:
                  type: boolean
                  nullable: true
                max_allowed_memberships:
                  type: integer
                  nullable: true
      responses:
        "200":
          "$ref": "#/components/responses/OrganizationSettings"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/webhooks/svix":
    post:
      operationId: CreateSvixApp
      summary: Create a Svix app
      description: Create a Svix app and associate it with the current instance
      tags:
        - Webhooks
      responses:
        "200":
          "$ref": "#/components/responses/SvixURL"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
    delete:
      operationId: DeleteSvixApp
      summary: Delete a Svix app
      description: Delete a Svix app and disassociate it from the current instance
      tags:
        - Webhooks
      responses:
        "204":
          description: Svix app was successfully deleted
        "400":
          "$ref": "#/components/responses/ClerkErrors"
  "/webhooks/svix_url":
    post:
      operationId: GenerateSvixAuthURL
      summary: Create a Svix Dashboard URL
      description:
        Generate a new url for accessing the Svix's management dashboard
        for that particular instance
      tags:
        - Webhooks
      responses:
        "200":
          "$ref": "#/components/responses/SvixURL"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
  "/jwt_templates":
    get:
      summary: List all templates
      operationId: ListJWTTemplates
      tags:
        - JWT Templates
      responses:
        "200":
          "$ref": "#/components/responses/JWTTemplate.List"
    post:
      operationId: CreateJWTTemplate
      summary: Create a JWT template
      description: Create a new JWT template
      tags:
        - JWT Templates
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: JWT template name
                  nullable: false
                claims:
                  type: object
                  description: JWT template claims in JSON format
                  nullable: false
                lifetime:
                  type: number
                  minimum: 30
                  maximum: 315360000
                  description: JWT token lifetime
                  nullable: true
                allowed_clock_skew:
                  type: number
                  minimum: 0
                  maximum: 300
                  description: JWT token allowed clock skew
                  nullable: true
                custom_signing_key:
                  type: boolean
                  description:
                    Whether a custom signing key/algorithm is also provided
                    for this template
                  nullable: false
                signing_algorithm:
                  type: string
                  description: The custom signing algorithm to use when minting JWTs
                  nullable: true
                signing_key:
                  type: string
                  description:
                    The custom signing private key to use when minting
                    JWTs
                  nullable: true
      responses:
        "200":
          "$ref": "#/components/responses/JWTTemplate"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "402":
          "$ref": "#/components/responses/PaymentRequired"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/jwt_templates/{template_id}":
    get:
      operationId: GetJWTTemplate
      summary: Retrieve a template
      description: Retrieve the details of a given JWT template
      tags:
        - JWT Templates
      parameters:
        - name: template_id
          in: path
          description: JWT Template ID
          required: true
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/JWTTemplate"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
    patch:
      operationId: UpdateJWTTemplate
      summary: Update a JWT template
      description: Updates an existing JWT template
      tags:
        - JWT Templates
      parameters:
        - name: template_id
          in: path
          description: The ID of the JWT template to update
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: JWT template name
                  nullable: false
                claims:
                  type: object
                  description: JWT template claims in JSON format
                  nullable: false
                lifetime:
                  type: number
                  minimum: 30
                  maximum: 315360000
                  description: JWT token lifetime
                  nullable: true
                allowed_clock_skew:
                  type: number
                  minimum: 0
                  maximum: 300
                  description: JWT token allowed clock skew
                  nullable: true
                custom_signing_key:
                  type: boolean
                  description:
                    Whether a custom signing key/algorithm is also provided
                    for this template
                  nullable: false
                signing_algorithm:
                  type: string
                  description: The custom signing algorithm to use when minting JWTs
                  nullable: true
                signing_key:
                  type: string
                  description:
                    The custom signing private key to use when minting
                    JWTs
                  nullable: true
      responses:
        "200":
          "$ref": "#/components/responses/JWTTemplate"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "402":
          "$ref": "#/components/responses/PaymentRequired"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
    delete:
      operationId: DeleteJWTTemplate
      summary: Delete a Template
      description: ""
      tags:
        - JWT Templates
      parameters:
        - name: template_id
          in: path
          description: JWT Template ID
          required: true
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/DeletedObject"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
  "/organizations":
    get:
      operationId: ListOrganizations
      summary: Get a list of organizations for an instance
      description: |-
        This request returns the list of organizations for an instance.
        Results can be paginated using the optional `limit` and `offset` query parameters.
        The organizations are ordered by descending creation date.
        Most recent organizations will be returned first.
      tags:
        - Organizations
      parameters:
        - "$ref": "#/components/parameters/LimitParameter"
        - "$ref": "#/components/parameters/OffsetParameter"
        - in: query
          required: false
          name: include_members_count
          description:
            Flag to denote whether the member counts of each organization
            should be included in the response or not.
          schema:
            type: boolean
        - in: query
          required: false
          name: query
          description: |-
            Returns organizations with ID, name, or slug that match the given query.
            Uses exact match for organization ID and partial match for name and slug.
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/Organizations"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
    post:
      operationId: CreateOrganization
      summary: Create an organization
      description: |-
        Creates a new organization with the given name for an instance.
        In order to successfully create an organization you need to provide the ID of the User who will become the organization administrator.
        You can specify an optional slug for the new organization.
        If provided, the organization slug can contain only lowercase alphanumeric characters (letters and digits) and the dash "-".
        Organization slugs must be unique for the instance.
        You can provide additional metadata for the organization and set any custom attribute you want.
        Organizations support private and public metadata.
        Private metadata can only be accessed from the Backend API.
        Public metadata can be accessed from the Backend API, and are read-only from the Frontend API.
      tags:
        - Organizations
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the new organization
                created_by:
                  type: string
                  description:
                    The ID of the User who will become the administrator
                    for the new organization
                private_metadata:
                  type: object
                  description:
                    Metadata saved on the organization, accessible only
                    from the Backend API
                public_metadata:
                  type: object
                  description:
                    Metadata saved on the organization, read-only from
                    the Frontend API and fully accessible (read/write) from the Backend
                    API
                slug:
                  type: string
                  description: |-
                    A slug for the new organization.
                    Can contain only lowercase alphanumeric characters and the dash "-".
                    Must be unique for the instance.
                max_allowed_memberships:
                  type: integer
                  description:
                    The maximum number of memberships allowed for this
                    organization
              required:
                - name
                - created_by
      responses:
        "200":
          "$ref": "#/components/responses/Organization"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/organizations/{organization_id}":
    get:
      operationId: GetOrganization
      summary: Retrieve an organization by ID or slug
      description:
        Fetches the organization whose ID or slug matches the provided
        `id_or_slug` URL query parameter.
      tags:
        - Organizations
      parameters:
        - in: path
          name: organization_id
          required: true
          schema:
            type: string
          description: The ID or slug of the organization
      responses:
        "200":
          "$ref": "#/components/responses/Organization"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
    patch:
      operationId: UpdateOrganization
      summary: Update an organization
      description: Updates an existing organization
      tags:
        - Organizations
      parameters:
        - in: path
          name: organization_id
          required: true
          schema:
            type: string
          description: The ID of the organization to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                public_metadata:
                  type: object
                  description:
                    Metadata saved on the organization, that is visible
                    to both your frontend and backend.
                private_metadata:
                  type: object
                  description:
                    Metadata saved on the organization that is only visible
                    to your backend.
                name:
                  type: string
                  description: The new name of the organization
                  nullable: true
                slug:
                  type: string
                  description:
                    The new slug of the organization, which needs to be
                    unique in the instance
                  nullable: true
                max_allowed_memberships:
                  type: integer
                  description:
                    The maximum number of memberships allowed for this
                    organization
                  nullable: true
      responses:
        "200":
          "$ref": "#/components/responses/Organization"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
    delete:
      operationId: DeleteOrganization
      summary: Delete an organization
      description: |-
        Deletes the given organization.
        Please note that deleting an organization will also delete all memberships and invitations.
        This is not reversible.
      tags:
        - Organizations
      parameters:
        - in: path
          name: organization_id
          required: true
          schema:
            type: string
          description: The ID of the organization to delete
      responses:
        "200":
          "$ref": "#/components/responses/DeletedObject"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
  "/organizations/{organization_id}/metadata":
    patch:
      operationId: MergeOrganizationMetadata
      summary: Merge and update metadata for an organization
      description: |-
        Update organization metadata attributes by merging existing values with the provided parameters.
        Metadata values will be updated via a deep merge.
        Deep meaning that any nested JSON objects will be merged as well.
        You can remove metadata keys at any level by setting their value to `null`.
      tags:
        - Organizations
      parameters:
        - name: organization_id
          in: path
          description:
            The ID of the organization for which metadata will be merged
            or updated
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                public_metadata:
                  type: object
                  description: |-
                    Metadata saved on the organization, that is visible to both your frontend and backend.
                    The new object will be merged with the existing value.
                private_metadata:
                  type: object
                  description: |-
                    Metadata saved on the organization that is only visible to your backend.
                    The new object will be merged with the existing value.
      responses:
        "200":
          "$ref": "#/components/responses/Organization"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/organizations/{organization_id}/logo":
    put:
      operationId: UploadOrganizationLogo
      summary: Upload a logo for the organization
      description: |-
        Set or replace an organization's logo, by uploading an image file.
        This endpoint uses the `multipart/form-data` request content type and accepts a file of image type.
        The file size cannot exceed 10MB.
        Only the following file content types are supported: `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `image/x-icon`, `image/vnd.microsoft.icon`.
      tags:
        - Organizations
      parameters:
        - name: organization_id
          in: path
          description: The ID of the organization for which to upload a logo
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                uploader_user_id:
                  type: string
                file:
                  type: string
                  format: binary
      responses:
        "200":
          "$ref": "#/components/responses/OrganizationWithLogo"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
        "413":
          "$ref": "#/components/responses/ClerkErrors"
  "/organizations/{organization_id}/invitations":
    post:
      operationId: CreateOrganizationInvitation
      summary: Create and send an organization invitation
      description: |-
        Creates a new organization invitation and sends an email to the provided `email_address` with a link to accept the invitation and join the organization.
        You can specify the `role` for the invited organization member.

        New organization invitations get a "pending" status until they are revoked by an organization administrator or accepted by the invitee.

        The request body supports passing an optional `redirect_url` parameter.
        When the invited user clicks the link to accept the invitation, they will be redirected to the URL provided.
        Use this parameter to implement a custom invitation acceptance flow.

        You must specify the ID of the user that will send the invitation with the `inviter_user_id` parameter.
        That user must be a member with administrator privileges in the organization.
        Only "admin" members can create organization invitations.

        You can optionally provide public metadata for the organization invitation.
        These metadata are visible by both the Frontend and the Backend.
        When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership.
      tags:
        - Organization Invitations
      parameters:
        - in: path
          required: true
          name: organization_id
          schema:
            type: string
          description: The ID of the organization for which to send the invitation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email_address:
                  type: string
                  description:
                    The email address of the new member that is going to
                    be invited to the organization
                inviter_user_id:
                  type: string
                  description: |-
                    The ID of the user that invites the new member to the organization.
                    Must be an administrator in the organization.
                role:
                  type: string
                  description: The role of the new member in the organization
                  enum:
                    - admin
                    - basic_member
                public_metadata:
                  type: object
                  description:
                    Metadata saved on the organization invitation, read-only
                    from the Frontend API and fully accessible (read/write) from the
                    Backend API.
                redirect_url:
                  type: string
                  description:
                    Optional URL that the invitee will be redirected to
                    once they accept the invitation by clicking the join link in the
                    invitation email.
              required:
                - email_address
                - inviter_user_id
                - role
      responses:
        "200":
          "$ref": "#/components/responses/OrganizationInvitation"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/organizations/{organization_id}/invitations/pending":
    get:
      operationId: ListPendingOrganizationInvitations
      summary: Get a list of pending organization invitations
      description: |-
        This request returns the list of organization invitations with "pending" status.
        These are the organization invitations that can still be used to join the organization, but have not been accepted by the invited user yet.
        Results can be paginated using the optional `limit` and `offset` query parameters.
        The organization invitations are ordered by descending creation date.
        Most recent invitations will be returned first.
      tags:
        - Organization Invitations
      parameters:
        - in: path
          required: true
          name: organization_id
          schema:
            type: string
          description: The organization ID.
        - "$ref": "#/components/parameters/LimitParameter"
        - "$ref": "#/components/parameters/OffsetParameter"
      responses:
        "200":
          "$ref": "#/components/responses/OrganizationInvitations"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
  "/organizations/{organization_id}/invitations/{invitation_id}/revoke":
    post:
      operationId: RevokeOrganizationInvitation
      summary: Revoke a pending organization invitation
      description: |-
        Use this request to revoke a previously issued organization invitation.
        Revoking an organization invitation makes it invalid; the invited user will no longer be able to join the organization with the revoked invitation.
        Only organization invitations with "pending" status can be revoked.
        The request needs the `requesting_user_id` parameter to specify the user which revokes the invitation.
        Only users with "admin" role can revoke invitations.
      tags:
        - Organization Invitations
      parameters:
        - in: path
          required: true
          name: organization_id
          schema:
            type: string
          description: The organization ID.
        - in: path
          required: true
          name: invitation_id
          schema:
            type: string
          description: The organization invitation ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                requesting_user_id:
                  type: string
                  description: |-
                    The ID of the user that revokes the invitation.
                    Must be an administrator in the organization.
              required:
                - requesting_user_id
      responses:
        "200":
          "$ref": "#/components/responses/OrganizationInvitation"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
  "/organizations/{organization_id}/memberships":
    post:
      operationId: CreateOrganizationMembership
      summary: Create a new organization membership
      description: |-
        Adds a user as a member to the given organization.
        Only users in the same instance as the organization can be added as members.
      tags:
        - Organization Memberships
      parameters:
        - in: path
          required: true
          name: organization_id
          schema:
            type: string
          description: The ID of the organization where the new membership will be created
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  description: |-
                    The ID of the user that will be added as a member in the organization.
                    The user needs to exist in the same instance as the organization and must not be a member of the given organization already.
                role:
                  type: string
                  description: The role that the new member will have in the organization.
                  enum:
                    - admin
                    - basic_member
              required:
                - user_id
                - role
      responses:
        "200":
          "$ref": "#/components/responses/OrganizationMembership"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
    get:
      operationId: ListOrganizationMemberships
      summary: Get a list of all members of an organization
      description: Retrieves all user memberships for the given organization
      tags:
        - Organization Memberships
      parameters:
        - in: path
          required: true
          name: organization_id
          schema:
            type: string
          description: The organization ID.
        - "$ref": "#/components/parameters/LimitParameter"
        - "$ref": "#/components/parameters/OffsetParameter"
      responses:
        "200":
          "$ref": "#/components/responses/OrganizationMemberships"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/organizations/{organization_id}/memberships/{user_id}":
    patch:
      operationId: UpdateOrganizationMembership
      summary: Update an organization membership
      description: Updates the properties of an existing organization membership
      tags:
        - Organization Memberships
      parameters:
        - in: path
          required: true
          name: organization_id
          schema:
            type: string
          description: The ID of the organization the membership belongs to
        - in: path
          required: true
          name: user_id
          schema:
            type: string
          description: The ID of the user that this membership belongs to
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                role:
                  type: string
                  description: The new role of the given membership.
                  enum:
                    - admin
                    - basic_member
              required:
                - role
      responses:
        "200":
          "$ref": "#/components/responses/OrganizationMembership"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
    delete:
      operationId: DeleteOrganizationMembership
      summary: Remove a member from an organization
      description: Removes the given membership from the organization
      tags:
        - Organization Memberships
      parameters:
        - in: path
          required: true
          name: organization_id
          schema:
            type: string
          description: The ID of the organization the membership belongs to
        - in: path
          required: true
          name: user_id
          schema:
            type: string
          description: The ID of the user that this membership belongs to
      responses:
        "200":
          "$ref": "#/components/responses/OrganizationMembership"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "401":
          "$ref": "#/components/responses/AuthenticationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
  "/organizations/{organization_id}/memberships/{user_id}/metadata":
    patch:
      operationId: UpdateOrganizationMembershipMetadata
      summary: Merge and update organization membership metadata
      description: |-
        Update an organization membership's metadata attributes by merging existing values with the provided parameters.
        Metadata values will be updated via a deep merge. Deep means that any nested JSON objects will be merged as well.
        You can remove metadata keys at any level by setting their value to `null`.
      tags:
        - Organization Memberships
      parameters:
        - in: path
          required: true
          name: organization_id
          schema:
            type: string
          description: The ID of the organization the membership belongs to
        - in: path
          required: true
          name: user_id
          schema:
            type: string
          description: The ID of the user that this membership belongs to
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                public_metadata:
                  type: object
                  description: |-
                    Metadata saved on the organization membership, that is visible to both your frontend and backend.
                    The new object will be merged with the existing value.
                private_metadata:
                  type: object
                  description: |-
                    Metadata saved on the organization membership that is only visible to your backend.
                    The new object will be merged with the existing value.
      responses:
        "200":
          "$ref": "#/components/responses/OrganizationMembership"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/redirect_urls":
    get:
      summary: List all redirect URLs
      description: Lists all whitelisted redirect_urls for the instance
      operationId: ListRedirectURLs
      tags:
        - Redirect URLs
      responses:
        "200":
          "$ref": "#/components/responses/RedirectURL.List"
    post:
      description: Create a redirect URL
      operationId: CreateRedirectURL
      tags:
        - Redirect URLs
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                url:
                  type: string
                  description:
                    The full url value prefixed with `https://` or a custom
                    scheme e.g. `"https://my-app.com/oauth-callback"` or `"my-app://oauth-callback"`
                  nullable: false
      responses:
        "200":
          "$ref": "#/components/responses/RedirectURL"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/redirect_urls/{id}":
    get:
      summary: Retrieve a redirect URL
      description: Retrieve the details of the redirect URL with the given ID
      operationId: GetRedirectURL
      tags:
        - Redirect URLs
      parameters:
        - name: id
          in: path
          description: The ID of the redirect URL
          required: true
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/RedirectURL"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
    delete:
      summary: Delete a redirect URL
      description: Remove the selected redirect URL from the whitelist of the instance
      operationId: DeleteRedirectURL
      tags:
        - Redirect URLs
      parameters:
        - name: id
          in: path
          description: The ID of the redirect URL
          required: true
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/DeletedObject"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
  "/sign_in_tokens":
    post:
      summary: Create sign-in token
      description: |-
        Creates a new sign-in token and associates it with the given user.
        By default, sign-in tokens expire in 30 days.
        You can optionally supply a different duration in seconds using the `expires_in_seconds` property.
      operationId: CreateSignInToken
      tags:
        - Sign-in Tokens
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  description:
                    The ID of the user that can use the newly created sign
                    in token
                expires_in_seconds:
                  type: integer
                  description: |-
                    Optional parameter to specify the life duration of the sign in token in seconds.
                    By default, the duration is 30 days.
                  default: 2592000
      responses:
        "200":
          "$ref": "#/components/responses/SignInToken"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/sign_in_tokens/{sign_in_token_id}/revoke":
    post:
      summary: Revoke the given sign-in token
      description: Revokes a pending sign-in token
      operationId: RevokeSignInToken
      tags:
        - Sign-in Tokens
      parameters:
        - name: sign_in_token_id
          in: path
          description: The ID of the sign-in token to be revoked
          required: true
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/SignInToken"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
  "/sign_ups/{id}":
    patch:
      operationId: UpdateSignUp
      summary: Update a sign-up
      description: Update the sign-up with the given ID
      tags:
        - Sign-ups
      parameters:
        - name: id
          in: path
          description: The ID of the sign-up to update
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                custom_action:
                  type: boolean
                  description: |-
                    Specifies whether a custom action has run for this sign-up attempt.
                    This is important when your instance has been configured to require a custom action to run before converting a sign-up into a user.
                    After executing any external business logic you deem necessary, you can mark the sign-up as ready-to-convert by setting `custom_action` to `true`.
                external_id:
                  type: string
                  description: |-
                    The ID of the guest attempting to sign up as used in your external systems or your previous authentication solution.
                    This will be copied to the resulting user when the sign-up is completed.
                  nullable: true
      responses:
        "200":
          "$ref": "#/components/responses/SignUp"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
  "/oauth_applications":
    get:
      operationId: ListOAuthApplications
      summary: Get a list of OAuth applications for an instance
      description: |-
        This request returns the list of OAuth applications for an instance.
        Results can be paginated using the optional `limit` and `offset` query parameters.
        The OAuth applications are ordered by descending creation date.
        Most recent OAuth applications will be returned first.
      tags:
        - OAuth Applications
      parameters:
        - "$ref": "#/components/parameters/LimitParameter"
        - "$ref": "#/components/parameters/OffsetParameter"
      responses:
        "200":
          "$ref": "#/components/responses/OAuthApplications"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
    post:
      operationId: CreateOAuthApplication
      summary: Create an OAuth application
      description: |-
        Creates a new OAuth application with the given name and callback URL for an instance.
        The callback URL must be a valid url.
        All URL schemes are allowed such as `http://`, `https://`, `myapp://`, etc...
      tags:
        - OAuth Applications
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The name of the new OAuth application
                callback_url:
                  type: string
                  description: The callback URL of the new OAuth application
              required:
                - name
                - callback_url
      responses:
        "200":
          "$ref": "#/components/responses/OAuthApplicationWithSecret"
        "400":
          "$ref": "#/components/responses/ClerkErrors"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
  "/oauth_applications/{oauth_application_id}":
    get:
      operationId: GetOAuthApplication
      summary: Retrieve an OAuth application by ID
      description:
        Fetches the OAuth application whose ID matches the provided `id`
        in the path.
      tags:
        - OAuth Applications
      parameters:
        - in: path
          name: oauth_application_id
          required: true
          schema:
            type: string
          description: The ID of the OAuth application
      responses:
        "200":
          "$ref": "#/components/responses/OAuthApplication"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
    patch:
      operationId: UpdateOAuthApplication
      summary: Update an OAuth application
      description: Updates an existing OAuth application
      tags:
        - OAuth Applications
      parameters:
        - in: path
          name: oauth_application_id
          required: true
          schema:
            type: string
          description: The ID of the OAuth application to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                name:
                  type: string
                  description: The new name of the OAuth application
                callback_url:
                  type: string
                  description: The new callback URL of the OAuth application
              required:
                - name
                - callback_url
      responses:
        "200":
          "$ref": "#/components/responses/OAuthApplication"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
        "422":
          "$ref": "#/components/responses/UnprocessableEntity"
    delete:
      operationId: DeleteOAuthApplication
      summary: Delete an OAuth application
      description: |-
        Deletes the given OAuth application.
        This is not reversible.
      tags:
        - OAuth Applications
      parameters:
        - in: path
          name: oauth_application_id
          required: true
          schema:
            type: string
          description: The ID of the OAuth application to delete
      responses:
        "200":
          "$ref": "#/components/responses/DeletedObject"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"
  "/oauth_applications/{oauth_application_id}/rotate_secret":
    post:
      operationId: RotateOAuthApplicationSecret
      summary: Rotate the client secret of the given OAuth application
      description: |-
        Rotates the OAuth application's client secret.
        When the client secret is rotated, make sure to update it in authorized OAuth clients.
      tags:
        - OAuth Applications
      parameters:
        - name: oauth_application_id
          in: path
          description:
            The ID of the OAuth application for which to rotate the client
            secret
          required: true
          schema:
            type: string
      responses:
        "200":
          "$ref": "#/components/responses/OAuthApplicationWithSecret"
        "403":
          "$ref": "#/components/responses/AuthorizationInvalid"
        "404":
          "$ref": "#/components/responses/ResourceNotFound"