Cancel a pending invitation
An administrator withdraws an invitation before the recipient accepts it.
Clerk · Module
invitations.revokeInvitation
Revokes an active Clerk invitation by ID and makes its invitation email link unusable. The call returns the revoked Invitation resource.
How it works
Call the Backend API method with an invitation identifier. Clerk invalidates the invitation's email link and resolves with the revoked Invitation object; the method is intended for active invitations only.
Syntax
function revokeInvitation(invitationId: string): Promise<Invitation>Parameters
| Name | Type | Description |
|---|---|---|
invitationId | string | The ID of the invitation to revoke. |
Returns
Promise<Invitation>
Key points
- The method targets one invitation identified by its ID.
- After revocation, the invitation URL can no longer be used.
- A successful call resolves with the updated Invitation resource.
- Pass the invitation's identifier as the method argument.
- The SDK method delegates to Clerk's backend API operation.
Common mistakes
- A previously revoked invitation cannot be revoked again.
- Revocation disables the invitation link but does not stop independent signup.
Example: Revoke an invitation
import { clerkClient } from '@clerk/nextjs/server'
export async function POST() {
const invitation = await clerkClient.invitations.revokeInvitation({
invitationId: 'invitation_123',
})
return Response.json({ message: 'Invitation revoked', invitation })
}Revokes the specified invitation and returns the revoked invitation.
When to use it
Disable an invitation link
A backend endpoint needs to invalidate an invitation link.
Refresh invitation data
An application displays the updated invitation state after cancellation.
Interview questions
QWhat does revokeInvitation() do, and what does it return?
It takes an invitation ID and returns a Promise<Invitation>. The operation revokes the invitation and makes its email link unusable.
Follow-up: What happens if the invitation was already revoked? It cannot be revoked again because only active invitations are eligible.
QHow would you call this method from server-side code?
Use the Backend API through Clerk's clerkClient wrapper, passing the invitation ID to the method. The wrapper handles the corresponding backend operation for the SDK.
Follow-up: What is the underlying endpoint? It is POST /invitations/{invitation_id}/revoke.
QDoes revocation prevent the user from signing up?
Revoking an invitation only invalidates the invitation link. It does not prevent the recipient from entering the normal signup flow independently.
Follow-up: How would you restrict registration to invited users? Use Clerk's invite-only access mode rather than relying on revocation.
Related
InvitationclerkClientPOST /invitations/{invitation_id}/revoke