Clerk Members API

openapi: 3.2.0
info:
  title: Clerk Frontend Members API
  version: v1
  description: 'The Clerk REST Frontend API, meant to be accessed from a browser or native environment.


    This is a Form Based API and all the data must be sent and formatted according to the `application/x-www-form-urlencoded` content type.


    ### Versions


    When the API changes in a way that isn''t compatible with older versions, a new version is released.

    Each version is identified by its release date, e.g. `2021-02-05`. For more information, please see [Clerk API Versions](https://clerk.com/docs/backend-requests/versioning/overview).


    ### Using the Try It Console


    The `Try It` feature of the docs only works for **Development Instances** when using the `DevBrowser` security scheme.

    To use it, first generate a dev instance token from the `/v1/dev_browser` endpoint.


    Please see https://clerk.com/docs for more information.'
  x-logo:
    url: https://clerk.com/_next/image?url=%2Fimages%2Fclerk-logo.svg&w=96&q=75
    altText: Clerk docs
    href: https://clerk.com/docs
  contact:
    email: support@clerk.com
    name: Clerk Team
    url: https://clerk.com/support
  termsOfService: https://clerk.com/terms
  license:
    name: MIT
    url: https://github.com/clerk/javascript/blob/main/LICENSE
servers:
- url: https://{domain}.clerk.accounts.dev
  variables:
    domain:
      default: example-destined-camel-13
      description: Your Development Instance Frontend API Domain.
security:
- {}
- DevBrowser: []
- ProductionBrowser: []
- ProductionNativeApp: []
  ProductionNativeFlag: []
tags:
- name: Members
  description: Used to interact with the members of an organization. The current user must be an administrator to access them.
paths:
  /v1/organizations/{organization_id}/memberships:
    post:
      summary: Create Organization Membership
      description: 'Create a new organization membership.


        The current user must have permissions to manage the members of the organization.'
      tags:
      - Members
      operationId: CreateOrganizationMembership
      parameters:
      - in: path
        required: true
        name: organization_id
        schema:
          type: string
        description: The organization ID.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              additionalProperties: false
              properties:
                user_id:
                  type:
                  - string
                  - 'null'
                  description: The ID of the user to be added as a member.
                role:
                  type:
                  - string
                  - 'null'
                  description: 'The role that will be assigned to the user after joining.

                    This can be one of the predefined roles (`org:admin`, `org:basic_member`) or a custom role defined.'
              required:
              - user_id
              - role
      responses:
        '200':
          $ref: '#/components/responses/Client.ClientWrappedOrganizationMembership'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/ClerkErrors'
    get:
      summary: Get All Organization Members
      description: 'Retrieve all members of an organization.


        The current user must have permissions to manage the members of the organization.'
      operationId: ListOrganizationMemberships
      tags:
      - Members
      parameters:
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      - $ref: '#/components/parameters/Paginated'
      - in: path
        required: true
        name: organization_id
        schema:
          type: string
        description: The organization ID.
      - in: query
        required: false
        name: query
        schema:
          type: string
        description: 'Returns members that match the given query.

          For possible matches, we check for any of the user''s identifier, usernames, user IDs, first and last names.

          The query value doesn''t need to match the exact value you are looking for, it is capable of partial matches as well.'
      - in: query
        required: false
        name: role
        description: Filter by roles. This can be one of the predefined roles (`org:admin`, `org:basic_member`) or a custom role defined.
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/Client.ClientWrappedOrganizationMemberships'
        '401':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/ClerkErrors'
  /v1/organizations/{organization_id}/memberships/{user_id}:
    patch:
      summary: Update Organization Membership
      description: 'Update the attributes of an organization membership for a specific user.

        The current user must have permissions to manage the members of the organization.'
      tags:
      - Members
      operationId: UpdateOrganizationMembership
      parameters:
      - in: path
        required: true
        name: organization_id
        schema:
          type: string
        description: The organization ID.
      - in: path
        required: true
        name: user_id
        schema:
          type: string
        description: The member ID.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              additionalProperties: false
              properties:
                role:
                  type: string
                  description: 'The new role that will be assigned to the member.

                    This can be one of the predefined roles (`org:admin`, `org:basic_member`) or a custom role defined.'
      responses:
        '200':
          $ref: '#/components/responses/Client.ClientWrappedOrganizationMembership'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/ClerkErrors'
    delete:
      summary: Remove Organization Member
      description: 'Remove a member from an organization.


        The current user must have permissions to manage the members of the organization.'
      operationId: removeOrganizationMember
      tags:
      - Members
      parameters:
      - in: path
        required: true
        name: organization_id
        schema:
          type: string
        description: The organization ID.
      - in: path
        required: true
        name: user_id
        schema:
          type: string
        description: The member ID.
      responses:
        '200':
          $ref: '#/components/responses/Client.ClientWrappedOrganizationMembership'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/ClerkErrors'
components:
  schemas:
    Stubs.Verification.SAML:
      type: object
      properties:
        object:
          type: string
          enum:
          - verification_saml
        status:
          type: string
          enum:
          - unverified
          - verified
          - failed
          - expired
          - transferable
        strategy:
          type: string
          enum:
          - saml
        external_verification_redirect_url:
          type:
          - string
          - 'null'
        error:
          allOf:
          - $ref: '#/components/schemas/ClerkError'
          - type:
            - object
            - 'null'
        expire_at:
          type:
          - integer
          - 'null'
        attempts:
          type:
          - integer
          - 'null'
      required:
      - status
      - strategy
    Stubs.Verification.Link:
      type: object
      properties:
        object:
          type: string
          enum:
          - verification_email_link
        status:
          type: string
          enum:
          - unverified
          - verified
          - failed
          - expired
          - transferable
        strategy:
          type: string
          enum:
          - email_link
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type: integer
        verified_at_client:
          type: string
      required:
      - status
      - strategy
      - expire_at
    Client.Passkey:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        object:
          type: string
          description: 'String representing the object''s type. Objects of the same type share the same value.

            '
          enum:
          - passkey
        name:
          type: string
        last_used_at:
          type:
          - integer
          - 'null'
          format: int64
          description: 'Unix timestamp of when the passkey was last used.

            '
        verification:
          type:
          - object
          - 'null'
          oneOf:
          - $ref: '#/components/schemas/Stubs.Verification.Passkey'
        created_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation

            '
        updated_at:
          type: integer
          format: int64
          description: 'Unix timestamp of update

            '
      required:
      - id
      - object
      - name
      - verification
    Stubs.SignInFactor:
      type: object
      additionalProperties: false
      properties:
        strategy:
          type: string
          enum:
          - ticket
          - password
          - email_code
          - email_link
          - phone_code
          - web3_metamask_signature
          - web3_base_signature
          - web3_coinbase_wallet_signature
          - web3_okx_wallet_signature
          - web3_solana_signature
          - totp
          - backup_code
          - oauth_apple
          - oauth_google
          - oauth_facebook
          - oauth_hubspot
          - oauth_github
          - oauth_mock
          - oauth_custom_mock
          - oauth_token_mock
          - saml
          - enterprise_sso
          - reset_password_email_code
          - reset_password_phone_code
          - passkey
          - google_one_tap
        safe_identifier:
          type: string
        enterprise_connection_id:
          type: string
        enterprise_connection_name:
          type: string
        email_address_id:
          type: string
        phone_number_id:
          type: string
        web3_wallet_id:
          type: string
        passkey_id:
          type: string
        primary:
          type:
          - boolean
          - 'null'
        external_verification_redirect_url:
          type:
          - string
          - 'null'
        default:
          type: boolean
      required:
      - strategy
    Stubs.Verification.BackupCode:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - verification_backup_code
        status:
          type: string
          enum:
          - unverified
          - verified
        strategy:
          type: string
          enum:
          - backup_code
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type:
          - integer
          - 'null'
      required:
      - status
      - strategy
    Stubs.Verification.FromOauth:
      type: object
      properties:
        object:
          type: string
          enum:
          - verification_from_oauth
        status:
          type: string
          enum:
          - verified
          - unverified
        strategy:
          type: string
          enum:
          - from_oauth_apple
          - from_oauth_google
          - from_oauth_mock
          - from_oauth_custom_mock
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type:
          - integer
          - 'null'
      required:
      - status
      - strategy
    Token:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          description: 'String representing the object''s type. Objects of the same type share the same value.

            '
          enum:
          - token
        jwt:
          type: string
          description: 'String representing the encoded JWT value.

            '
      required:
      - object
      - jwt
    Stubs.Verification.Admin:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - verification_admin
        status:
          type: string
          enum:
          - verified
          - unverified
          - failed
          - expired
        strategy:
          type: string
          enum:
          - admin
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type:
          - integer
          - 'null'
      required:
      - status
      - strategy
    Client.EmailAddress:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        object:
          type: string
          description: 'String representing the object''s type. Objects of the same type share the same value.

            '
          enum:
          - email_address
        email_address:
          type: string
        reserved:
          type: boolean
        verification:
          type:
          - object
          - 'null'
          oneOf:
          - $ref: '#/components/schemas/Stubs.Verification.OTP'
          - $ref: '#/components/schemas/Stubs.Verification.Invitation'
          - $ref: '#/components/schemas/Stubs.Verification.Link'
          - $ref: '#/components/schemas/Stubs.Verification.Ticket'
          - $ref: '#/components/schemas/Stubs.Verification.Admin'
          - $ref: '#/components/schemas/Stubs.Verification.FromOauth'
          - $ref: '#/components/schemas/Stubs.Verification.SAML'
        linked_to:
          type: array
          items:
            $ref: '#/components/schemas/Stubs.Identification.Link'
        matches_sso_connection:
          description: 'Indicates whether this email address domain matches an active enterprise connection.

            '
          type: boolean
        created_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation

            '
        updated_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation

            '
      required:
      - id
      - object
      - email_address
      - verification
      - linked_to
      - reserved
      - created_at
      - updated_at
    ExternalAccountWithVerification:
      type: object
      additionalProperties: true
      properties:
        object:
          type: string
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - external_account
          - facebook_account
          - google_account
        id:
          type: string
        provider:
          type: string
        identification_id:
          type: string
        provider_user_id:
          description: The unique ID of the user in the external provider's system
          type: string
        approved_scopes:
          type: string
        email_address:
          type: string
        email_address_verified:
          type:
          - boolean
          - 'null'
          description: 'Whether the email was verified by the OAuth provider at creation time. null = unknown (pre-migration data or custom OAuth providers), true = provider confirmed email was verified, false = provider confirmed email was NOT verified

            '
        first_name:
          type: string
        last_name:
          type: string
        avatar_url:
          type: string
          deprecated: true
          description: Please use `image_url` instead
        image_url:
          type:
          - string
          - 'null'
        username:
          type:
          - string
          - 'null'
        phone_number:
          type:
          - string
          - 'null'
        public_metadata:
          type: object
          additionalProperties: true
        label:
          type:
          - string
          - 'null'
        created_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation

            '
        updated_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation

            '
        verification:
          type:
          - object
          - 'null'
          oneOf:
          - $ref: '#/components/schemas/verification_oauth'
          - $ref: '#/components/schemas/verification_google_one_tap'
          discriminator:
            propertyName: object
      required:
      - object
      - id
      - provider
      - identification_id
      - provider_user_id
      - approved_scopes
      - email_address
      - first_name
      - last_name
      - public_metadata
      - created_at
      - updated_at
      - verification
    Client.OrganizationMembership:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          description: 'String representing the object''s type. Objects of the same type share the same value.

            '
          enum:
          - organization_membership
        public_metadata:
          type: object
          additionalProperties: true
        role:
          type: string
        role_name:
          type: string
        permissions:
          type:
          - array
          - 'null'
          items:
            type: string
        created_at:
          type: integer
          format: int64
          description: Unix timestamp of creation.
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp of last update.
        organization:
          $ref: '#/components/schemas/Client.Organization'
        public_user_data:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/Client.PublicUserData'
      required:
      - object
      - id
      - public_metadata
      - role
      - role_name
      - permissions
      - created_at
      - updated_at
      - organization
    Client.PublicUserData:
      type: object
      additionalProperties: false
      properties:
        first_name:
          type:
          - string
          - 'null'
        last_name:
          type:
          - string
          - 'null'
        image_url:
          type:
          - string
          - 'null'
        has_image:
          type: boolean
        identifier:
          type: string
        profile_image_url:
          type:
          - string
          - 'null'
          deprecated: true
          description: Use `image_url` instead.
        user_id:
          type:
          - string
          - 'null'
        username:
          type:
          - string
          - 'null'
        banned:
          type: boolean
      required:
      - first_name
      - last_name
      - identifier
      - has_image
    verification_oauth:
      x-speakeasy-name-override: Oauth
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - verification_oauth
        status:
          type: string
          x-speakeasy-unknown-values: allow
          enum:
          - unverified
          - verified
          - failed
          - expired
          - transferable
        strategy:
          type: string
          x-speakeasy-unknown-values: allow
          pattern: ^oauth_(?:(?:token_)|(?:custom_))?[a-z]+$
        external_verification_redirect_url:
          type: string
        error:
          type:
          - object
          - 'null'
          oneOf:
          - $ref: '#/components/schemas/ClerkError'
        expire_at:
          type: integer
        attempts:
          type:
          - integer
          - 'null'
        verified_at_client:
          type:
          - string
          - 'null'
      required:
      - status
      - strategy
      - attempts
      - expire_at
    Stubs.Verification.Ticket:
      type: object
      properties:
        object:
          type: string
          enum:
          - verification_ticket
        status:
          type: string
          enum:
          - unverified
          - verified
          - expired
        strategy:
          type: string
          enum:
          - ticket
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type:
          - integer
          - 'null'
      required:
      - status
      - strategy
    schemas-Client.Session:
      allOf:
      - $ref: '#/components/schemas/schemas-Client.SessionBase'
      - type: object
        properties:
          last_active_organization_id:
            type:
            - string
            - 'null'
          user:
            $ref: '#/components/schemas/Client.User'
          public_user_data:
            type:
            - object
            - 'null'
            allOf:
            - $ref: '#/components/schemas/Client.PublicUserData'
          factor_verification_age:
            type: array
            description: Each item represents the minutes that have passed since the last time a first or second factor were verified.
            items:
              type: integer
          created_at:
            type: integer
            format: int64
            description: Unix timestamp of creation.
            example: 1700690400000
          updated_at:
            type: integer
            format: int64
            description: Unix timestamp of last update.
            example: 1700690400000
        required:
        - last_active_organization_id
        - public_user_data
        - factor_verification_age
        - created_at
        - updated_at
    Stubs.Verification.Passkey:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - verification_passkey
        status:
          type: string
          enum:
          - unverified
          - verified
          - failed
          - expired
        strategy:
          type: string
          enum:
          - passkey
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type: integer
        nonce:
          type: string
      required:
      - status
      - strategy
      - expire_at
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ClerkError'
        meta:
          type: object
        clerk_trace_id:
          type: string
      required:
      - errors
    Client.ClientWrappedOrganizationMembership:
      type: object
      additionalProperties: false
      properties:
        response:
          type: object
          allOf:
          - $ref: '#/components/schemas/Client.OrganizationMembership'
        client:
          type: object
          allOf:
          - $ref: '#/components/schemas/schemas-Client.Client'
      required:
      - response
      - client
    Stubs.Verification.Web3Signature:
      type: object
      properties:
        object:
          type: string
          enum:
          - verification_web3
        status:
          type: string
          enum:
          - unverified
          - verified
          - failed
          - expired
        strategy:
          type: string
          enum:
          - web3_metamask_signature
          - web3_base_signature
          - web3_coinbase_wallet_signature
          - web3_okx_wallet_signature
          - web3_solana_signature
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type:
          - integer
          - 'null'
        nonce:
          type:
          - string
          - 'null'
        message:
          type:
          - string
          - 'null'
      required:
      - status
      - strategy
    Client.SessionTask:
      type: object
      properties:
        key:
          type: string
      required:
      - key
    schemas-Client.Client:
      type:
      - object
      - 'null'
      properties:
        object:
          type: string
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - client
        id:
          type: string
          description: String representing the identifier of the session.
        sessions:
          type: array
          items:
            $ref: '#/components/schemas/schemas-Client.Session'
        sign_in:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/schemas-Client.SignIn'
        sign_up:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/Client.SignUp'
        last_active_session_id:
          type:
          - string
          - 'null'
          description: Last active session_id.
        last_authentication_strategy:
          type:
          - string
          - 'null'
          description: 'The authentication strategy that was last used to authenticate the user on this client.

            '
        cookie_expires_at:
          type:
          - integer
          - 'null'
          format: int64
          description: Unix timestamp of the cookie expiration.
        captcha_bypass:
          type: boolean
          description: Whether the client can bypass CAPTCHA.
        created_at:
          type: integer
          format: int64
          description: Unix timestamp of creation.
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp of last update.
      required:
      - object
      - id
      - sessions
      - sign_in
      - sign_up
      - last_active_session_id
      - last_authentication_strategy
      - cookie_expires_at
      - captcha_bypass
      - created_at
      - updated_at
    Client.User:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          description: 'String representing the object''s type. Objects of the same type share the same value.

            '
          enum:
          - user
        username:
          type:
          - string
          - 'null'
        first_name:
          type:
          - string
          - 'null'
        last_name:
          type:
          - string
          - 'null'
        image_url:
          type: string
        has_image:
          type: boolean
        primary_email_address_id:
          type:
          - string
          - 'null'
        primary_phone_number_id:
          type:
          - string
          - 'null'
        primary_web3_wallet_id:
          type:
          - string
          - 'null'
        password_enabled:
          type: boolean
        two_factor_enabled:
          type: boolean
        totp_enabled:
          type: boolean
        backup_code_enabled:
          type: boolean
        email_addresses:
          type: array
          items:
            $ref: '#/components/schemas/Client.EmailAddress'
        phone_numbers:
          type: array
          items:
            $ref: '#/components/schemas/Client.PhoneNumber'
        web3_wallets:
          type: array
          items:
            $ref: '#/components/schemas/Client.Web3Wallet'
        passkeys:
          type: array
          items:
            $ref: '#/components/schemas/Client.Passkey'
        organization_memberships:
          type: array
          items:
            $ref: '#/components/schemas/Client.OrganizationMembership'
        external_accounts:
          type: array
          items:
            $ref: '#/components/schemas/ExternalAccountWithVerification'
        saml_accounts:
          type: array
          items:
            $ref: '#/components/schemas/Client.SAMLAccount'
        password_last_updated_at:
          type:
          - integer
          - 'null'
          format: int64
          description: Unix timestamp of last update.
          example: 1700690400000
        public_metadata:
          type: object
          additionalProperties: true
        private_metadata:
          type: object
          additionalProperties: true
        unsafe_metadata:
          type: object
          additionalProperties: true
        external_id:
          type:
          - string
          - 'null'
        last_sign_in_at:
          type:
          - integer
          - 'null'
          format: int64
          description: Unix timestamp of last sign-in.
          example: 1700690400000
        banned:
          type: boolean
          description: Flag to denote whether user is banned or not.
        locked:
          type: boolean
          description: 'Flag to denote whether user is currently locked, i.e. restricted from signing in or not.

            '
        deprovisioned:
          type: boolean
          description: 'Flag to denote whether the user has been deprovisioned via SCIM and is restricted from signing in. Only present on instances with SCIM enabled.

            '
        lockout_expires_in_seconds:
          type:
          - integer
          - 'null'
          format: int64
          description: 'The number of seconds remaining until the lockout period expires for a locked user. A null value for a locked user indicates that lockout never expires.

            '
          example: 300
        verification_attempts_remaining:
          type:
          - integer
          - 'null'
          format: int64
          description: 'The number of verification attempts remaining until the user is locked. Null if account lockout is not enabled. Note: if a user is locked explicitly via the Backend API, they may still have verification attempts remaining.

            '
        created_at:
          type: integer
          format: int64
          description: Unix timestamp of creation.
          example: 1700690400000
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp of last update.
          example: 1700690400000
        delete_self_enabled:
          type: boolean
          description: If enabled, user can delete themselves via FAPI.
        create_organization_enabled:
          type: boolean
          description: If enabled, user can create organizations via FAPI.
        create_organizations_limit:
          type: integer
          description: The maximum number of organizations the user can create. 0 means unlimited.
        last_active_at:
          type:
          - integer
          - 'null'
          format: int64
          description: Unix timestamp of the latest session activity, with day precision.
          example: 1700690400000
        mfa_enabled_at:
          type:
          - integer
          - 'null'
          format: int64
          description: Unix timestamp at which the user enabled MFA.
          example: 1700690400000
        mfa_disabled_at:
          type:
          - integer
          - 'null'
          format: int64
          description: Unix timestamp at which the user disabled MFA.
          example: 1700690400000
        legal_accepted_at:
          type:
          - integer
          - 'null'
          format: int64
          description: Unix timestamp at which the user accepted the legal requirements.
          example: 1700690400000
        profile_image_url:
          type: strin

# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/clerk-com/refs/heads/main/openapi/clerk-com-members-api-openapi.yml