Skip to main content

Revoke Invitation

Organization API

Revoke an invitation.

Description​

The Revoke Invitation endpoint allows authorized users to cancel a pending organization invitation before it is accepted. Once revoked, the invitation token becomes invalid and cannot be used to accept the invitation. This endpoint is essential for invitation management, allowing administrators to cancel invitations that are no longer needed or were sent in error.

This endpoint is part of the Invitations API and implements permission-based access control. Only users with appropriate permissions (system administrators, organization administrators, or members with invite management permissions) can revoke invitations.

Use Cases​

  • Invitation Management: Cancel invitations that are no longer needed
  • Error Correction: Revoke invitations sent to incorrect email addresses
  • Access Control: Prevent unwanted users from joining organizations
  • Security Response: Revoke invitations when security concerns arise

Workflow Context​

This endpoint is typically used:

  • After reviewing the list of invitations to identify invitations to revoke
  • When an invitation was sent to the wrong email address
  • When the invited role or permissions need to be changed (revoke and create new invitation)
  • During security audits to manage pending invitations

Prerequisites​

  • User must be authenticated with a valid access token
  • User must have permission to revoke invitations (system admin, organization admin, or member with invite permission)
  • User must know the invitation ID (obtainable from List Invitations)
  • Invitation must exist and be revocable (not already accepted)
Quick Navigation

Endpoint​

DELETE /api/v1/invitations/{invitation_id}

Headers​

HeaderRequiredDescription
AuthorizationYesBearer <access_token>

Path Parameters​

ParameterTypeRequiredDescription
invitation_idintegerYesUnique identifier of the invitation to revoke. You can obtain invitation IDs from the List Invitations endpoint.

Response​

Success (204)​

No content returned.

Features​

  • Permission Validation: Ensures only authorized users can revoke invitations
  • Immediate Revocation: Invalidates the invitation token immediately upon successful request
  • Token Invalidation: The invitation token can no longer be used to accept the invitation
  • Audit Logging: Records revocation events for security monitoring and compliance
  • Idempotent Operation: Revoking an already-revoked invitation returns success without error

Important Notes​

  • Immediate Effect: Invitation revocation takes effect immediately. The invitation token becomes invalid and cannot be used.
  • No Recovery: Once revoked, the invitation cannot be restored. A new invitation must be created if needed.
  • Accepted Invitations: Cannot revoke invitations that have already been accepted. Accepted invitations are automatically excluded from revocation.
  • Permission Required: Only users with appropriate permissions can revoke invitations. See Permission Scoping for details.

Error Handling​

Common error scenarios include:

  • Invalid invitation ID
  • Invitation not found or doesn't belong to accessible organization
  • Insufficient permissions to revoke invitation
  • Invitation already accepted (cannot revoke)

For more information on error handling, see Error Handling.

See Also​