Users

Users are individual people who authenticate and interact with the platform. A user can belong to multiple accounts with different roles in each.

Users vs. Accounts

	User	Account
Represents	A person	An organization / tenant
Has	Email, password, 2FA	Plan, billing, usage
Scope	Cross-account identity	Subscription + data

A user signs in once and then selects (or switches between) the accounts they belong to.

Roles

Users are assigned a role (permission level) within each account. Roles are hierarchical — each level includes everything below it:

Role	Access level
master	Platform operator — cross-account admin (/master/* endpoints)
owner	Full account control including deletion
admin	Account administration: team, billing, account settings
developer	API keys and webhooks, plus everything a user can do
user	Standard member access

The full matrix lives in demo-server/config/default.json under permissions.

API endpoints

Method	Endpoint	Description
GET	/user	Get the authenticated user's profile
PATCH	/user	Update profile (name, avatar, etc.)
PUT	/user/password	Change password (body: { oldpassword, newpassword }; enforces history check)
PUT	/user/2fa	Enable or disable 2FA (body: { twoFactor_enabled: true|false })
POST	/user/2fa/verify	Confirm 2FA setup with an OTP code

Email notification preferences are account-scoped — see GET/PUT /account/email-preferences on the Accounts page.

Team management (admin)

Admins manage the users on their account through the /users group:

Method	Endpoint	Description
POST	/users	Add a user to the account
GET	/users/account	List the users on the account
GET	/users/permissions	List assignable permission levels
GET	/users/:id	Get a single user
PATCH	/users	Update a user's details or role
DELETE	/users	Remove a user from the account

Password policy

• Passwords are hashed with Argon2
• The last N passwords are stored and cannot be reused:

NUMBER_OF_PREVIOUS_PASSWORDS=5

2FA setup flow

1. Call PUT /user/2fa with { "twoFactor_enabled": true } → server returns TOTP secret + QR code URL
2. User scans the QR code in their authenticator app (Google Authenticator, Authy, etc.)
3. User submits a valid OTP to POST /user/2fa/verify to confirm setup
4. Server stores the secret and issues one-time backup codes

TOTP_LOGO_URL=https://yourdomain.com/logo.png  # Logo shown in the authenticator app

Invitations

Users are added to accounts via an invite flow (admin role required):

Method	Endpoint	Description
POST	/invite	Send an invite email to a new user
GET	/invite	List pending invites for the account
GET	/invite/:id	Get a single invite
DELETE	/invite	Revoke a pending invite

The invited user completes signup through the link in the email; the invite is marked as used once accepted.