Clerk

Clerk Organization Memberships API

Manage member roles in an organization.

GitHub OpenAPI
Business capability
Identity & Access Management BC-620.20

Operations 6

Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay

POST /organizations/{organization_id}/memberships Add a user to an organization · Create a New Organization Membership #
Ask an LLM
“How do I add an existing user to an organization with a role?”
“Can I attach private metadata to a new organization membership?”
Tell an agent
Add user {user_id} to organization {organization_id} as {role}.
Make user {user_id} a {role} of organization {organization_id} with private metadata {private_metadata}.
GET /organizations/{organization_id}/memberships List members of an organization · Get a List of All Members of an Organization #
Ask an LLM
“Who are the members of a given organization?”
“Can I filter an organization's members by role or by when they were last active?”
Tell an agent
List members of organization {organization_id}.
List members of organization {organization_id} with role {role}.
PATCH /organizations/{organization_id}/memberships/{user_id} Change a member's organization role · Update an Organization Membership #
Ask an LLM
“How do I promote an organization member to admin?”
“Can I change a member's role in an organization?”
Tell an agent
Change user {user_id}'s role in organization {organization_id} to {role}.
Promote member {user_id} of organization {organization_id} to {role}.
DELETE /organizations/{organization_id}/memberships/{user_id} Remove a member from an organization · Remove a Member from an Organization #
Ask an LLM
“How do I kick a user out of an organization?”
“Can I remove someone from an organization without deleting their user account?”
Tell an agent destructive · confirm first
Remove user {user_id} from organization {organization_id}.
Take user {user_id} out of organization {organization_id}.
PATCH /organizations/{organization_id}/memberships/{user_id}/metadata Merge metadata on an organization membership · Merge and Update Organization Membership Metadata #
Ask an LLM
“How do I store custom data on a user's membership in an organization?”
“Is membership metadata deep-merged, and how do I remove a key?”
Tell an agent
Merge public metadata {public_metadata} into user {user_id}'s membership in organization {organization_id}.
Deep-merge private metadata {private_metadata} into membership of {user_id} in {organization_id}.
GET /organization_memberships List all organization memberships in the instance · Get a List of All Organization Memberships Within an Instance #
Ask an LLM
“How do I see every organization membership across my whole instance?”
“Can I sort all memberships instance-wide?”
Tell an agent
List all organization memberships across the instance.
List instance-wide memberships ordered by {order_by}.

Documentation

📖
Documentation
https://clerk.com/docs/reference/backend-api
📖
APIReference
https://clerk.com/docs/reference/backend-api
📖
GettingStarted
https://clerk.com/docs/quickstarts/overview
📖
Authentication
https://clerk.com/docs/backend-requests/making/jwt-templates
📖
Documentation
https://clerk.com/docs
📖
Documentation
https://clerk.com/docs/webhooks/overview

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/clerk-com/refs/heads/main/openapi/clerk-com-organization-memberships-api-openapi.yml

Other Resources

🔗
SpectralRuleset
https://raw.githubusercontent.com/api-evangelist/clerk-com/refs/heads/main/rules/clerk-rules.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/clerk-com-organization-memberships-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

clerk-com-organization-memberships-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Clerk Backend Organization Memberships API
  x-logo:
    url: https://clerk.com/_next/image?url=%2Fimages%2Fclerk-logo.svg&w=96&q=75
    altText: Clerk docs
    href: https://clerk.com/docs
  contact:
    email: support@clerk.com
    name: Clerk Platform Team
    url: https://clerk.com/support
  description: 'The Clerk REST Backend API, meant to be accessed by backend servers.


    ### Versions


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

    Each version is identified by its release date, e.g. `2025-04-10`. For more information, please see Clerk API Versions.


    Please see https://clerk.com/docs for more information.'
  version: '2025-11-10'
  termsOfService: https://clerk.com/terms
  license:
    name: MIT
    url: https://github.com/clerk/openapi-specs/blob/main/LICENSE
servers:
- url: https://api.clerk.com/v1
security:
- bearerAuth: []
tags:
- name: Organization Memberships
  description: Manage member roles in an organization.
  externalDocs:
    url: https://clerk.com/docs/organizations/manage-member-roles
paths:
  /organizations/{organization_id}/memberships:
    post:
      operationId: CreateOrganizationMembership
      x-speakeasy-group: organizationMemberships
      x-speakeasy-name-override: create
      summary: Create a New Organization Membership
      description: 'Adds a user as a member to the given organization.

        Only users in the same instance as the organization can be added as members.


        This organization will be the user''s [active organization] (https://clerk.com/docs/organizations/overview#active-organization)

        the next time they create a session, presuming they don''t explicitly set a

        different organization as active before then.'
      tags:
      - Organization Memberships
      parameters:
      - in: path
        required: true
        name: organization_id
        schema:
          type: string
        description: The ID of the organization where the new membership will be created
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                user_id:
                  type: string
                  description: 'The ID of the user that will be added as a member in the organization.

                    The user needs to exist in the same instance as the organization and must not be a member of the given organization already.'
                role:
                  type: string
                  description: The role that the new member will have in the organization.
                public_metadata:
                  type:
                  - object
                  - 'null'
                  description: Metadata saved on the organization membership, that is visible to both your frontend and backend.
                  additionalProperties: true
                private_metadata:
                  type:
                  - object
                  - 'null'
                  description: Metadata saved on the organization membership that is only visible to your backend.
                  additionalProperties: true
              required:
              - user_id
              - role
      responses:
        '200':
          $ref: '#/components/responses/OrganizationMembership'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      operationId: ListOrganizationMemberships
      x-speakeasy-group: organizationMemberships
      x-speakeasy-name-override: list
      summary: Get a List of All Members of an Organization
      description: Retrieves all user memberships for the given organization
      tags:
      - Organization Memberships
      parameters:
      - in: path
        required: true
        name: organization_id
        schema:
          type: string
        description: The organization ID.
      - in: query
        required: false
        name: order_by
        description: 'Sorts organizations memberships by phone_number, email_address, created_at, first_name, last_name or username.

          By prepending one of those values with + or -, we can choose to sort in ascending (ASC) or descending (DESC) order."'
        schema:
          type: string
      - name: user_id
        in: query
        schema:
          type: array
          items:
            type: string
        description: 'Returns users with the user IDs specified. For each user ID, the `+` and `-` can be

          prepended to the ID, which denote whether the respective user ID should be included or

          excluded from the result set. Accepts up to 100 user IDs. Any user IDs not found are ignored.'
        required: false
      - name: email_address
        in: query
        schema:
          type: array
          items:
            type: string
        description: Returns users with the specified email addresses. Accepts up to 100 email addresses. Any email addresses not found are ignored.
        required: false
      - name: phone_number
        in: query
        schema:
          type: array
          items:
            type: string
        description: Returns users with the specified phone numbers. Accepts up to 100 phone numbers. Any phone numbers not found are ignored.
        required: false
      - name: username
        in: query
        schema:
          type: array
          items:
            type: string
        description: 'Returns users with the specified usernames.

          Accepts up to 100 usernames.

          Any usernames not found are ignored.'
        required: false
      - name: web3_wallet
        in: query
        schema:
          type: array
          items:
            type: string
        description: 'Returns users with the specified web3 wallet addresses.

          Accepts up to 100 web3 wallet addresses.

          Any web3 wallet addresses not found are ignored.'
        required: false
      - name: role
        in: query
        schema:
          type: array
          items:
            type: string
        description: Returns users with the specified roles. Accepts up to 100 roles. Any roles not found are ignored.
        required: false
      - name: query
        in: query
        description: 'Returns users that match the given query.

          For possible matches, we check the email addresses, phone numbers, usernames, web3 wallets, user IDs, first and last names.

          The query value doesn''t need to match the exact value you are looking for, it is capable of partial matches as well.'
        schema:
          type: string
        required: false
      - name: email_address_query
        in: query
        description: 'Returns users with emails that match the given query, via case-insensitive partial match.

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

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

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

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

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

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

          Example: use 1730160000000 to retrieve users who have been created after 2024-10-29.'
        example: 1730160000000
        schema:
          type: integer
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      responses:
        '200':
          $ref: '#/components/responses/OrganizationMemberships'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /organizations/{organization_id}/memberships/{user_id}:
    patch:
      operationId: UpdateOrganizationMembership
      x-speakeasy-group: organizationMemberships
      x-speakeasy-name-override: update
      summary: Update an Organization Membership
      description: Updates the properties of an existing organization membership
      tags:
      - Organization Memberships
      parameters:
      - in: path
        required: true
        name: organization_id
        schema:
          type: string
        description: The ID of the organization to which this membership belongs
      - in: path
        required: true
        name: user_id
        schema:
          type: string
        description: The ID of the user to which this membership belongs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                role:
                  type: string
                  description: The new role of the given membership.
              required:
              - role
      responses:
        '200':
          $ref: '#/components/responses/OrganizationMembership'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      operationId: DeleteOrganizationMembership
      x-speakeasy-group: organizationMemberships
      x-speakeasy-name-override: delete
      summary: Remove a Member from an Organization
      description: Removes the given membership from the organization
      tags:
      - Organization Memberships
      parameters:
      - in: path
        required: true
        name: organization_id
        schema:
          type: string
        description: The ID of the organization to which this membership belongs
      - in: path
        required: true
        name: user_id
        schema:
          type: string
        description: The ID of the user to which this membership belongs
      responses:
        '200':
          $ref: '#/components/responses/OrganizationMembership'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /organizations/{organization_id}/memberships/{user_id}/metadata:
    patch:
      operationId: UpdateOrganizationMembershipMetadata
      x-speakeasy-group: organizationMemberships
      x-speakeasy-name-override: updateMetadata
      summary: Merge and Update Organization Membership Metadata
      description: 'Update an organization membership''s metadata attributes by merging existing values with the provided parameters.

        Metadata values will be updated via a deep merge. Deep means that any nested JSON objects will be merged as well.

        You can remove metadata keys at any level by setting their value to `null`.'
      tags:
      - Organization Memberships
      parameters:
      - in: path
        required: true
        name: organization_id
        schema:
          type: string
        description: The ID of the organization to which this membership belongs
      - in: path
        required: true
        name: user_id
        schema:
          type: string
        description: The ID of the user to which this membership belongs
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                public_metadata:
                  type: object
                  description: 'Metadata saved on the organization membership, that is visible to both your frontend and backend.

                    The new object will be merged with the existing value.'
                  additionalProperties: true
                private_metadata:
                  type: object
                  description: 'Metadata saved on the organization membership that is only visible to your backend.

                    The new object will be merged with the existing value.'
                  additionalProperties: true
      responses:
        '200':
          $ref: '#/components/responses/OrganizationMembership'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /organization_memberships:
    get:
      operationId: InstanceGetOrganizationMemberships
      x-speakeasy-group: users
      x-speakeasy-name-override: getInstanceOrganizationMemberships
      summary: Get a List of All Organization Memberships Within an Instance
      description: Retrieves all organization user memberships for the given instance.
      tags:
      - Organization Memberships
      parameters:
      - name: order_by
        in: query
        required: false
        description: 'Sorts organizations memberships by phone_number, email_address, created_at, first_name, last_name or username.

          By prepending one of those values with + or -,

          we can choose to sort in ascending (ASC) or descending (DESC) order.'
        schema:
          type: string
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      responses:
        '200':
          $ref: '#/components/responses/OrganizationMemberships'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/ClerkErrors'
components:
  responses:
    AuthorizationInvalid:
      description: Authorization invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    ResourceNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    ClerkErrors:
      description: Request was not successful
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    OrganizationMembership:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OrganizationMembership'
    UnprocessableEntity:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    AuthenticationInvalid:
      description: Authentication invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    OrganizationMemberships:
      description: A list of organization memberships
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OrganizationMemberships'
  schemas:
    ClerkError:
      type: object
      properties:
        message:
          type: string
        long_message:
          type: string
        code:
          type: string
        meta:
          type: object
      required:
      - message
      - long_message
      - code
    OrganizationMembershipPublicUserData:
      description: An organization membership with public user data populated
      type: object
      additionalProperties: false
      properties:
        user_id:
          type: string
        first_name:
          type:
          - string
          - 'null'
        last_name:
          type:
          - string
          - 'null'
        profile_image_url:
          type:
          - string
          - 'null'
          deprecated: true
        image_url:
          type: string
        has_image:
          type: boolean
        identifier:
          type:
          - string
          - 'null'
        username:
          type:
          - string
          - 'null'
        banned:
          type: boolean
      required:
      - user_id
      - first_name
      - last_name
      - profile_image_url
      - image_url
      - has_image
    Organization:
      type: object
      properties:
        object:
          type: string
          enum:
          - organization
        id:
          type: string
        name:
          type: string
        slug:
          type: string
        image_url:
          type: string
        has_image:
          type: boolean
        members_count:
          type: integer
        missing_member_with_elevated_permissions:
          type: boolean
        pending_invitations_count:
          type: integer
        max_allowed_memberships:
          type: integer
        admin_delete_enabled:
          type: boolean
        public_metadata:
          type: object
          additionalProperties: true
        private_metadata:
          type: object
          additionalProperties: true
        created_by:
          type: string
        created_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation.

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

            '
        last_active_at:
          type: integer
          format: int64
          description: 'Unix timestamp of last activity.

            '
        role_set_key:
          type:
          - string
          - 'null'
          description: 'The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) assigned to this organization.

            '
      required:
      - object
      - id
      - name
      - slug
      - has_image
      - max_allowed_memberships
      - admin_delete_enabled
      - public_metadata
      - created_at
      - updated_at
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ClerkError'
        meta:
          type: object
        clerk_trace_id:
          type: string
      required:
      - errors
    OrganizationMembership:
      description: A user's membership in an organization
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          description: 'String representing the object''s type. Objects of the same type share the same value.

            '
          enum:
          - organization_membership
        role:
          type: string
        role_name:
          type: string
        permissions:
          type: array
          items:
            type: string
        public_metadata:
          type: object
          description: Metadata saved on the organization membership, accessible from both Frontend and Backend APIs
          additionalProperties: true
        private_metadata:
          type: object
          description: Metadata saved on the organization membership, accessible only from the Backend API
          additionalProperties: true
        organization:
          type: object
          allOf:
          - $ref: '#/components/schemas/Organization'
        public_user_data:
          $ref: '#/components/schemas/OrganizationMembershipPublicUserData'
        created_at:
          type: integer
          format: int64
          description: Unix timestamp of creation.
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp of last update.
      required:
      - object
      - id
      - role
      - permissions
      - public_metadata
      - created_at
      - updated_at
      - organization
    OrganizationMemberships:
      type: object
      additionalProperties: false
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationMembership'
        total_count:
          type: integer
          format: int64
          description: 'Total number of organization memberships

            '
      required:
      - data
      - total_count
  parameters:
    OffsetParameter:
      name: offset
      in: query
      description: 'Skip the first `offset` results when paginating.

        Needs to be an integer greater or equal to zero.

        To be used in conjunction with `limit`.'
      required: false
      schema:
        type: integer
        default: 0
        minimum: 0
    LimitParameter:
      name: limit
      in: query
      description: 'Applies a limit to the number of results returned.

        Can be used for paginating the results together with `offset`.'
      required: false
      schema:
        type: integer
        default: 10
        minimum: 1
        maximum: 500
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Secret key, obtained under "API Keys" in the Clerk Dashboard.
      bearerFormat: sk_<environment>_<secret value>
externalDocs:
  url: https://clerk.com/docs
x-speakeasy-retries:
  strategy: backoff
  backoff:
    initialInterval: 500
    maxInterval: 60000
    maxElapsedTime: 3600000
    exponent: 1.5
  statusCodes:
  - 5XX
  retryConnectionErrors: true