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

public_metadata
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.

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
}
Response samples
application/json
{
  • "object": "invitation",
  • "id": "string",
  • "email_address": "user@example.com",
  • "public_metadata": { },
  • "revoked": false,
  • "status": "pending",
  • "url": "string",
  • "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"
Responses
200

List of invitations

get/invitations
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",
  • "created_at": 0,
  • "updated_at": 0
}
➔ Next to JWKS