Recipe
Team Invite Flow
A step-by-step pattern for inviting teammates into your Nimbus workspace with role assignment and expiry windows.
Overview
The invite flow uses a three-stage pipeline: generate a signed invite token, deliver it via email or copyable link, and resolve the token on acceptance. Tokens carry a workspace ID, target role, and a configurable TTL. Once consumed or expired, the token is invalidated server-side.
Data Model
| Field | Type | Notes |
|---|---|---|
| invite_id | UUIDv4 | Primary key |
| workspace_id | UUIDv4 | Target workspace |
| role | enum | admin | member | viewer |
| expires_at | timestamp | Default 72h |
| consumed | boolean | Set on acceptance |
Endpoints
POST/api/invites
Creates an invite. Requires admin role on the workspace. Returns the invite token and a pre-signed acceptance URL.
GET/api/invites/:token
Resolves invite metadata before acceptance. Shows workspace name and assigned role. Returns 410 if expired.
POST/api/invites/:token/accept
Consumes the token, adds the authenticated user to the workspace with the assigned role. Idempotent.
Edge Cases
- Token already consumed — return 409 with workspace link.
- Token expired — return 410, prompt admin to re-invite.
- User already in workspace — return 200, no state change.
- Invitee email differs from authenticated session — reject with 403.