naftiko: 1.0.0-alpha2
info:
  label: Clerk Backend Api — Organization Memberships
  description: 'Clerk Organization Memberships capability. 6 operations. Lead operation: Create a New Organization Membership.'
  tags:
  - Clerk
  - Organization Memberships
  created: '2026-05-22'
  modified: '2026-05-22'
binds:
- namespace: env
  keys:
    CLERK_SECRET_KEY: CLERK_SECRET_KEY
capability:
  consumes:
  - type: http
    namespace: clerk-backend-api-organization-memberships
    baseUri: https://api.clerk.com/v1
    description: Clerk clerk-backend-api Organization Memberships business capability.
    resources:
    - name: organizations-organization-id-memberships
      path: /organizations/{organization_id}/memberships
      operations:
      - name: CreateOrganizationMembership
        method: POST
        description: Create a New Organization Membership
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: organization_id
          in: path
          type: string
          description: The ID of the organization where the new membership will be created
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: ListOrganizationMemberships
        method: GET
        description: Get a List of All Members of an Organization
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: organization_id
          in: path
          type: string
          description: The organization ID.
          required: true
        - name: order_by
          in: query
          type: string
          description: 'Sorts organizations memberships by phone_number, email_address, created_at, first_name, last_name or username.

            By prepending one of those values with + or -, we can choose to sort in ascending (ASC) o'
          required: false
        - name: user_id
          in: query
          type: array
          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.'
          required: false
        - name: email_address
          in: query
          type: array
          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
          type: array
          description: Returns users with the specified phone numbers. Accepts up to 100 phone numbers. Any phone numbers not found are ignored.
          required: false
        - name: username
          in: query
          type: array
          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
          type: array
          description: 'Returns users with the specified web3 wallet addresses.

            Accepts up to 100 web3 wallet addresses.

            Any web3 wallet addresses not found are ignored.'
          required: false
        - name: role
          in: query
          type: array
          description: Returns users with the specified roles. Accepts up to 100 roles. Any roles not found are ignored.
          required: false
        - name: query
          in: query
          type: string
          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 ma'
          required: false
        - name: email_address_query
          in: query
          type: string
          description: 'Returns users with emails that match the given query, via case-insensitive partial match.

            For example, `email_address_query=ello` will match a user with the email `HELLO@example.com`.'
          required: false
        - name: phone_number_query
          in: query
          type: string
          description: 'Returns users with phone numbers that match the given query, via case-insensitive partial match.

            For example, `phone_number_query=555` will match a user with the phone number `+1555xxxxxxx`.'
          required: false
        - name: username_query
          in: query
          type: string
          description: 'Returns users with usernames that match the given query, via case-insensitive partial match.

            For example, `username_query=CoolUser` will match a user with the username `SomeCoolUser`.'
          required: false
        - name: name_query
          in: query
          type: string
          description: Returns users with names that match the given query, via case-insensitive partial match.
          required: false
        - name: last_active_at_before
          in: query
          type: integer
          description: 'Returns users whose last session activity was before the given date (with millisecond precision).

            Example: use 1700690400000 to retrieve users whose last session activity was before 2023-11-23.'
          required: false
        - name: last_active_at_after
          in: query
          type: integer
          description: 'Returns users whose last session activity was after the given date (with millisecond precision).

            Example: use 1700690400000 to retrieve users whose last session activity was after 2023-11-23.'
          required: false
        - name: created_at_before
          in: query
          type: integer
          description: 'Returns users who have been created before the given date (with millisecond precision).

            Example: use 1730160000000 to retrieve users who have been created before 2024-10-29.'
          required: false
        - name: created_at_after
          in: query
          type: integer
          description: 'Returns users who have been created after the given date (with millisecond precision).

            Example: use 1730160000000 to retrieve users who have been created after 2024-10-29.'
          required: false
    - name: organizations-organization-id-memberships-user-id
      path: /organizations/{organization_id}/memberships/{user_id}
      operations:
      - name: UpdateOrganizationMembership
        method: PATCH
        description: Update an Organization Membership
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: organization_id
          in: path
          type: string
          description: The ID of the organization to which this membership belongs
          required: true
        - name: user_id
          in: path
          type: string
          description: The ID of the user to which this membership belongs
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
      - name: DeleteOrganizationMembership
        method: DELETE
        description: Remove a Member from an Organization
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: organization_id
          in: path
          type: string
          description: The ID of the organization to which this membership belongs
          required: true
        - name: user_id
          in: path
          type: string
          description: The ID of the user to which this membership belongs
          required: true
    - name: organizations-organization-id-memberships-user-id-metadata
      path: /organizations/{organization_id}/memberships/{user_id}/metadata
      operations:
      - name: UpdateOrganizationMembershipMetadata
        method: PATCH
        description: Merge and Update Organization Membership Metadata
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: organization_id
          in: path
          type: string
          description: The ID of the organization to which this membership belongs
          required: true
        - name: user_id
          in: path
          type: string
          description: The ID of the user to which this membership belongs
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: organization-memberships
      path: /organization_memberships
      operations:
      - name: InstanceGetOrganizationMemberships
        method: GET
        description: Get a List of All Organization Memberships Within an Instance.
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: order_by
          in: query
          type: string
          description: 'Sorts organizations memberships by phone_number, email_address, created_at, first_name, last_name or username.

            By prepending one of those values with + or -,

            we can choose to sort in ascending (ASC) o'
          required: false