The next important step is to define roles. Remember, roles are connected to CYPEX users and represent real database-side users. Role Management lets you manage PostgreSQL database roles and application permissions for your CYPEX platform:
Role Management
Roles define capabilities — what operations a user can perform — which is a separate concern from organization membership, the data scope those operations apply to.
Permissions in CYPEX have two independent dimensions, both required for access:
- Role (Capabilities) — what operations you can perform. Examples: SELECT, INSERT, UPDATE, DELETE on tables; EXECUTE functions and workflows.
- Organization Scope (Data Isolation) — where those operations apply. Examples: Organization A, Organization B, enforced via PostgreSQL Row-Level Security.
A role without an organization scope cannot access any data — capabilities alone don’t grant visibility into a tenant’s rows. See Capabilities vs Data Scope for the full mental model.
New in v2.0.0: every role has a type, chosen at creation. The type sets the PostgreSQL inheritance and the validation rules; it does not collapse capabilities and data scope into one switch.
| Role type | PostgreSQL layer | JWT claim | Organization assignment | RLS |
|---|---|---|---|---|
| System Administrator | cypex_admin | isSuperAdmin | Not applicable (rejected if supplied) | Admitted by every policy via cypex.is_admin() |
| Organization Administrator | cypex_admin + organization_admin | isOrganizationAdmin | Required, one or more | Admitted via cypex.is_organization_admin() for mapped organizations only; everything outside is invisible |
| Organization Member | cypex_user | — | Required, one or more | Fully applied |
Notes that bite in practice:
- Organization Member is SELECT-oriented on CYPEX core tables. Full CRUD is retained where users create and own the content — reports, files, notifications. An application relying on
cypex_userwrite access elsewhere will fail. - The default for a new role is Organization Member — least privilege unless you deliberately choose broader access.
- Only an existing System Administrator can create another System Administrator.
- Creating an Organization Administrator or Organization Member without at least one organization is rejected by the API. This is a backend rule, not a database constraint, so it is enforced on the API path and not on direct SQL. A role created with raw SQL can end up with no scope and will silently see nothing.
Use the Select organization and Filter by UI dropdowns above the role tables to narrow the list down to the roles relevant to a given tenant or application:
Filter by organization
Scoping the role list to a specific organization (smi, eshop, or the Default Organization).
CYPEX ships five core system roles — cypex_admin, cypex_user, organization_admin, authenticator, and anon. These form the foundation of the permissions model and cannot be modified or deleted:
System Roles
cypex_admin has Global Access; organization_admin and authenticator carry the Organization Admin scope; cypex_user and anon apply across All Organizations.
Custom roles are created by administrators for specific business requirements and can be modified and deleted. They are grouped by inheritance — system admin roles inherit cypex_admin, Org Admin roles inherit organization_admin, and Standard roles inherit cypex_user:
User-Defined Roles
The Scope/Organizations column shows each role's data boundary — a single org (eshop), the Default Organization, an Organization Admin badge, or a No Scope warning when nothing is assigned yet.
WarningNo Scope. A role flagged No Scope has capabilities but no organization assigned — per the two-dimension model above, users holding it cannot see any tenant data until it is mapped to at least one organization.
A separate tab lists PostgreSQL roles that CYPEX can see but that have no organization data scope — roles reachable through authenticator and template inheritance that were never mapped. They are functionally invisible to their users until adopted.
Two situations produce them:
- After an upgrade from v1.9.x. The migration maps every role that is a member of
cypex_userorcypex_adminto the Default Organization. A role outside those two group memberships is left unmapped. - After installing a repository application, which may create its own roles.
Adopting a role assigns it a role type and one or more organizations, bringing it into the v2.0.0 model without recreating it or disturbing its existing grants.
Listing and adopting are both System Administrator only.
InfoCYPEX core roles and System Administrator roles are excluded from this list by design — a global role has no organization scope to assign. Their absence is not a fault.
TipWork through this tab as a post-upgrade step. A role sitting here is the most likely explanation for “this user could see their data before the upgrade and cannot now”, after Schema Access.
A role↔organization mapping goes stale when the PostgreSQL role or the organization it references no longer exists — typically after a role or tenant is dropped outside the admin panel.
System Administrators can list stale mappings and purge them in bulk. Purging removes only mappings whose referenced role or organization is already gone; it cannot remove a live mapping. Both operations are System Administrator only.
Click the eye icon on any role to open Role Details. It is organized into four tabs:
Role Details — Role Attributes
PostgreSQL role attributes (Superuser, Can Login, Create Roles, Create Databases, …) define what operations this role can perform at the database level.
Capabilities lists the role’s schema-level permissions — application schemas only, with an option to reveal the internal CYPEX schemas:
Role Details — Capabilities
Schema permissions (e.g. eshop: USAGE) define database-level operations. Object-level permissions (views, functions, state transitions) are managed on the Access Preview page.
Organizations is where the data-scope side of the model lives — the set of organizations this role’s users can access, each with a default organization role (admin, member, or viewer):
Role Details — Organizations
Organization Boundaries: users with this role can only access data within the assigned organizations. Edit Assignments changes the mapping.
Usage Stats shows where the role is actually used — assigned users, organizations it has access to, active sessions, and accessible schemas:
Role Details — Usage Stats
At-a-glance counts: Assigned Users, Organizations (Scoped), Active Sessions, and Accessible Schemas.
Click Create New Role to define a new PostgreSQL role. Give it a name, then choose the role type:
Create Role
System Role (PostgreSQL) defines what operations the role can perform; Organization Role defines the permission level within each organization. These are separate concerns.
The role type determines how the role fits into the permission model — System Administrator, Organization Administrator, or Organization Member:
Role type
Organization Administrator and Organization Member scope the role to one or more organizations; System Administrator grants global access.
For Organization Administrator and Organization Member roles, assign the organizations the role should be scoped to under Organization Assignments:
Organization Assignments
Picking which organizations (smi, eshop, Default Organization) this new role's data access is scoped to.
While it is possible to create roles quickly, it is the task of the DBA to assign the actual object-level permissions to those roles. At the moment, this is done at the query level via the Access Preview page — once a query is created, you can assign permissions to roles there.
- Users — map users to a role.
- Access Preview — verify what each role can do.
- Capabilities vs Data Scope — the mental model.
- Organizations — the admin-panel entry point for multi-tenancy.
- Organizations setup guide — create, edit, and assign organizations.