Skip to main content

Get Invitation

Organization API

Get an invitation by token (public endpoint, no auth required).

Description​

The Get Invitation endpoint retrieves invitation details using an invitation token. This is a public endpoint that does not require authentication, making it accessible to users who receive invitation links via email. The endpoint validates the invitation token and returns comprehensive invitation information including organization, workspace, role, and expiration details.

This endpoint is part of the Invitations API and is typically the first step in the invitation acceptance workflow. Users can view invitation details before deciding to accept, allowing them to understand what organization, workspace, and role they're being invited to.

Use Cases​

  • Invitation Preview: Users can preview invitation details before accepting
  • Email Link Handling: Process invitation links received via email
  • Invitation Validation: Verify invitation token validity and expiration status
  • User Decision Making: Review organization, workspace, and role details before acceptance

Workflow Context​

This endpoint is used in the following invitation acceptance workflow:

  1. User receives invitation email with invitation token
  2. User clicks invitation link or uses token to call this endpoint
  3. User reviews invitation details (organization, workspace, role)
  4. User decides to accept the invitation or decline
  5. If accepting, user must be authenticated to complete acceptance

Prerequisites​

  • Valid invitation token (received via email or invitation link)
  • No authentication required (public endpoint)
  • Invitation must not be expired or already accepted
Quick Navigation

Endpoint​

GET /api/v1/invitations/{invitation_token}

Headers​

None required (public endpoint)

Path Parameters​

ParameterTypeRequiredDescription
invitation_tokenstringYesUnique invitation token received via email or invitation link. This token is generated when an invitation is created via the Invite Member endpoint.

Response​

Success (200)​

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

Features​

  • Public Access: No authentication required, making it accessible to users who haven't yet created accounts
  • Token Validation: Validates invitation token and checks expiration status
  • Complete Details: Returns comprehensive invitation information including organization, workspace, role, and expiration
  • Status Checking: Indicates if invitation is valid, expired, or already accepted
  • Security: Token-based access ensures only users with valid invitation tokens can view details

Response Fields​

FieldTypeDescription
invitationobjectInvitation details object
invitation.idintegerUnique invitation identifier
invitation.emailstringEmail address the invitation was sent to
invitation.organizationobjectOrganization details including ID and name
invitation.workspaceobjectWorkspace details including ID and name where the user will be added
invitation.roleobjectRole details including ID and name assigned to the invited user
invitation.expires_atstring (ISO 8601)Timestamp when the invitation expires (typically 7 days from creation)

Error Handling​

If the invitation token is invalid, expired, or already accepted, the endpoint will return an appropriate error response. For more information on error handling, see Error Handling.

See Also​