The three layers
- Workspace entitlements — what your tenant has paid for. Set by Prax CRM; not editable by tenant admins.
- Designation templates — reusable permission bundles per job title (Sales Rep, Backend Manager, Accountant, etc.). Tenant-admin editable.
- Per-user overrides — exceptions for an individual on top of their designation. Used sparingly, mostly for vacation cover or training.
Effective permissions = entitlement gate ∩ (designation template ∪ override). If the workspace isn't entitled to a feature, no designation can grant it.
Roles
The coarse layer. Every user is exactly one of:
- admin — full visibility into the workspace (modulo entitlements). Can edit designations, invite users, configure SMTP, view audit log.
- employee — limited to the tabs and actions their designation grants. Can never see other employees' salary records unless their designation explicitly allows it.
- customer — external user, lands in the customer portal. Sees only the records the workspace shares with their account.
Designations & the matrix
Open Admin → Access Control → Designations. Each row is a designation; each column is a feature; each cell is a set of action toggles.
The four actions are:
view— see the tab and read records.create— add new records.edit— modify existing records.delete— remove records.
Granted actions are enforced both in the UI (the button is hidden) and in the Convex backend (the mutation throws "Forbidden"). The UI hide is convenience — the server check is the lock.
Per-user overrides
From Admin → Users → ⋯ → Permissions, you can override the designation matrix for one user. Three modes:
- Grant — give this user an action their designation doesn't normally have.
- Revoke — remove an action the designation normally grants.
- Reset — drop the override; user falls back to designation defaults.
Overrides survive designation changes. If "Sales Rep" is rebuilt, users with overrides keep their overrides applied on top of the new template.
The audit log
Every privileged action — create, edit, delete on any record type — writes a row to Admin → Agent History. Each row captures:
- actor (user, role, designation at the time)
- action (create / update / delete)
- entity type + entity ID
- timestamp + IP / device fingerprint
- workspace ID (for cross-tenant safety even in platform-admin views)
The log is workspace-scoped — tenant admins see only their own workspace's events. Platform admins (Prax CRM ops) see across tenants but only via gated UI; every read is itself audited.
Worked example: a Sales Rep
Typical Sales Rep designation:
leads: view, create, edit sales: view, create, edit customers: view, create, edit calls: view, create emails: view, create attendance: view (own records) hrDocuments: - (no access) salaries: - (no access) designations: - (no access — admins only) auditLog: - (no access)
They cannot delete a lead even by accident — the delete button is hidden, and a direct API call would be rejected by requirePermission(ctx, token, "leads", "delete").
If you need one Sales Rep to handle off-boarding clean-up for two weeks, give them a per-user leads:delete grant override. Reset it when the project ends.
Workspace entitlements
On top of role + designation, there's a platform-level gate: entitlements. These are flipped by Prax CRM (not by tenant admins) based on your plan.
Examples: SAML, SCIM, custom domains, Atlas AI assistant, the REST API, the embeddable chat widget. If your plan doesn't include a feature, no designation can grant access — the tab simply doesn't render and the API rejects the call.
On the pricing page, the "what's in each plan" matrix maps directly to the entitlements your workspace gets.
Tips for designing your matrix
- Start narrow. Grant only what each designation genuinely needs. It's easier to widen later than to narrow after a leak.
- Avoid bespoke per-user grants for permanent staff. If three Sales Reps need the same exception, that's a sign the designation needs updating.
- Don't create one designation per person. Five well-named designations (Sales Rep, Sales Lead, Backend Manager, Accountant, HR) cover most teams up to 100 people.
- Review quarterly. As features ship, new actions appear in the matrix and default to off — explicitly decide who gets them.