Access Control
Multi-tenant isolation
Percus is a multi-tenant platform. Each organization is a fully isolated tenant. Users, projects, templates, and API credentials belong to a single organization and are never visible to users of other organizations.
There is no shared state between organizations at the application layer. The Identity Service and Campaign Service each maintain per-organization scoping on all queries.
Role-based access
Every user has exactly one role within each organization they belong to. Roles are assigned at invitation time and can be changed by an OrganizationAdmin.
| Role | Scope | What they can do |
|---|---|---|
Viewer | Org | Read-only access to projects, templates, and channels |
Developer | Org | Upload and manage templates; view all resources |
ProjectManager | Org | Create projects, publish templates, manage landing pages and API credentials |
OrganizationAdmin | Org | Full control — all above plus invite users, change roles, archive projects |
Owner | Platform | Percus internal role; access to all organizations |
A user can belong to multiple organizations with different roles in each.
Enforcement
Authorization is enforced at the API layer, not in the frontend. The frontend forwards the user's role via the X-Percus-Forwarded-Org-Role and X-Percus-Forwarded-System-Role request headers. The backend validates these against the session JWT before processing any mutation.
Sensitive operations — creating projects, publishing templates, managing credentials, archiving — require ProjectManager or OrganizationAdmin role and return 403 Forbidden if the role check fails.
What clients control
| Control | How |
|---|---|
| Who has access to their organization | Managed by their OrganizationAdmin via invitations |
| Role assignment per user | OrganizationAdmin can change roles at any time |
| Revoking access | OrganizationAdmin can deactivate a user; deactivated users cannot log in |
| API credential lifecycle | ProjectManager+ can create and revoke credentials per project |