Overview
The Invitations API provides comprehensive endpoints for managing organization membership invitations. Organization owners and admins can invite users via email, and invited users can accept or decline invitations through secure token-based flows.
Invitations use SHA256-hashed tokens for security and expire after a configurable period (default: 7 days). The system prevents duplicate invitations and enforces organization member limits based on tier configuration.
Key Features
- Email-based Invitations: Invite users by email address with role assignment
- Token Security: SHA256-hashed invitation tokens for secure acceptance
- Role-Based Access: Invite users as owner, admin, or member
- Expiration Handling: Automatic expiration after 7 days
- Duplicate Prevention: Prevents duplicate invitations to the same email
- Member Limit Enforcement: Respects organization tier member limits
- Invitation Management: List, cancel, and track invitation status
- Email Link Support: Direct email link for one-click acceptance
Endpoints Summary
| Method | Path | Description |
|---|---|---|
POST |
/api/organizations/:org_slug/invitations |
Create invitation |
GET |
/api/organizations/:org_slug/invitations |
List organization invitations |
POST |
/api/organizations/:org_slug/invitations/:invitation_id |
Cancel invitation |
GET |
/api/invitations |
List user’s pending invitations |
POST |
/api/invitations/accept |
Accept invitation |
POST |
/api/invitations/decline |
Decline invitation |
GET |
/invitations/accept/:token |
Email link redirect for acceptance |
Choose an invitation task
| Need | Focused reference |
|---|---|
| Create, list, cancel, accept, or decline invitations | Endpoint reference |
| Understand statuses, token handling, expiration, and security | Lifecycle and security |
| Build the complete flow, email, and consumer UI | Integration recipes |
| Diagnose authorization, invalid tokens, expiry, or membership failures | Troubleshooting |
Treat invitation tokens as credentials. Keep them out of logs and public channels, handle expiration explicitly, and grant the minimum role required.
Published-anchor compatibility
This overview remains the stable published route. The headings below retain the original fragment identifiers and direct existing links to focused references.
Organization Admin Endpoints
Continue in the endpoint reference.
POST /api/organizations/:org_slug/invitations
Continue in the endpoint reference.
GET /api/organizations/:org_slug/invitations
Continue in the endpoint reference.
POST /api/organizations/:org_slug/invitations/:invitation_id
Continue in the endpoint reference.
User Endpoints
Continue in the endpoint reference.
GET /api/invitations
Continue in the endpoint reference.
POST /api/invitations/accept
Continue in the endpoint reference.
POST /api/invitations/decline
Continue in the endpoint reference.
GET /invitations/accept/:token
Continue in the endpoint reference.
Invitation Lifecycle
Continue in lifecycle and security.
Status Flow
Continue in lifecycle and security.
Status Descriptions
Continue in lifecycle and security.
Security
Continue in lifecycle and security.
Token Hashing
Continue in lifecycle and security.
Expiration
Continue in lifecycle and security.
Best Practices
Continue in lifecycle and security.
Error Responses
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
Complete Workflow Example
Continue in integration recipes.
Admin Invites User
Continue in integration recipes.
User Receives Email
Continue in integration recipes.
User Accepts Invitation
Continue in integration recipes.
Admin Monitors Invitations
Continue in integration recipes.
Integration Examples
Continue in integration recipes.
Frontend Invitation Acceptance Page
Continue in integration recipes.
Email Template
Continue in integration recipes.
Example Consumer-App Admin Component
Continue in integration recipes.