Workspace Invitations

Overview

Workspace owners and admins can invite colleagues to join their workspace by email. Invited users receive an email with a secure token link, and can accept the invitation to join immediately — bypassing the normal access waitlist.

---

Sending an Invitation

From the UI

1. Go to Settings → Members
2. Click Invite member
3. Enter the recipient's email address
4. Select a role: Member or Admin
5. Click Send Invite

The invitee receives an email with a personalised link valid for 7 days. The pending invitation appears in the Members settings page with an expiry countdown.

Via API

POST /api/workspaces/{workspace_id}/invitations

{
  "email": "colleague@company.com",
  "role": "member"
}

Roles:

Role	Capabilities
member	View and contribute to workspace content
admin	Manage members, settings, and integrations

---

Invitation Lifecycle

Sent → Pending ──► Accepted  (user clicks link and accepts)
               ──► Revoked   (admin cancels before acceptance)
               ──► Expired   (7 days pass without acceptance)

Status	Meaning
pending	Awaiting recipient action
accepted	User has joined the workspace
revoked	Admin cancelled the invitation
expired	Link expired after 7 days

Expiry is lazy — a pending invitation is auto-marked expired the first time it is read after its expiry timestamp passes.

---

Accepting an Invitation

When the invitee clicks the link in their email, they land on /workspace-invite/{token}. The page has three states:

Signed in with matching email

If the signed-in account matches the invited email, a single Accept & Join [Workspace Name] button is shown. Clicking it creates the workspace membership and redirects to the app.

Signed in with a different email

A warning is shown: "This invite is for colleague@company.com. You're signed in as other@email.com."

The user is prompted to sign in with the correct account. The token is stored in sessionStorage and auto-accepted after sign-in completes.

Not signed in

Two options are presented:

• Create account & Accept — for new users
• Sign in to Accept — for existing users

The invitation token is preserved through the auth flow so acceptance completes automatically after authentication.

---

Managing Pending Invitations

List pending invitations

GET /api/workspaces/{workspace_id}/invitations

Returns all pending invitations for the workspace. Requires owner or admin role.

[
  {
    "id": "uuid",
    "workspace_id": "uuid",
    "invited_email": "colleague@company.com",
    "role": "member",
    "status": "pending",
    "expires_at": "2026-04-10T12:00:00Z",
    "created_at": "2026-04-03T12:00:00Z",
    "invited_by_name": "Alice Smith"
  }
]

Revoke an invitation

DELETE /api/workspaces/{workspace_id}/invitations/{invitation_id}

Only pending invitations can be revoked. Returns the updated invitation with status: "revoked".

---

Validation (Public Endpoint)

The invitation landing page calls a public endpoint to validate the token before showing the accept UI:

GET /api/invitations/{token}/validate

No authentication required. Returns:

{
  "valid": true,
  "workspace_id": "uuid",
  "workspace_name": "Acme Product Team",
  "inviter_name": "Alice Smith",
  "inviter_email": "alice@acme.com",
  "invited_email": "colleague@company.com",
  "role": "member",
  "error": null
}

If the token is expired or revoked, valid is false and error contains a descriptive message.

---

Accepting via API

POST /api/invitations/{token}/accept

Requires authentication. The authenticated user's email must match invited_email (case-insensitive). On success:

{
  "workspace_id": "uuid",
  "workspace_name": "Acme Product Team"
}

Error codes:

Error	Condition
EMAIL_MISMATCH	Authenticated user email ≠ invited email
INVITATION_EXPIRED	Token is past its 7-day window
INVITATION_REVOKED	Admin cancelled the invitation

---

Permissions

Operation	Required Role
Send invitation	Workspace owner or admin
List pending invitations	Workspace owner or admin
Revoke invitation	Workspace owner or admin
Validate token	Public (no auth)
Accept invitation	Any authenticated user (email must match)

---

What's Next

• Invitations API Reference — full endpoint documentation
• Workspace Management — workspace member management