Clerk Organizations API

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


    ### Versions


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

    Each version is identified by its release date, e.g. `2025-04-10`. For more information, please see [Clerk API Versions](https://clerk.com/docs/versioning/available-versions).


    Please see https://clerk.com/docs for more information.'
  version: '2025-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: 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
paths:
  /organizations:
    get:
      operationId: ListOrganizations
      x-speakeasy-group: organizations
      x-speakeasy-name-override: list
      summary: Get a List of Organizations for an Instance
      description: 'This request returns the list of organizations for an instance.

        Results can be paginated using the optional `limit` and `offset` query parameters.

        The organizations are ordered by descending creation date.

        Most recent organizations will be returned first.'
      tags:
      - Organizations
      parameters:
      - in: query
        required: false
        name: include_members_count
        description: Flag to denote whether the member counts of each organization should be included in the response or not.
        schema:
          type: boolean
      - in: query
        required: false
        name: include_missing_member_with_elevated_permissions
        description: Flag to denote whether or not to include a member with elevated permissions who is not currently a member of the organization.
        schema:
          type: boolean
      - in: query
        required: false
        name: query
        description: 'Returns organizations with ID, name, or slug that match the given query.

          Uses exact match for organization ID and partial match for name and slug.'
        schema:
          type: string
      - in: query
        name: user_id
        description: 'Returns organizations that include any of the specified user IDs as members. Any user IDs not found are ignored.

          For each user ID, the `+` and `-` can be prepended to the ID, which denote whether the

          respective organization should be included or excluded from the result set.'
        schema:
          type: array
          items:
            type: string
        required: false
      - in: query
        name: organization_id
        description: 'Returns organizations with the organization IDs specified. Any organization IDs not found are ignored.

          For each organization ID, the `+` and `-` can be prepended to the ID, which denote whether the

          respective organization should be included or excluded from the result set. Accepts up to 100 organization IDs.

          Example: ?organization_id=+org_1&organization_id=-org_2'
        schema:
          type: array
          items:
            type: string
        required: false
      - in: query
        name: order_by
        description: 'Allows to return organizations in a particular order.

          At the moment, you can order the returned organizations either by their `name`, `created_at` or `members_count`.

          In order to specify the direction, you can use the `+/-` symbols prepended in the property to order by.

          For example, if you want organizations to be returned in descending order according to their `created_at` property, you can use `-created_at`.

          If you don''t use `+` or `-`, then `+` is implied.

          Defaults to `-created_at`.'
        schema:
          type: string
          default: -created_at
        required: false
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      responses:
        '200':
          $ref: '#/components/responses/Organizations'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    post:
      operationId: CreateOrganization
      x-speakeasy-group: organizations
      x-speakeasy-name-override: create
      summary: Create an Organization
      description: 'Creates a new organization with the given name for an instance.

        You can specify an optional slug for the new organization.

        If provided, the organization slug can contain only lowercase alphanumeric characters (letters and digits) and the dash "-".

        Organization slugs must be unique for the instance.

        You can provide additional metadata for the organization and set any custom attribute you want.

        Organizations support private and public metadata.

        Private metadata can only be accessed from the Backend API.

        Public metadata can be accessed from the Backend API, and are read-only from the Frontend API.

        The `created_by` user will see this as their [active organization](https://clerk.com/docs/organizations/overview#active-organization)

        the next time they create a session, presuming they don''t explicitly set a different organization as active before then.'
      tags:
      - Organizations
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: 'The name of the new organization.

                    May not contain URLs or HTML.

                    Max length: 256'
                created_by:
                  type: string
                  description: The ID of the User who will become the administrator for the new organization
                  nullable: true
                private_metadata:
                  type: object
                  description: Metadata saved on the organization, accessible only from the Backend API
                  additionalProperties: true
                  nullable: true
                public_metadata:
                  type: object
                  description: Metadata saved on the organization, read-only from the Frontend API and fully accessible (read/write) from the Backend API
                  additionalProperties: true
                  nullable: true
                slug:
                  type: string
                  description: 'A slug for the new organization.

                    Can contain only lowercase alphanumeric characters and the dash "-".

                    Must be unique for the instance.

                    This field should only be included when slugs are enabled in the organization settings, refer to our [documentation](https://clerk.com/docs/guides/organizations/overview#organization-slugs).'
                  nullable: true
                max_allowed_memberships:
                  type: integer
                  minimum: 0
                  description: The maximum number of memberships allowed for this organization
                  nullable: true
                created_at:
                  type: string
                  description: A custom date/time denoting _when_ the organization was created, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`).
                  nullable: true
                role_set_key:
                  type: string
                  description: The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) to assign to this organization.
                  nullable: true
              required:
              - name
      responses:
        '200':
          $ref: '#/components/responses/Organization'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /organizations/{organization_id}:
    get:
      operationId: GetOrganization
      x-speakeasy-group: organizations
      x-speakeasy-name-override: get
      summary: Retrieve an Organization by ID or Slug
      description: Fetches the organization whose ID or slug matches the provided `id_or_slug` URL query parameter.
      tags:
      - Organizations
      parameters:
      - in: path
        name: organization_id
        required: true
        schema:
          type: string
        description: The ID or slug of the organization
      - in: query
        required: false
        name: include_members_count
        description: Flag to denote whether or not the organization's members count should be included in the response.
        schema:
          type: boolean
      - in: query
        required: false
        name: include_missing_member_with_elevated_permissions
        description: Flag to denote whether or not to include a member with elevated permissions who is not currently a member of the organization.
        schema:
          type: boolean
      responses:
        '200':
          $ref: '#/components/responses/Organization'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
    patch:
      operationId: UpdateOrganization
      x-speakeasy-group: organizations
      x-speakeasy-name-override: update
      summary: Update an Organization
      description: Updates an existing organization
      tags:
      - Organizations
      parameters:
      - in: path
        name: organization_id
        required: true
        schema:
          type: string
        description: The ID of the organization to update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                public_metadata:
                  type: object
                  description: Metadata saved on the organization, that is visible to both your frontend and backend.
                  additionalProperties: true
                  nullable: true
                private_metadata:
                  type: object
                  description: Metadata saved on the organization that is only visible to your backend.
                  additionalProperties: true
                  nullable: true
                name:
                  type: string
                  description: 'The new name of the organization.

                    May not contain URLs or HTML.

                    Max length: 256'
                  nullable: true
                slug:
                  type: string
                  description: The new slug of the organization, which needs to be unique in the instance
                  nullable: true
                max_allowed_memberships:
                  type: integer
                  minimum: 0
                  description: The maximum number of memberships allowed for this organization
                  nullable: true
                admin_delete_enabled:
                  type: boolean
                  description: If true, an admin can delete this organization with the Frontend API.
                  nullable: true
                created_at:
                  type: string
                  description: A custom date/time denoting _when_ the organization was created, specified in RFC3339 format (e.g. `2012-10-20T07:15:20.902Z`).
                  nullable: true
                role_set_key:
                  type: string
                  description: The key of the [role set](https://clerk.com/docs/guides/organizations/control-access/role-sets) to assign to this organization.
                  nullable: true
      responses:
        '200':
          $ref: '#/components/responses/Organization'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '402':
          $ref: '#/components/responses/ResourceNotFound'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    delete:
      operationId: DeleteOrganization
      x-speakeasy-group: organizations
      x-speakeasy-name-override: delete
      summary: Delete an Organization
      description: 'Deletes the given organization.

        Please note that deleting an organization will also delete all memberships and invitations.

        This is not reversible.


        After the organization is deleted, any user''s active sessions that contain the deleted

        organization will be cleared.'
      tags:
      - Organizations
      parameters:
      - in: path
        name: organization_id
        required: true
        schema:
          type: string
        description: The ID of the organization to delete
      responses:
        '200':
          $ref: '#/components/responses/DeletedObject'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
  /organizations/{organization_id}/metadata:
    patch:
      operationId: MergeOrganizationMetadata
      x-speakeasy-group: organizations
      x-speakeasy-name-override: mergeMetadata
      summary: Merge and Update Metadata for an Organization
      description: 'Update organization metadata attributes by merging existing values with the provided parameters.

        Metadata values will be updated via a deep merge.

        Deep meaning that any nested JSON objects will be merged as well.

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

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

                    The new object will be merged with the existing value.'
                  additionalProperties: true
      responses:
        '200':
          $ref: '#/components/responses/Organization'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /organizations/{organization_id}/logo:
    put:
      operationId: UploadOrganizationLogo
      x-speakeasy-group: organizations
      x-speakeasy-name-override: uploadLogo
      summary: Upload a Logo for the Organization
      description: 'Set or replace an organization''s logo, by uploading an image file.

        This endpoint uses the `multipart/form-data` request content type and accepts a file of image type.

        The file size cannot exceed 10MB.

        Only the following file content types are supported: `image/jpeg`, `image/png`, `image/gif`, `image/webp`.'
      tags:
      - Organizations
      parameters:
      - name: organization_id
        in: path
        description: The ID of the organization for which to upload a logo
        required: true
        schema:
          type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                uploader_user_id:
                  type: string
                  description: The ID of the user that will be credited with the image upload.
                file:
                  type: string
                  format: binary
              required:
              - file
      responses:
        '200':
          $ref: '#/components/responses/OrganizationWithLogo'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '413':
          $ref: '#/components/responses/ClerkErrors'
    delete:
      operationId: DeleteOrganizationLogo
      x-speakeasy-group: organizations
      x-speakeasy-name-override: deleteLogo
      summary: Delete the Organization's Logo.
      description: Delete the organization's logo.
      tags:
      - Organizations
      parameters:
      - name: organization_id
        in: path
        description: The ID of the organization for which the logo will be deleted.
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/Organization'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
  /organizations/{organization_id}/billing/subscription:
    get:
      operationId: GetOrganizationBillingSubscription
      x-speakeasy-group: organizations
      x-speakeasy-name-override: getBillingSubscription
      summary: Retrieve an Organization's Billing Subscription
      description: 'Retrieves the billing subscription for the specified organization.

        This includes subscription details, active plans, billing information, and payment status.

        The subscription contains subscription items which represent the individual plans the organization is subscribed to.'
      tags:
      - Organizations
      parameters:
      - in: path
        name: organization_id
        required: true
        schema:
          type: string
        description: The ID of the organization whose subscription to retrieve
      responses:
        '200':
          $ref: '#/components/responses/CommerceSubscription'
        '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'
        '500':
          $ref: '#/components/responses/ClerkErrors'
  /organizations/{organization_id}/billing/credits:
    get:
      operationId: GetOrganizationBillingCreditBalance
      x-speakeasy-group: organizations
      x-speakeasy-name-override: getBillingCreditBalance
      summary: Retrieve an Organization's Credit Balance
      description: 'Retrieves the current credit balance for the specified organization.

        Credits can be applied during checkout to reduce the charge or automatically applied to upcoming recurring charges.'
      tags:
      - Organizations
      parameters:
      - in: path
        name: organization_id
        required: true
        schema:
          type: string
        description: The ID of the organization whose credit balance to retrieve
      responses:
        '200':
          $ref: '#/components/responses/CommerceCreditBalance'
        '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'
        '500':
          $ref: '#/components/responses/ClerkErrors'
    post:
      operationId: AdjustOrganizationBillingCreditBalance
      x-speakeasy-group: organizations
      x-speakeasy-name-override: adjustBillingCreditBalance
      summary: Adjust an Organization's Credit Balance
      description: 'Increases or decreases the credit balance for the specified organization.

        Each adjustment is recorded as a ledger entry. The idempotency_key parameter

        ensures that duplicate requests are safely handled.'
      tags:
      - Organizations
      parameters:
      - in: path
        name: organization_id
        required: true
        schema:
          type: string
        description: The ID of the organization whose credit balance to adjust
      requestBody:
        description: Parameters for the credit balance adjustment
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdjustCreditBalanceRequest'
      responses:
        '200':
          $ref: '#/components/responses/CommerceCreditLedger'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/AuthenticationInvalid'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '409':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/ClerkErrors'
components:
  responses:
    AuthorizationInvalid:
      description: Authorization invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    CommerceCreditBalance:
      description: A payer's credit balance.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommerceCreditBalanceResponse'
    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'
    CommerceCreditLedger:
      description: A credit ledger entry.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommerceCreditLedgerResponse'
    UnprocessableEntity:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    PaymentRequired:
      description: Payment required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    Organization:
      description: An organization
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Organization'
    Organizations:
      description: A list of organizations
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Organizations'
    CommerceSubscription:
      description: A commerce subscription.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CommerceSubscription'
    ResourceNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    DeletedObject:
      description: Deleted Object
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/DeletedObject'
    OrganizationWithLogo:
      description: An organization with a logo URL.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OrganizationWithLogo'
  schemas:
    CommerceProrationCreditDetailResponse:
      type: object
      additionalProperties: false
      properties:
        amount:
          $ref: '#/components/schemas/CommerceMoneyResponse'
        cycle_days_remaining:
          type: integer
          format: int64
        cycle_days_total:
          type: integer
          format: int64
        cycle_remaining_percent:
          type: number
          format: double
      required:
      - amount
      - cycle_days_remaining
      - cycle_days_total
      - cycle_remaining_percent
    CommerceSubscription:
      type: object
      additionalProperties: false
      required:
      - object
      - id
      - instance_id
      - status
      - payer_id
      - created_at
      - updated_at
      - active_at
      - past_due_at
      - subscription_items
      properties:
        object:
          type: string
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - commerce_subscription
        id:
          type: string
          description: Unique identifier for the commerce subscription.
        instance_id:
          type: string
          description: The ID of the instance this subscription belongs to.
        status:
          type: string
          description: The current status of the subscription.
          enum:
          - active
          - past_due
          - canceled
          - ended
          - abandoned
          - incomplete
        payer_id:
          type: string
          description: The ID of the payer for this subscription.
        created_at:
          type: integer
          format: int64
          description: Unix timestamp (milliseconds) of creation.
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp (milliseconds) of last update.
        active_at:
          type: integer
          format: int64
          nullable: true
          description: Unix timestamp (milliseconds) when the subscription became active.
        past_due_at:
          type: integer
          format: int64
          nullable: true
          description: Unix timestamp (milliseconds) when the subscription became past due.
        subscription_items:
          type: array
          items:
            $ref: '#/components/schemas/CommerceSubscriptionItem'
          description: Array of subscription items in this subscription.
        next_payment:
          $ref: '#/components/schemas/CommerceSubscriptionNextPayment'
          description: Information about the next scheduled payment.
        eligible_for_free_trial:
          type: boolean
          description: Whether the payer is eligible for a free trial.
    CommerceCreditBalanceResponse:
      type: object
      additionalProperties: false
      required:
      - object
      - balance
      properties:
        object:
          type: string
          description: String representing the object's type. Always "commerce_credit_balance".
        balance:
          allOf:
          - $ref: '#/components/schemas/CommerceMoneyResponse'
          nullable: true
          description: The current credit balance. Null when the payer has never had credits.
    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
    ClerkError:
      type: object
      properties:
        message:
          type: string
        long_message:
          type: string
        code:
          type: string
        meta:
          type: object
      required:
      - message
      - long_message
      - code
    CommercePaymentMethodResponse:
      type: object
      additionalProperties: false
      required:
      - object
      - id
      - payer_id
      - payment_type
      - gateway
      - gateway_external_id
      - gateway_external_account_id
      - last4
      - status
      - card_type
      properties:
        object:
          type: string
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - commerce_payment_method
        id:
          type: string
          description: Unique identifier for the payment method.
        payer_id:
          type: string
          description: Unique identifier for the payer.
        payment_type:
          type: string
          description: The payment method type.
          enum:
          - card
          - link
        is_default:
          type: boolean
          description: Whether this is the default payment method for the payer.
        gateway:
          type: string
          description: The payment gateway.
        gateway_external_id:
          type: string
          description: External ID in the payment gateway.
        gateway_external_account_id:
          type: string
          nullable: true
          description: External account ID in the payment gateway.
        last4:
          type: string
          description: Last 4 digits of the card (for card payment methods).
          nullable: true
        status:
          type: string
          description: Status of the payment method.
          enum:
          - active
          - disconnected
        wallet_type:
          type: string
          description: Type of wallet (if applicable).
          nullable: true
        card_type:
          type: string
          description: Type of card (if applicable).
          nullable: true
        expiry_year:
          type: integer
          description: Card expiration year (for card payment methods).
          nullable: true
        expiry_month:
          type: integer
          description: Card expiration month (for card payment methods).
          nullable: true
        created_at:
          type: integer
          format: int64
          description: Unix timestamp (in milliseconds) when the payment method was created.
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp (in milliseconds) when the payment method was last updated.
        is_removable:
          type: boolean
          description: Whether this payment method can be removed.
    CommercePlanUnitPrice:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          description: Name of the billable unit (for example, seats)
        block_size:
          type: integer
          format: int64
          description: Number of units included in each pricing block
        tiers:
          type: array
          items:
            $ref: '#/components/schemas/CommercePlanUnitPriceTier'
          description: Tiered pricing configuration for this unit
      required:
      - name
      - block_size
      - tiers
    CommercePlanUnitPriceTier:
      type: object
      additionalProperties: false
      properties:
        starts_at_block:
          type: integer
          format: int64
          description: Start block (inclusive) for this tier
        ends_after_block:
          type: integer
          format: int64
          nullable: true
          description: End block (inclusive) for this tier; null means unlimited
        fee_per_block:
          $ref: '#/components/schemas/CommerceMoneyResponse'
          description: Price charged per block in this tier
      required:
      - starts_at_block
      - fee_per_block
    CommercePerUnitTotal:
      type: object
      additionalProperties: false
      properties:
        name:
          type: string
          description: Name of the billable unit (for example, seats)
        block_size:
          type: integer
          format: int64
          description: Number of units included in each pricing block
        tiers:
          

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