Skip to content

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 ​

RuleDetail
ExpiryTokens expire after 7 days (configurable with INVITATION_EXPIRY_DAYS)
Single useOnce accepted, the token can no longer be used
User must existThe invited email must already have an account in the system
Multi-companyIf 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 ​

MethodRouteWho can use itDescription
POST/companies/:id/invitationsOwner, AdminCreate an invitation — returns the token
GET/invitations/accept?token=PublicAccept an invitation
GET/companies/:id/invitationsOwner, AdminList pending invitations
DELETE/companies/:id/invitations/:invitationIdOwner, AdminRevoke an invitation

Role hierarchy when inviting

POST /companies/:id/invitations applies the same rule as POST /companies/:id/users (see Companies → Adding a member):

  • owner can invite with any role (owner, admin, member, viewer).
  • admin can only invite with member or viewer. If an admin tries to invite with owner or admin, 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? ​

  1. The system looks the token up in the database.
  2. It verifies that it has not expired and has not already been accepted.
  3. It looks up the user whose email matches the invitation's.
  4. If the invitation grants the owner or admin role, the current role of whoever created it is revalidated (not the accepting user's, who has no session). If the creator no longer holds the owner role 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.
  5. It adds the user to the company with the role stated in the invitation.
  6. It marks the invitation as accepted.

After acceptance the user can sign in and access the company.