Organisations
Multi-user workspaces — the org switcher, billing scope, invites and seven-day invitation tokens.
CleverRouter is multi-tenant. Every user belongs to at least one organisation, and most settings (keys, budgets, members, billing) live at the org level.
At a glance
| Identity model | Better-Auth organization plugin |
| Membership unique | One (org, user) pair, enforced at DB level |
| Invite TTL | 7 days |
| Active-org store | Session cookie (activeOrganizationId) |
What an org owns
- Members and roles.
- Billing identity (Stripe customer).
- Per-org settings: ZDR opt-out posture, allowed sub-processors, team-wide rate-limit cap.
- (Soon) Team-shared API keys — today keys are user-scoped.
The default during onboarding is to create your own org. You can be in multiple orgs at once; sign-up doesn't pull you into anyone else's workspace by accident.
Inviting team members
In Settings → Team, an owner or admin can invite by email.
Send the invite. Email is fired via Scaleway TEM. The
invitation row sits in the invitations table with status
pending.
Recipient clicks the link. It carries an HMAC-signed token that encodes the invitation id and a short expiry.
Sign-up + accept happen in one flow. The HMAC token also bypasses the closed-beta sign-up gate for that one user.
Membership inserted. A uniqueness constraint on
(organizationId, userId) prevents double-membership on a
multi-tab race.
Invite expiry is 7 days. Expired invites need to be resent.
Switching orgs
The org switcher is a Better-Auth widget in the dashboard top bar.
The active org id is stored in the session. Server actions and
dashboard pages read it via requireSession().activeOrganizationId.
Every server action checks membership before touching org-scoped
data.
What's still user-scoped
Keys belong to a user, not the org
Today, API keys are user-scoped. A key issued by Alice keeps working even after Alice leaves. There's no org-wide "team key" rotate-once-and-done.
The roadmap moves keys to org-scoped (api_keys.organizationId
plus a backfill). Until then, treat keys as personal credentials
and revoke on offboarding.
Platform admin (Clevermation only)
/app/platform/* routes are for the CleverRouter operator team.
Access requires either:
- Membership in the
clevermationorg with roleowneroradmin, or - Email in
SUPERADMIN_EMAILS.
Platform admin is not an org setting — an org owner cannot promote themselves to it.
Related
- Roles & permissions — what
owner/admin/membercan do. - Get your API key — the user-scoped reality.
- Authentication — server-only security model.