Clerk Invitations API

openapi: 3.2.0
info:
  title: Clerk Com Invitations API
  termsOfService: https://clerk.com/terms
  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
  version: '1.0'
  description: 'Operations tagged Invitations across 2 of this provider''s published API definitions: clerk-backend-api-openapi.yml, clerk-frontend-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.clerk.com/v1
- url: https://{domain}.clerk.accounts.dev
  variables:
    domain:
      default: example-destined-camel-13
      description: Your Development Instance Frontend API Domain.
tags:
- name: Invitations
  description: Invitations allow you to invite someone to sign up to your application, via email.
  externalDocs:
    url: https://clerk.com/docs/authentication/invitations
paths:
  /invitations:
    post:
      operationId: CreateInvitation
      x-speakeasy-group: invitations
      x-speakeasy-name-override: create
      summary: Create an Invitation
      description: 'Creates a new invitation for the given email address and sends the invitation email.

        Keep in mind that you cannot create an invitation if there is already one for the given email address.

        Also, trying to create an invitation for an email address that already exists in your application will result to an error.'
      tags:
      - Invitations
      requestBody:
        description: Required parameters
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                email_address:
                  type: string
                  description: The email address the invitation will be sent to
                public_metadata:
                  type: object
                  description: 'Metadata that will be attached to the newly created invitation.

                    The value of this property should be a well-formed JSON object.

                    Once the user accepts the invitation and signs up, these metadata will end up in the user''s public metadata.'
                  additionalProperties: true
                redirect_url:
                  type: string
                  description: 'Optional URL which specifies where to redirect the user once they click the invitation link.

                    This is only required if you have implemented a [custom flow](https://clerk.com/docs/authentication/invitations#custom-flow) and you''re not using Clerk Hosted Pages or Clerk Components.'
                notify:
                  type:
                  - boolean
                  - 'null'
                  description: 'Optional flag which denotes whether an email invitation should be sent to the given email address.

                    Defaults to `true`.'
                  default: true
                ignore_existing:
                  type:
                  - boolean
                  - 'null'
                  description: Whether an invitation should be created if there is already an existing invitation for this email address, or it's claimed by another user.
                  default: false
                expires_in_days:
                  type:
                  - integer
                  - 'null'
                  description: The number of days the invitation will be valid for. By default, the invitation expires after 30 days.
                  minimum: 1
                  maximum: 365
                template_slug:
                  type: string
                  enum:
                  - invitation
                  - waitlist_invitation
                  description: The slug of the email template to use for the invitation email.
              required:
              - email_address
      responses:
        '200':
          $ref: '#/components/responses/Invitation'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
      - bearerAuth: []
    get:
      summary: List All Invitations
      x-speakeasy-group: invitations
      x-speakeasy-name-override: list
      description: Returns all non-revoked invitations for your application, sorted by creation date
      operationId: ListInvitations
      parameters:
      - in: query
        name: status
        required: false
        description: Filter invitations based on their status
        schema:
          type: string
          enum:
          - pending
          - accepted
          - revoked
          - expired
      - in: query
        required: false
        name: query
        description: Filter invitations based on their `email_address` or `id`
        schema:
          type: string
      - name: order_by
        in: query
        required: false
        description: 'Allows to return invitations in a particular order.

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

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

          For example, if you want 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/Paginated'
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      tags:
      - Invitations
      responses:
        '200':
          $ref: '#/components/responses/Invitation.List'
      security:
      - bearerAuth: []
    servers:
    - url: https://api.clerk.com/v1
  /invitations/bulk:
    post:
      operationId: CreateBulkInvitations
      x-speakeasy-group: invitations
      x-speakeasy-name-override: bulkCreate
      summary: Create Multiple Invitations
      description: 'Use this API operation to create multiple invitations for the provided email addresses. You can choose to send the

        invitations as emails by setting the `notify` parameter to `true`. There cannot be an existing invitation for any

        of the email addresses you provide unless you set `ignore_existing` to `true` for specific email addresses. Please

        note that there must be no existing user for any of the email addresses you provide, and this rule cannot be bypassed.


        This endpoint is limited to a maximum of 10 invitations per API call. If you need to send more invitations, please make multiple requests.'
      tags:
      - Invitations
      requestBody:
        description: Required parameters
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              maxItems: 10
              items:
                type: object
                additionalProperties: false
                properties:
                  email_address:
                    type: string
                    description: The email address the invitation will be sent to
                  public_metadata:
                    type:
                    - object
                    - 'null'
                    description: 'Metadata that will be attached to the newly created invitation.

                      The value of this property should be a well-formed JSON object.

                      Once the user accepts the invitation and signs up, these metadata will end up in the user''s public metadata.'
                    additionalProperties: true
                  redirect_url:
                    type:
                    - string
                    - 'null'
                    description: The URL where the user is redirected upon visiting the invitation link, where they can accept the invitation. Required if you have implemented a [custom flow for handling application invitations](/docs/custom-flows/invitations).
                  notify:
                    type:
                    - boolean
                    - 'null'
                    description: 'Optional flag which denotes whether an email invitation should be sent to the given email address.

                      Defaults to true.'
                    default: true
                  ignore_existing:
                    type:
                    - boolean
                    - 'null'
                    description: 'Whether an invitation should be created if there is already an existing invitation for this email

                      address, or it''s claimed by another user.'
                    default: false
                  expires_in_days:
                    type:
                    - integer
                    - 'null'
                    description: The number of days the invitation will be valid for. By default, the invitation expires after 30 days.
                    minimum: 1
                    maximum: 365
                  template_slug:
                    type: string
                    enum:
                    - invitation
                    - waitlist_invitation
                    description: The slug of the email template to use for the invitation email.
                    default: invitation
                required:
                - email_address
      responses:
        '200':
          $ref: '#/components/responses/Invitation.List'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
      security:
      - bearerAuth: []
    servers:
    - url: https://api.clerk.com/v1
  /invitations/{invitation_id}/revoke:
    post:
      operationId: RevokeInvitation
      x-speakeasy-group: invitations
      x-speakeasy-name-override: revoke
      summary: Revokes an Invitation
      description: 'Revokes the given invitation.

        Revoking an invitation will prevent the user from using the invitation link that was sent to them.

        However, it doesn''t prevent the user from signing up if they follow the sign up flow.

        Only active (i.e. non-revoked) invitations can be revoked.'
      tags:
      - Invitations
      parameters:
      - name: invitation_id
        in: path
        description: The ID of the invitation to be revoked
        required: true
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/Invitation.Revoked'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
      security:
      - bearerAuth: []
    servers:
    - url: https://api.clerk.com/v1
  /v1/organizations/{organization_id}/invitations:
    post:
      summary: Create Organization Invitation
      description: 'Create an invitation for a user to join an organization.


        The current user must have permissions to manage the members of the organization.'
      operationId: createOrganizationInvitations
      tags:
      - Invitations
      parameters:
      - in: path
        name: organization_id
        required: true
        schema:
          type: string
        description: The ID of the organization for which the invitation will be created.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              additionalProperties: false
              properties:
                email_address:
                  type: string
                  description: The email address the invitation will be sent to.
                role:
                  type: string
                  description: 'The role that will be assigned to the user after joining.

                    This can be one of the predefined roles (`org:admin`, `org:basic_member`) or a custom role.'
              required:
              - email_address
              - role
      responses:
        '200':
          $ref: '#/components/responses/Client.ClientWrappedOrganizationInvitation'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/ClerkErrors'
      security:
      - {}
      - DevBrowser: []
      - ProductionBrowser: []
      - ProductionNativeApp: []
        ProductionNativeFlag: []
    get:
      summary: Get All Organization Invitations
      description: 'Retrieve all invitations for an organization.


        The current user must have permissions to manage the members of the organization.'
      operationId: getOrganizationInvitations
      tags:
      - Invitations
      parameters:
      - $ref: '#/components/parameters/LimitParameter'
      - $ref: '#/components/parameters/OffsetParameter'
      - in: path
        name: organization_id
        required: true
        schema:
          type: string
        description: The ID of the organization for which the invitation will be retrieved.
      - in: query
        name: status
        required: false
        schema:
          type: string
          enum:
          - pending
          - accepted
          - revoked
          - expired
          - invalid
          - completed
      responses:
        '200':
          $ref: '#/components/responses/Client.ClientWrappedOrganizationInvitations'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/ClerkErrors'
      security:
      - {}
      - DevBrowser: []
      - ProductionBrowser: []
      - ProductionNativeApp: []
        ProductionNativeFlag: []
    servers:
    - url: https://{domain}.clerk.accounts.dev
      variables:
        domain:
          default: example-destined-camel-13
          description: Your Development Instance Frontend API Domain.
  /v1/organizations/{organization_id}/invitations/bulk:
    post:
      summary: Bulk Create Organization Invitations
      description: 'Create an invitation for a user to join an organization.


        The current user must have permissions to manage the members of the organization.'
      operationId: bulkCreateOrganizationInvitations
      tags:
      - Invitations
      parameters:
      - in: path
        name: organization_id
        required: true
        schema:
          type: string
        description: The ID of the organization for which the invitations will be created.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              additionalProperties: false
              properties:
                email_address:
                  type: array
                  description: An array of email addresses the invitations will be sent to.
                  items:
                    type: string
                role:
                  type: string
                  description: 'The role that will be assigned to each of the users after joining.

                    This can be one of the predefined roles (`org:admin`, `org:basic_member`) or a custom role.'
              required:
              - email_address
              - role
      responses:
        '200':
          $ref: '#/components/responses/Client.ClientWrappedOrganizationInvitations'
        '400':
          $ref: '#/components/responses/ClerkErrors'
        '401':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/ClerkErrors'
      security:
      - {}
      - DevBrowser: []
      - ProductionBrowser: []
      - ProductionNativeApp: []
        ProductionNativeFlag: []
    servers:
    - url: https://{domain}.clerk.accounts.dev
      variables:
        domain:
          default: example-destined-camel-13
          description: Your Development Instance Frontend API Domain.
  /v1/organizations/{organization_id}/invitations/pending:
    get:
      summary: Get All Pending Organization Invitations
      deprecated: true
      description: 'Get a list of pending invitations for an organization.


        This endpoint is deprecated. Instead use the `/v1/organizations/{organization_id}/invitations`

        with a query parameter of `status=pending`.'
      operationId: getAllPendingOrganizationInvitations
      tags:
      - Invitations
      parameters:
      - in: path
        name: organization_id
        required: true
        schema:
          type: string
        description: The ID of the organization for which the invitations will be retrieved.
      responses:
        '200':
          $ref: '#/components/responses/Client.ClientWrappedOrganizationInvitations'
        '401':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '422':
          $ref: '#/components/responses/ClerkErrors'
      security:
      - {}
      - DevBrowser: []
      - ProductionBrowser: []
      - ProductionNativeApp: []
        ProductionNativeFlag: []
    servers:
    - url: https://{domain}.clerk.accounts.dev
      variables:
        domain:
          default: example-destined-camel-13
          description: Your Development Instance Frontend API Domain.
  /v1/organizations/{organization_id}/invitations/{invitation_id}/revoke:
    post:
      summary: Revoke Pending Organization Invitation
      description: 'Revoke a pending organization invitation.


        The current user must have permissions to manage the members of the organization.'
      operationId: revokePendingOrganizationInvitation
      tags:
      - Invitations
      parameters:
      - in: path
        name: organization_id
        required: true
        schema:
          type: string
        description: The ID of the organization for which the invitations will be retrieved.
      - in: path
        name: invitation_id
        required: true
        schema:
          type: string
        description: The ID of the invitation to revoke.
      responses:
        '200':
          $ref: '#/components/responses/Client.ClientWrappedOrganizationInvitation'
        '401':
          $ref: '#/components/responses/ClerkErrors'
        '403':
          $ref: '#/components/responses/ClerkErrors'
        '404':
          $ref: '#/components/responses/ClerkErrors'
      security:
      - {}
      - DevBrowser: []
      - ProductionBrowser: []
      - ProductionNativeApp: []
        ProductionNativeFlag: []
    servers:
    - url: https://{domain}.clerk.accounts.dev
      variables:
        domain:
          default: example-destined-camel-13
          description: Your Development Instance Frontend API Domain.
components:
  responses:
    ResourceNotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    Invitation:
      description: Success
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Invitation'
    ClerkErrors:
      description: Request was not successful
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    Invitation.Revoked:
      description: Success
      content:
        application/json:
          schema:
            allOf:
            - $ref: '#/components/schemas/Invitation'
            - type: object
              properties:
                revoked:
                  type: boolean
                  enum:
                  - true
                  example: true
                status:
                  type: string
                  enum:
                  - revoked
                  example: revoked
    Invitation.List:
      description: List of invitations
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Invitation'
    UnprocessableEntity:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ClerkErrors'
    Client.ClientWrappedOrganizationInvitation:
      description: Returns the response for Client wrapped OrganizationInvitation object.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Client.ClientWrappedOrganizationInvitation'
    Client.ClientWrappedOrganizationInvitations:
      description: Returns the response for Client wrapped array of OrganizationInvitation objects.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Client.ClientWrappedOrganizationInvitations'
  schemas:
    ClerkError:
      type: object
      properties:
        message:
          type: string
        long_message:
          type: string
        code:
          type: string
        meta:
          type: object
      required:
      - message
      - long_message
      - code
    ClerkErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ClerkError'
        meta:
          type: object
        clerk_trace_id:
          type: string
      required:
      - errors
    Invitation:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - invitation
        id:
          type: string
        email_address:
          type: string
          format: email
        public_metadata:
          type: object
          additionalProperties: true
        revoked:
          type: boolean
          example: false
        status:
          type: string
          enum:
          - pending
          - accepted
          - revoked
          - expired
          example: pending
        url:
          type: string
        expires_at:
          type:
          - integer
          - 'null'
          format: int64
          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
      - public_metadata
      - status
      - created_at
      - updated_at
    Stubs.Verification.SAML:
      type: object
      properties:
        object:
          type: string
          enum:
          - verification_saml
        status:
          type: string
          enum:
          - unverified
          - verified
          - failed
          - expired
          - transferable
        strategy:
          type: string
          enum:
          - saml
        external_verification_redirect_url:
          type:
          - string
          - 'null'
        error:
          allOf:
          - $ref: '#/components/schemas/ClerkError'
          - type:
            - object
            - 'null'
        expire_at:
          type:
          - integer
          - 'null'
        attempts:
          type:
          - integer
          - 'null'
      required:
      - status
      - strategy
    Stubs.Verification.Link:
      type: object
      properties:
        object:
          type: string
          enum:
          - verification_email_link
        status:
          type: string
          enum:
          - unverified
          - verified
          - failed
          - expired
          - transferable
        strategy:
          type: string
          enum:
          - email_link
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type: integer
        verified_at_client:
          type: string
      required:
      - status
      - strategy
      - expire_at
    Client.OrganizationInvitation:
      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_invitation
        email_address:
          type: string
        role:
          type: string
        role_name:
          type: string
        organization_id:
          type: string
        public_organization_data:
          type: object
          allOf:
          - $ref: '#/components/schemas/Client.PublicOrganizationData'
        status:
          type: string
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
          - pending
          - revoked
          - accepted
          - expired
          - completed
        public_metadata:
          type: object
          additionalProperties: true
        url:
          type:
          - string
          - 'null'
        expires_at:
          type:
          - integer
          - 'null'
          format: int64
        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
    Client.Passkey:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        object:
          type: string
          description: 'String representing the object''s type. Objects of the same type share the same value.

            '
          enum:
          - passkey
        name:
          type: string
        last_used_at:
          type:
          - integer
          - 'null'
          format: int64
          description: 'Unix timestamp of when the passkey was last used.

            '
        verification:
          type:
          - object
          - 'null'
          oneOf:
          - $ref: '#/components/schemas/Stubs.Verification.Passkey'
        created_at:
          type: integer
          format: int64
          description: 'Unix timestamp of creation

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

            '
      required:
      - id
      - object
      - name
      - verification
    Client.ClientWrappedOrganizationInvitations:
      type: object
      additionalProperties: false
      properties:
        response:
          oneOf:
          - type: array
            items:
              $ref: '#/components/schemas/Client.OrganizationInvitation'
          - type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/Client.OrganizationInvitation'
              total_count:
                type: integer
                format: int64
        client:
          type: object
          allOf:
          - $ref: '#/components/schemas/schemas-Client.Client'
      required:
      - response
      - client
    Stubs.SignInFactor:
      type: object
      additionalProperties: false
      properties:
        strategy:
          type: string
          enum:
          - ticket
          - password
          - email_code
          - email_link
          - phone_code
          - web3_metamask_signature
          - web3_base_signature
          - web3_coinbase_wallet_signature
          - web3_okx_wallet_signature
          - web3_solana_signature
          - totp
          - backup_code
          - oauth_apple
          - oauth_google
          - oauth_facebook
          - oauth_hubspot
          - oauth_github
          - oauth_mock
          - oauth_custom_mock
          - oauth_token_mock
          - saml
          - enterprise_sso
          - reset_password_email_code
          - reset_password_phone_code
          - passkey
          - google_one_tap
        safe_identifier:
          type: string
        enterprise_connection_id:
          type: string
        enterprise_connection_name:
          type: string
        email_address_id:
          type: string
        phone_number_id:
          type: string
        web3_wallet_id:
          type: string
        passkey_id:
          type: string
        primary:
          type:
          - boolean
          - 'null'
        external_verification_redirect_url:
          type:
          - string
          - 'null'
        default:
          type: boolean
      required:
      - strategy
    Stubs.Verification.BackupCode:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - verification_backup_code
        status:
          type: string
          enum:
          - unverified
          - verified
        strategy:
          type: string
          enum:
          - backup_code
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type:
          - integer
          - 'null'
      required:
      - status
      - strategy
    Stubs.Verification.FromOauth:
      type: object
      properties:
        object:
          type: string
          enum:
          - verification_from_oauth
        status:
          type: string
          enum:
          - verified
          - unverified
        strategy:
          type: string
          enum:
          - from_oauth_apple
          - from_oauth_google
          - from_oauth_mock
          - from_oauth_custom_mock
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type:
          - integer
          - 'null'
      required:
      - status
      - strategy
    Token:
      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:
          - token
        jwt:
          type: string
          description: 'String representing the encoded JWT value.

            '
      required:
      - object
      - jwt
    Stubs.Verification.Admin:
      type: object
      additionalProperties: false
      properties:
        object:
          type: string
          enum:
          - verification_admin
        status:
          type: string
          enum:
          - verified
          - unverified
          - failed
          - expired
        strategy:
          type: string
          enum:
          - admin
        attempts:
          type:
          - integer
          - 'null'
        expire_at:
          type:
          - integer
          - 'null'
      required:
      - status
      - strategy
    Client.EmailAddress:
      type: object
      additionalProperties: false
      properties:
        id:
          type: string
        object:
          type: string
          description: 'String representing the object''s type. Objects of the same type share the same value.

            '
          enum:
          - email_address
        email_address:
          type: string
        reserved:
          type: boolean
        verification:
          type:
          - object
          - 'null'
          oneOf:
          - $ref: '#/components/schemas/Stubs.Verification.OTP'
          - $ref: '#/components/schemas/Stubs.Verification.Invitation'
          - $ref: '#/components/schemas/Stubs.Verification.Link'
          - $ref: '#/components/schemas/Stubs.Verification.Ticket'
          - $ref: '#/components/schemas/Stubs.Verification.Admin'
          - $ref: '#/components/schemas/Stubs.Verification.FromOauth'
          - $ref: '#/components/schemas/Stubs.Verification.SAML'
        linked_to:
          type: array
          items:
    

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