Skip to main content

Accept Invitation

Organization API

Accept an organization invitation for the current user.

Description​

The Accept Invitation endpoint allows an authenticated user to accept an organization invitation and join the organization. Upon acceptance, the system automatically creates an organization membership, assigns the specified role, and grants access to the associated workspace. This endpoint completes the invitation workflow and enables the user to access organization resources.

This endpoint is part of the Invitations API and is the final step in the invitation acceptance process. Users must first view the invitation details to understand what they're accepting, then authenticate and call this endpoint to complete the process.

Use Cases​

  • Join Organization: Accept invitations to join organizations and gain access to resources
  • Team Collaboration: Join teams and workspaces through invitation links
  • Role Assignment: Accept invitations with specific role assignments
  • Access Management: Gain access to organization resources through invitation acceptance

Workflow Context​

This endpoint is used in the following invitation acceptance workflow:

  1. User receives invitation email with invitation token
  2. User views invitation details to review organization, workspace, and role
  3. User authenticates or creates an account
  4. User calls this endpoint to accept the invitation
  5. System creates membership, assigns role, and grants workspace access
  6. User can now access organization resources

Prerequisites​

  • User must be authenticated with a valid access token
  • Valid invitation token (obtained from invitation email or Get Invitation endpoint)
  • Invitation must be valid, not expired, and not already accepted
  • User email must match the invitation email (or system must allow email changes)
Quick Navigation

Endpoint​

POST /api/v1/invitations/{invitation_token}/accept

Headers​

HeaderRequiredDescription
AuthorizationYesBearer <access_token>

Path Parameters​

ParameterTypeRequiredDescription
invitation_tokenstringYesUnique invitation token received via email or obtained from the Get Invitation endpoint. The token must be valid and not expired.

Response​

Success (200)​

{
  "success": true,
  "data": {
    "organization": {
      "id": 1,
      "name": "Acme Corp"
    },
    "workspace": {
      "id": 1,
      "name": "Main Workspace"
    },
    "membership": {
      "id": 1,
      "is_admin": false
    },
    "role": {
      "id": 2,
      "name": "Developer"
    },
    "message": "Invitation accepted successfully."
  },
  "message": "Invitation accepted successfully."
}

Features​

  • Automatic Membership Creation: Creates organization membership and workspace access automatically
  • Role Assignment: Assigns the role specified in the invitation to the user
  • Invitation Completion: Marks the invitation as accepted and prevents duplicate acceptance
  • Comprehensive Response: Returns organization, workspace, membership, and role details
  • Audit Logging: Records invitation acceptance events for security monitoring and compliance
  • Email Validation: Ensures user email matches invitation email (or handles email changes if allowed)

Response Fields​

FieldTypeDescription
organizationobjectOrganization details including ID and name the user has joined
workspaceobjectWorkspace details including ID and name where the user has been granted access
membershipobjectMembership details including ID and admin status
membership.is_adminbooleanWhether the user has administrative privileges in the organization
roleobjectRole details including ID and name assigned to the user

Important Notes​

  • One-Time Use: Each invitation can only be accepted once. After acceptance, the invitation token becomes invalid.
  • Email Matching: The authenticated user's email must match the invitation email, unless the system allows email changes.
  • Immediate Access: Upon successful acceptance, the user immediately gains access to the organization and workspace.
  • Role Permissions: The user's permissions are determined by the role assigned in the invitation.

Error Handling​

Common error scenarios include:

  • Invalid or expired invitation token
  • Invitation already accepted
  • User email mismatch
  • Authentication failure

For more information on error handling, see Error Handling.

  • Get Invitation - View invitation details before accepting (prerequisite)
  • List Invitations - List invitations (requires permissions)
  • Login - Authenticate to accept invitation (prerequisite)
  • Invite Member - Create invitations (admin operation)

See Also​