Roles & permissions (RBAC)

Relay's authorization model — permissions, system and custom roles, bindings, teams, the permission matrix, and how access is resolved across organizations and workspaces.

Relay controls who can do what through role-based access control (RBAC). This page explains the model: permissions, roles, bindings, and teams; what each system role grants; and how a request is resolved to allow or deny across the organization → workspace hierarchy.

Concepts

Permission — a service.resource.verb string, e.g. org.databases.create. Permissions are the atomic units of access.
Role — a named bundle of permissions. System roles (owner, admin, member, viewer) exist in every organization. Custom roles are defined by your organization and scoped to it.
Binding — grants a subject (a user or a team) a role at a scope (an organization or a workspace). Bindings are the single source of truth for what a member can do — membership alone carries no permissions.
Team — an organization-scoped collection of users. A team can be a binding subject, so a role can be granted to a whole group at once.

System roles

Role	Audience	Summary
`owner`	Founders / top admins	Full control. The only role that can delete the organization or transfer ownership. A last-owner guard prevents an org from ever reaching zero owners.
`admin`	Operators	Manage members, teams, settings, connections, workspaces, and databases. Cannot delete the org or transfer ownership.
`member`	Day-to-day users	Read across the organization; create, read and update managed databases and database users (no delete).
`viewer`	Read-only / auditors	Read-only across the organization.

Effective permission matrix

Resource	owner	admin	member	viewer
Organization	full	read, rename, settings	read	read
Teams	full	create/read/rename/delete, add/remove members	read	read
Members	full	read/invite/remove/update, change role	read	read
Sessions	full	revoke	—	—
Connections	full	full	read, connect	read
Connection groups	full	full	read	read
Policies	full	full	read	read
Access grants	full	create/read/delete	read	read
Agents	full	full	read	read
Agent replicas	full	read/delete	read	read
Enrollment tokens	full	create/read/delete	read	read
Audit logs	full	read	read	read
Workspaces	full	full	read	read
Workspace members / teams	full	add/remove members and teams	read	read
Roles	full	create/read/update/delete	read	read
Role bindings	full	create/read/delete	read	read
Managed databases	full	full	create, read, update	read
Database users	full	full	create, read, update	read
Billing	full	read, manage	read	read
API keys	full	create/read/delete	—	—
SSO	full	manage	—	—
External secret sources	full	full	—	—
Cloud integrations	full	full	read	read
Support reports	full	create/read	create/read	create/read

Self-rule: regardless of role, anyone may view and revoke their own sessions. Viewing other people's sessions is not a permission any role holds; only revoking them is (admin and owner). Owner-only: deleting the organization and transferring ownership are reachable only through the owner role. Workspace-assignable roles are admin, member, and viewer — owner is an organization-level concept and cannot be assigned at the workspace scope.

Where a role lives

A user's role is exactly the set of bindings they hold — directly, or through a team they belong to. Membership tables record who belongs to an organization or workspace; they never record what they can do. When you sign in, Relay resolves:

your strongest role in each organization you belong to,
your permission set at the active organization, and
your permission set in the active workspace.

Owners resolve to full permissions everywhere.

Access resolution

Every request is checked deny-by-default in this order:

Platform/system access — internal service and platform-admin paths, scoped to the target organization.
Cross-tenant guard — a request is denied if its target organization is not the caller's organization.
Self-rule — allowed if the target belongs to the caller and the action is in the self-service whitelist (e.g. your own sessions).
Workspace gate — when the request targets a workspace resource:
- Organization admins and owners bypass the gate (they have org-wide access).
- Everyone else must hold a workspace-scoped role (directly, or via a team) that grants the action. No workspace role → denied. An org-level member or viewer binding does not by itself reach workspace resources.
Organization / team binding — allowed if any of the caller's bindings (direct or via a team) grants the action at the organization scope.

The strict workspace gate is deliberate. To act in a workspace you must be granted a role there — directly or through a team — or be an organization admin/owner. This is the Kubernetes-namespace model applied to Relay's organization → workspace hierarchy: workspace membership is meaningful, not a formality.

Denied requests are recorded with a reason; mutations also emit an entry in the activity log.

Bootstrap defaults

Creating an organization — the creator becomes its owner. The last-owner guard prevents the org from ever having zero owners; ownership moves via transfer.
Creating a workspace — the creator gets a workspace-scoped admin role so they are never locked out by the gate. Existing organization owners and admins are also added to new workspaces as admins. A custom role that holds org.workspaces.create is not added to the workspace it creates, so its holder is stopped by the workspace gate there until someone grants them a role in it.
New members — added to the organization's default workspace so they can work immediately; elevate or restrict them per-workspace with workspace roles.
Promotion — promoting a user to organization admin or owner extends admin access to every workspace (they inherit org-wide access anyway).

Custom roles

Custom roles let you bundle exactly the permissions your team needs and grant them by binding, to a user or a whole team, at the organization or workspace scope. Custom roles are available on Business and Enterprise plans.