Clerk Organization Invitations API

openapi: 3.0.3
info:
  title: Clerk Backend Account Portal Organization Invitations 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: Organization Invitations
  description: Invite users to an organization.
  externalDocs:
    url: https://clerk.com/docs/organizations/invite-users
paths:
  /organization_invitations:
    get:
      operationId: ListInstanceOrganizationInvitations
      x-speakeasy-group: organizationInvitations
      x-speakeasy-name-override: getAll
      summary: Get a List of Organization Invitations for the Current Instance
      description: 'This request returns the list of organization invitations for the instance.

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

        You can filter them by providing the ''status'' query parameter, that accepts multiple values.

        You can change the order by providing the ''order'' query parameter, that accepts multiple values.

        You can filter by the invited user email address providing the `query` query parameter.

        The organization invitations are ordered by descending creation date by default.'
      tags:
      - Organization Invitations
      parameters:
      - in: query
        name: order_by
        required: false
        description: 'Allows to return organization invitations in a particular order.

          At the moment, you can order the returned organization invitations either by their `created_at` or `email_address`.

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

          For example, if you want organization invitations 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
      - in: query
        name: status
        description: Filter organization invitations based on their status
        required: false
        schema:
          type: string
          enum:
          - pending
          - accepted
          - revoked
          - expired
      - in: query
        required: false
        name: query
        description: Filter organization invitations based on their `email_address`
        schema:
          type: string
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      responses:
        '200':
          $ref: '#/components/responses/OrganizationInvitationsWithPublicOrganizationData'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/ClerkErrors'
        '500':
          $ref: '#/components/responses/ClerkErrors'
  /organizations/{organization_id}/invitations:
    post:
      operationId: CreateOrganizationInvitation
      x-speakeasy-group: organizationInvitations
      x-speakeasy-name-override: create
      summary: Create and Send an Organization Invitation
      description: 'Creates a new organization invitation and sends an email to the provided `email_address` with a link to accept the invitation and join the organization.

        You can specify the `role` for the invited organization member.


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


        The request body supports passing an optional `redirect_url` parameter.

        When the invited user clicks the link to accept the invitation, they will be redirected to the URL provided.

        Use this parameter to implement a custom invitation acceptance flow.


        You can specify the ID of the user that will send the invitation with the `inviter_user_id` parameter.

        That user must be a member with administrator privileges in the organization.

        Only "admin" members can create organization invitations.


        You can optionally provide public and private metadata for the organization invitation.

        The public metadata are visible by both the Frontend and the Backend whereas the private ones only by the Backend.

        When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership.'
      tags:
      - Organization Invitations
      parameters:
      - in: path
        required: true
        name: organization_id
        schema:
          type: string
        description: The ID of the organization for which to send the invitation
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email_address:
                  type: string
                  description: The email address of the new member that is going to be invited to the organization
                inviter_user_id:
                  type: string
                  nullable: true
                  description: 'The ID of the user that invites the new member to the organization.

                    Must be an administrator in the organization.'
                role:
                  type: string
                  description: The role of the new member in the organization
                public_metadata:
                  type: object
                  description: 'Metadata saved on the organization invitation, read-only from the Frontend API and fully accessible (read/write) from the Backend API.

                    When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership.'
                  additionalProperties: true
                  nullable: true
                private_metadata:
                  type: object
                  description: 'Metadata saved on the organization invitation, fully accessible (read/write) from the Backend API but not visible from the Frontend API.

                    When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership.'
                  additionalProperties: true
                  nullable: true
                redirect_url:
                  type: string
                  description: Optional URL that the invitee will be redirected to once they accept the invitation by clicking the join link in the invitation email.
                  nullable: true
                expires_in_days:
                  type: integer
                  description: The number of days the invitation will be valid for. By default, the invitation has a 30 days expire.
                  nullable: true
                  minimum: 1
                  maximum: 365
                notify:
                  type: boolean
                  description: 'Optional flag which denotes whether an email invitation should be sent to the given email address.

                    Defaults to `true`.'
                  nullable: true
                  default: true
              required:
              - email_address
              - role
      responses:
        '200':
          $ref: '#/components/responses/OrganizationInvitation'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '402':
          $ref: '#/components/responses/PaymentRequired'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
    get:
      operationId: ListOrganizationInvitations
      x-speakeasy-group: organizationInvitations
      x-speakeasy-name-override: list
      summary: Get a List of Organization Invitations
      description: 'This request returns the list of organization invitations.

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

        You can filter them by providing the ''status'' query parameter, that accepts multiple values.

        The organization invitations are ordered by descending creation date.

        Most recent invitations will be returned first.

        Any invitations created as a result of an Organization Domain are not included in the results.'
      tags:
      - Organization Invitations
      parameters:
      - in: path
        required: true
        name: organization_id
        schema:
          type: string
        description: The organization ID.
      - in: query
        name: status
        description: Filter organization invitations based on their status
        required: false
        schema:
          type: string
          enum:
          - pending
          - accepted
          - revoked
          - expired
      - in: query
        required: false
        name: email_address
        description: Returns organization invitations inviting the specified email address.
        schema:
          type: string
      - in: query
        name: order_by
        required: false
        description: 'Allows to return organization invitations in a particular order.

          You can order the returned organization invitations either by their `created_at` or `email_address`.

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

          For example, if you want organization invitations 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
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      responses:
        '200':
          $ref: '#/components/responses/OrganizationInvitations'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /organizations/{organization_id}/invitations/bulk:
    post:
      operationId: CreateOrganizationInvitationBulk
      x-speakeasy-group: organizationInvitations
      x-speakeasy-name-override: bulkCreate
      summary: Bulk Create and Send Organization Invitations
      description: 'Creates new organization invitations in bulk and sends out emails to the provided email addresses with a link to accept the invitation and join the organization.


        This endpoint is limited to a maximum of 10 invitations per API call. If you need to send more invitations, please make multiple requests.


        You can specify a different `role` for each invited organization member.

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

        The request body supports passing an optional `redirect_url` parameter for each invitation.

        When the invited user clicks the link to accept the invitation, they will be redirected to the provided URL.

        Use this parameter to implement a custom invitation acceptance flow.

        You can specify the ID of the user that will send the invitation with the `inviter_user_id` parameter. Each invitation

        can have a different inviter user.

        Inviter users must be members with administrator privileges in the organization.

        Only "admin" members can create organization invitations.

        You can optionally provide public and private metadata for each organization invitation. The public metadata are visible

        by both the Frontend and the Backend, whereas the private metadata are only visible by the Backend.

        When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership.'
      tags:
      - Organization Invitations
      parameters:
      - in: path
        required: true
        name: organization_id
        schema:
          type: string
        description: The organization ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              maxItems: 10
              items:
                type: object
                properties:
                  email_address:
                    type: string
                    description: The email address of the new member that is going to be invited to the organization
                  inviter_user_id:
                    type: string
                    nullable: true
                    description: 'The ID of the user that invites the new member to the organization.

                      Must be an administrator in the organization.'
                  role:
                    type: string
                    description: The role of the new member in the organization
                  public_metadata:
                    type: object
                    description: 'Metadata saved on the organization invitation, read-only from the Frontend API and fully accessible (read/write) from the Backend API.

                      When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership.'
                    additionalProperties: true
                    nullable: true
                  private_metadata:
                    type: object
                    description: 'Metadata saved on the organization invitation, fully accessible (read/write) from the Backend API but not visible from the Frontend API.

                      When the organization invitation is accepted, the metadata will be transferred to the newly created organization membership.'
                    additionalProperties: true
                    nullable: true
                  redirect_url:
                    type: string
                    description: Optional URL that the invitee will be redirected to once they accept the invitation by clicking the join link in the invitation email.
                    nullable: true
                  expires_in_days:
                    type: integer
                    description: The number of days the invitation will be valid for. By default, the invitation has a 30 days expire.
                    nullable: true
                    minimum: 1
                    maximum: 365
                  notify:
                    type: boolean
                    description: 'Optional flag which denotes whether an email invitation should be sent to the given email address.

                      Defaults to `true`.'
                    nullable: true
                    default: true
                required:
                - email_address
                - role
      responses:
        '200':
          $ref: '#/components/responses/OrganizationInvitations'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /organizations/{organization_id}/invitations/pending:
    get:
      deprecated: true
      operationId: ListPendingOrganizationInvitations
      x-speakeasy-group: organizationInvitations
      x-speakeasy-name-override: listPending
      summary: Get a List of Pending Organization Invitations
      description: 'This request returns the list of organization invitations with "pending" status.

        These are the organization invitations that can still be used to join the organization, but have not been accepted by the invited user yet.

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

        The organization invitations are ordered by descending creation date.

        Most recent invitations will be returned first.

        Any invitations created as a result of an Organization Domain are not included in the results.'
      tags:
      - Organization Invitations
      parameters:
      - in: path
        required: true
        name: organization_id
        schema:
          type: string
        description: The organization ID.
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      responses:
        '200':
          $ref: '#/components/responses/OrganizationInvitations'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
  /organizations/{organization_id}/invitations/{invitation_id}:
    get:
      operationId: GetOrganizationInvitation
      x-speakeasy-group: organizationInvitations
      x-speakeasy-name-override: get
      summary: Retrieve an Organization Invitation by ID
      description: Use this request to get an existing organization invitation by ID.
      tags:
      - Organization Invitations
      parameters:
      - in: path
        required: true
        name: organization_id
        schema:
          type: string
        description: The organization ID.
      - in: path
        required: true
        name: invitation_id
        schema:
          type: string
        description: The organization invitation ID.
      responses:
        '200':
          $ref: '#/components/responses/OrganizationInvitation'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
  /organizations/{organization_id}/invitations/{invitation_id}/revoke:
    post:
      operationId: RevokeOrganizationInvitation
      x-speakeasy-group: organizationInvitations
      x-speakeasy-name-override: revoke
      summary: Revoke a Pending Organization Invitation
      description: 'Use this request to revoke a previously issued organization invitation.

        Revoking an organization invitation makes it invalid; the invited user will no longer be able to join the organization with the revoked invitation.

        Only organization invitations with "pending" status can be revoked.

        The request accepts the `requesting_user_id` parameter to specify the user which revokes the invitation.

        Only users with "admin" role can revoke invitations.'
      tags:
      - Organization Invitations
      parameters:
      - in: path
        required: true
        name: organization_id
        schema:
          type: string
        description: The organization ID.
      - in: path
        required: true
        name: invitation_id
        schema:
          type: string
        description: The organization invitation ID.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                requesting_user_id:
                  type: string
                  nullable: true
                  description: 'The ID of the user that revokes the invitation.

                    Must be an administrator in the organization.'
      responses:
        '200':
          $ref: '#/components/responses/OrganizationInvitation'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/AuthorizationInvalid'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
components:
  responses:
    AuthorizationInvalid:
      description: Authorization invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    ClerkErrors:
      description: Request was not successful
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    OrganizationInvitation:
      description: An organization invitation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OrganizationInvitation'
    OrganizationInvitationsWithPublicOrganizationData:
      description: A list of organization invitations with public organization data
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OrganizationInvitationsWithPublicOrganizationData'
    ResourceNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    OrganizationInvitations:
      description: A list of organization invitations
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OrganizationInvitations'
    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'
  schemas:
    ClerkError:
      type: object
      properties:
        message:
          type: string
        long_message:
          type: string
        code:
          type: string
        meta:
          type: object
      required:
      - message
      - long_message
      - code
    OrganizationInvitationPublicOrganizationData:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        name:
          type: string
        slug:
          type: string
        image_url:
          type: string
        has_image:
          type: boolean
      required:
      - id
      - name
      - slug
      - has_image
    OrganizationInvitationsWithPublicOrganizationData:
      type: object
      additionalProperties: false
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationInvitationWithPublicOrganizationData'
        total_count:
          type: integer
          format: int64
          description: 'Total number of organization invitations

            '
      required:
      - data
      - total_count
    OrganizationInvitations:
      type: object
      additionalProperties: false
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/OrganizationInvitation'
        total_count:
          type: integer
          format: int64
          description: 'Total number of organization invitations

            '
      required:
      - data
      - total_count
    OrganizationInvitationWithPublicOrganizationData:
      description: An organization invitation with public organization data populated
      type: object
      allOf:
      - properties:
          object:
            type: string
            description: 'String representing the object''s type. Objects of the same type share the same value.

              '
            enum:
            - organization_invitation
          id:
            type: string
          email_address:
            type: string
          role:
            type: string
          role_name:
            type: string
          organization_id:
            type: string
          inviter_id:
            type: string
            nullable: true
          public_inviter_data:
            $ref: '#/components/schemas/OrganizationInvitationPublicUserData'
          status:
            type: string
          public_metadata:
            type: object
            additionalProperties: true
          private_metadata:
            type: object
            additionalProperties: true
          url:
            type: string
            nullable: true
          expires_at:
            type: integer
            format: int64
            nullable: true
            description: Unix timestamp of expiration.
          created_at:
            type: integer
            format: int64
            description: Unix timestamp of creation.
          updated_at:
            type: integer
            format: int64
            description: Unix timestamp of last update.
      - properties:
          public_organization_data:
            $ref: '#/components/schemas/OrganizationInvitationPublicOrganizationData'
      required:
      - object
      - id
      - email_address
      - role
      - role_name
      - public_metadata
      - url
      - expires_at
      - created_at
      - updated_at
      - inviter_id
      - public_inviter_data
    OrganizationInvitation:
      description: An organization invitation
      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:
          - organization_invitation
        id:
          type: string
        email_address:
          type: string
        role:
          type: string
        role_name:
          type: string
        organization_id:
          type: string
        inviter_id:
          type: string
          nullable: true
        public_inviter_data:
          $ref: '#/components/schemas/OrganizationInvitationPublicUserData'
        status:
          type: string
        public_metadata:
          type: object
          additionalProperties: true
        private_metadata:
          type: object
          additionalProperties: true
        url:
          type: string
          nullable: true
        expires_at:
          type: integer
          format: int64
          nullable: true
          description: Unix timestamp of expiration.
        created_at:
          type: integer
          format: int64
          description: Unix timestamp of creation.
        updated_at:
          type: integer
          format: int64
          description: Unix timestamp of last update.
      required:
      - object
      - id
      - email_address
      - role
      - role_name
      - public_metadata
      - url
      - expires_at
      - created_at
      - updated_at
      - inviter_id
      - public_inviter_data
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ClerkError'
        meta:
          type: object
        clerk_trace_id:
          type: string
      required:
      - errors
    OrganizationInvitationPublicUserData:
      description: An organization inviter's public user data
      type: object
      additionalProperties: false
      nullable: true
      properties:
        user_id:
          type: string
          nullable: false
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        image_url:
          type: string
        has_image:
          type: boolean
        identifier:
          type: string
      required:
      - user_id
      - first_name
      - last_name
      - image_url
      - has_image
      - identifier
  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