Skip to main content

List Invitations

Organization API

List all invitations based on user permissions.

Description​

The List Invitations endpoint retrieves all organization invitations that the authenticated user has permission to view. The results are automatically scoped based on the user's role and permissions, ensuring users only see invitations relevant to their access level.

This endpoint is part of the Invitations API and implements permission-based scoping to provide appropriate visibility. System administrators see all invitations across all organizations, organization administrators see invitations in their organizations, and members with invite permissions see invitations where they have permission.

Use Cases​

  • Administrative Review: Organization administrators can review all pending invitations for their organizations
  • Permission Management: Members with invite permissions can view invitations they've created or have permission to manage
  • Audit and Compliance: System administrators can audit all invitations across the platform
  • Invitation Management: Review invitations before revoking or managing them

Workflow Context​

This endpoint is typically used:

  • By organization administrators to review pending invitations
  • Before revoking an invitation to identify the correct invitation ID
  • During security audits to review invitation activity
  • To track invitation status and expiration dates

Prerequisites​

  • User must be authenticated with a valid access token
  • User must have appropriate permissions (system admin, organization admin, or member with invite permission)
Quick Navigation

Endpoint​

GET /api/v1/invitations

Headers​

HeaderRequiredDescription
AuthorizationYesBearer <access_token>

Response​

Success (200)​

{
  "success": true,
  "data": {
    "invitations": [
      {
        "id": 1,
        "email": "user@example.com",
        "organization": {
          "id": 1,
          "name": "Acme Corp"
        },
        "workspace": {
          "id": 1,
          "name": "Main Workspace"
        },
        "role": {
          "id": 2,
          "name": "Developer"
        },
        "status": "pending",
        "expires_at": "2024-01-08T00:00:00Z"
      }
    ],
    "message": "Invitations retrieved successfully."
  },
  "message": "Invitations retrieved successfully."
}

Permission Scoping​

The invitation list is automatically filtered based on the authenticated user's role and permissions:

  • System Admin: See all invitations across all organizations in the system
  • Organization Admin: See all invitations in organizations where they have administrative access
  • Member with Invite Permission: See invitations in organizations where they have been granted invite management permissions

For more information on permissions and roles, see the Roles & Permissions API.

Features​

  • Permission-Based Scoping: Automatically filters invitations based on user role and permissions
  • Complete Invitation Details: Returns comprehensive invitation information including organization, workspace, role, and expiration
  • Status Tracking: Shows invitation status (pending, accepted, expired, revoked)
  • Expiration Information: Includes expiration timestamps for invitation management
  • Organization Context: Provides full organization and workspace details for each invitation

Response Fields​

FieldTypeDescription
invitationsarrayArray of invitation objects based on user permissions
invitations[].idintegerUnique invitation identifier. Use this ID to revoke the invitation if needed.
invitations[].emailstringEmail address of the invited user
invitations[].organizationobjectOrganization details including ID and name
invitations[].workspaceobjectWorkspace details including ID and name where the user will be added
invitations[].roleobjectRole details including ID and name assigned to the invited user
invitations[].statusstringInvitation status: pending, accepted, expired, or revoked
invitations[].expires_atstring (ISO 8601)Timestamp when the invitation expires (typically 7 days from creation)

See Also​