Invitations
What this module does
It lets a company's administrators invite new members through a link/token sent by email. The invited user accepts and is automatically linked to the company with the assigned role.
Full flow
Admin System Invited user
│ │ │
├─ POST /companies/:id/ │ │
│ invitations │ │
│ { email, role } │ │
│ ├── Creates the invitation │
│ ├── Generates a unique token │
│◄─ Returns the token ─────────┤ │
│ │ │
├─ (sends the link by email) ──────────────────────────────────────►│
│ │ │
│ │ GET /invitations/accept │
│ │◄────?token=<token> ───────────────┤
│ │ │
│ ├── Verifies the token │
│ ├── Adds the user to the company │
│ ├── Marks the token as used │
│ │ │
│ ├──────────── ✅ Access granted ────►│The system generates the token; the integrator sends the email
The backend returns the token but does not send the email itself. Building the link and sending it to the user is the responsibility of the client application (or a worker).
Important rules
| Rule | Detail |
|---|---|
| Expiry | Tokens expire after 7 days (configurable with INVITATION_EXPIRY_DAYS) |
| Single use | Once accepted, the token can no longer be used |
| User must exist | The invited email must already have an account in the system |
| Multi-company | If multi_company = false, a user who already belongs to another company cannot accept the invitation — 409 Conflict (same status as POST /companies / POST /companies/:id/users) |
Endpoints
| Method | Route | Who can use it | Description |
|---|---|---|---|
POST | /companies/:id/invitations | Owner, Admin | Create an invitation — returns the token |
GET | /invitations/accept?token= | Public | Accept an invitation |
GET | /companies/:id/invitations | Owner, Admin | List pending invitations |
DELETE | /companies/:id/invitations/:invitationId | Owner, Admin | Revoke an invitation |
Role hierarchy when inviting
POST /companies/:id/invitations applies the same rule as POST /companies/:id/users (see Companies → Adding a member):
ownercan invite with any role (owner,admin,member,viewer).admincan only invite withmemberorviewer. If anadmintries to invite withowneroradmin, the request answers 403 Forbidden.
This prevents an admin from bringing someone in as owner/admin through an invitation, bypassing the same control that already exists for adding members directly. A super admin bypasses this restriction, just as with POST /companies/:id/users.
What happens when someone accepts?
- The system looks the token up in the database.
- It verifies that it has not expired and has not already been accepted.
- It looks up the user whose email matches the invitation's.
- If the invitation grants the
owneroradminrole, the current role of whoever created it is revalidated (not the accepting user's, who has no session). If the creator no longer holds theownerrole in the company (for example, they were demoted after creating the invitation) and is not a super admin, acceptance is rejected with 403 Forbidden — no membership is created. - It adds the user to the company with the role stated in the invitation.
- It marks the invitation as accepted.
After acceptance the user can sign in and access the company.