Clerk docs

Invitations

Invitations allow you to invite someone to sign up to your application, via email.

https://clerk.com/docs/authentication/invitations

Create an invitation

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.

SecuritybearerAuth
Request
Request Body schema: application/json

Required parameters

email_address
required
string

The email address the invitation will be sent to

object

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.

redirect_url
string

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 and you're not using Clerk Hosted Pages or Clerk Components.

notify
boolean or null
Default: true

Optional flag which denotes whether an email invitation should be sent to the given email address. Defaults to true.

ignore_existing
boolean or null
Default: false

Whether an invitation should be created if there is already an existing invitation for this email address, or it's claimed by another user.

expires_in_days
integer or null [ 1 .. 365 ]

The number of days the invitation will be valid for. By default, the invitation expires after 30 days.

template_slug
string or null

The slug of the email template to use for the invitation email. If not provided, the "invitation" template will be used.

Enum: "invitation" "waitlist_invitation"
Responses
200

Success

400

Request was not successful

422

Invalid request parameters

post/invitations
Request samples
application/json
{
  • "email_address": "string",
  • "public_metadata": { },
  • "redirect_url": "string",
  • "notify": true,
  • "ignore_existing": false,
  • "expires_in_days": 1,
  • "template_slug": "invitation"
}
Response samples
application/json
{
  • "object": "invitation",
  • "id": "string",
  • "email_address": "user@example.com",
  • "public_metadata": { },
  • "revoked": false,
  • "status": "pending",
  • "url": "string",
  • "expires_at": 0,
  • "created_at": 0,
  • "updated_at": 0
}

List all invitations

Returns all non-revoked invitations for your application, sorted by creation date

SecuritybearerAuth
Request
query Parameters
limit
number [ 1 .. 500 ]
Default: 10

Applies a limit to the number of results returned. Can be used for paginating the results together with offset.

offset
number >= 0
Default: 0

Skip the first offset results when paginating. Needs to be an integer greater or equal to zero. To be used in conjunction with limit.

status
string

Filter invitations based on their status

Enum: "pending" "accepted" "revoked" "expired"
query
string

Filter invitations based on their email_address or id

Responses
200

List of invitations

get/invitations
Response samples
application/json
[
  • {
    }
]

Create multiple invitations

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.

SecuritybearerAuth
Request
Request Body schema: application/json

Required parameters

Array
email_address
required
string

The email address the invitation will be sent to

object

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.

redirect_url
string

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 and you're not using Clerk Hosted Pages or Clerk Components.

notify
boolean or null
Default: true

Optional flag which denotes whether an email invitation should be sent to the given email address. Defaults to true.

ignore_existing
boolean or null
Default: false

Whether an invitation should be created if there is already an existing invitation for this email address, or it's claimed by another user.

expires_in_days
integer or null [ 1 .. 365 ]

The number of days the invitation will be valid for. By default, the invitation expires after 30 days.

Responses
200

List of invitations

400

Request was not successful

422

Invalid request parameters

post/invitations/bulk
Request samples
application/json
[
  • {
    }
]
Response samples
application/json
[
  • {
    }
]

Revokes an invitation

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.

SecuritybearerAuth
Request
path Parameters
invitation_id
required
string

The ID of the invitation to be revoked

Responses
200

Success

400

Request was not successful

404

Resource not found

post/invitations/{invitation_id}/revoke
Response samples
application/json
{
  • "object": "invitation",
  • "id": "string",
  • "email_address": "user@example.com",
  • "public_metadata": { },
  • "revoked": true,
  • "status": "revoked",
  • "url": "string",
  • "expires_at": 0,
  • "created_at": 0,
  • "updated_at": 0
}
➔ Next to JWKS