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__ 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