Understanding the Workbench Permission Model

The Workbench permission model controls what each user account, service account, and token can do. The model layers several pieces that work together to grant or restrict access.

The permission model controls three kinds of access:

• The model controls which database connections an account can reach.
• The model controls which MCP tools an account can invoke.
• The model controls which administrative operations an account can perform.

The Workbench builds this access from layered pieces using groups, privileges, permissions, and token scopes to manage the layers. Groups collect users and assign shared privileges; privileges define connection and tool access; token scopes narrow what an individual token may do. Administrators manage these pieces with the Administration console or the command line.

How the Pieces Interact

The Workbench evaluates a request by combining the layered pieces in order. An account first inherits privileges from every group it belongs to, including the privileges of any nested groups. A token then applies its scope, narrowing those inherited privileges to the scoped subset.

The following sequence describes how the Workbench resolves access for a request:

1. The Workbench identifies the account that owns the request token.

2. The Workbench collects the privileges from every group the account belongs to, including nested groups.

3. The Workbench applies the token scope, restricting the request to the scoped subset of those privileges.

4. The Workbench grants the request only when the resulting permissions allow the requested operation.

A superuser short-circuits the group lookup in this sequence; the Workbench grants a superuser every privilege without regard to group membership. Step three still applies, so a request that a superuser makes with a scoped API token succeeds only where the token scope allows the operation. A superuser working in a browser session holds every privilege unconditionally, because a session carries no token scope.

Accounts and Roles

Permissions apply to two kinds of accounts.

• A user account authenticates with a username and password to receive a session token.
• A service account provides programmatic access and authenticates only with an API token.

Both account types gain privileges in the same way; each joins groups that hold the privileges the account needs.

A superuser holds a special role that bypasses all permission checks. This allows a superuser to reach every connection, invoke every MCP tool, and perform every administrative operation. An API token that a superuser owns is bound by the scope of that token, so the token reaches only the connections, tools, and administrative permissions its scope names. A superuser may grant or revoke the superuser role when they create or edit an account; the manage_users permission alone does not allow either, and the Workbench refuses a request from any other account that sets or clears the role. Likewise, only a superuser may edit or delete an account that holds the superuser role. For details on creating and managing accounts, see Account Management.

Groups and Privileges

Groups organize accounts and assign shared permissions. The Workbench assigns privileges to groups rather than to individual accounts; an account gains a privilege by joining a group that holds the privilege.

Each group can contain users, service accounts, or other groups. Groups can be nested, and a nested group inherits the parent group's privileges. This approach keeps permission management consistent and auditable.

The Workbench recognizes three kinds of privileges that administrators assign to groups:

• CONNECTION privileges grant access to a specified database connection at a chosen access level.
• ADMIN privileges grant permission to perform administrative actions.
• MCP privileges grant access to specific MCP tools such as query_database or get_schema_info.

A connection privilege grants a group access to one monitored connection at a specified access level. The Workbench supports two connection access levels:

• The read access level allows read-only operations against the connection; the group inspects data and metadata without changing them. A SELECT that calls a function with side effects, such as pg_terminate_backend or set_config, counts as a write and needs the read_write level.
• The read_write access level allows both read and write operations against the connection.

A connection privilege that names a connection also restricts that connection, so that only its owner, the members of groups that hold a grant on the connection, and the members of groups that hold an All Connections grant may reach it. An All Connections privilege gives the members of its group every connection, but restricts no connection for anyone outside the group. The Workbench applies the following rules, in order, to decide whether an account other than a superuser may reach a connection:

1. The owner of a connection always holds read_write access to it, whether or not a group restricts the connection.
2. Any account holds read_write access to a shared connection that no group restricts.
3. An account that belongs to a group holding a grant on the connection, or an All Connections grant, holds the access level of that grant; when both apply, the higher level wins.

The Workbench denies access in every other case. The connection lists that the web client and the MCP tools show apply the same rules, so every listed connection can be opened and every connection an account can open is listed. A token scope then narrows the result for an API token.

An All Connections grant at the read level does not lower a member's access to a shared connection that no grant names; such a connection stays open at read_write to every account, the members of that group included. To keep a group read-only on a connection, grant that connection to the group by name at the read level, and lower or remove any read_write grant that also applies to its members on that connection, such as an All Connections grant at read_write; the higher access level wins.

An ADMIN privilege grants a group permission to perform administrative actions in the Workbench, such as managing users, groups, and connections. Admin privileges are broad by nature and should be granted only to trusted groups.

An MCP privilege grants a group access to named MCP tools. Administrators grant individual tool names rather than broad categories; this keeps each grant explicit and auditable.

Administrators manage group privileges through the Administration console's Permissions page or the command line. The following flags assign and remove privileges for a group:

• The -grant-connection and -revoke-connection flags assign or remove connection access for a group.
• The -access-level flag sets the access level for a connection grant.
• The -grant-privilege and -revoke-privilege flags assign or remove ADMIN privileges or MCP tool access for a group.

For detailed information about creating groups and managing their membership, see Group Management.

Token Scopes

A token carries the permissions of the account that owns it. A token's effective access can never exceed the owner's access; the Workbench always enforces the more restrictive level. An optional token scope narrows what the token can do within the owner's permissions.

A token scope restricts the token without expanding its access. When a token has no scope, the token inherits the full set of the owner's group privileges. The Workbench applies each part of a scope independently; an unrestricted part inherits the owner's full group privileges for that category. The Workbench supports three scope types:

• A connection scope limits the token to specific database connections, each at a read or read_write access level.
• An ADMIN permission scope limits the token to specific administrative operations.
• An MCP privilege scope limits the token to specific MCP tools.

Each scope type supports a wildcard that grants access to all items of that type the owner holds. A connection scope can lower a token to read even when the owner holds read_write access through a group.

A token's effective access also bounds what the token can hand out. The connection and MCP privilege scopes limit what a token can reach, and the admin permission scope limits which administrative actions the token can perform; a token acting as an administrator can, in addition, grant only what it holds itself. No token can grant a group, create or take over a user, mint a token for another owner, or set any token's scope, its own included, in a way that reaches beyond its own effective access, judged for each connection and access level, MCP item and admin permission. The server refuses each such request with 403 Forbidden and records the refusal in the RBAC audit log. The Bounding What a Token Can Grant section explains the design and lists every request the bound covers.

Administrators manage token scopes with the Administration console or at the command line. The following flags control token scopes:

• The -scope-token-connections flag sets the connection scope for a token; pass connection IDs with -scope-connections as a comma-separated list. The command refuses a list that combines connection 0, the All Connections entry, with particular connections, or that names a connection twice, and leaves the stored scope unchanged.
• The -scope-token-tools flag sets the MCP tool scope for a token; pass tool names with -scope-tools as a comma-separated list.
• The -show-token-scope flag displays the current scope for a token, including its connection and MCP restrictions.
• The -clear-token-scope flag removes all scope restrictions from a token, restoring the owner's full group privileges.

Each scope command identifies the target token with the -token-id flag. For details on creating tokens and setting their scopes, see Token Management.

Administrative Permissions

Administrative (or ADMIN) permissions control access to management operations in the Workbench's Administration console and the REST API. Privileged users assign these permissions through groups, alongside connection and MCP privileges. A superuser bypasses these checks and holds every administrative permission automatically, although an API token that a superuser owns holds only the permissions its admin scope names, unless that scope is unset or holds the * wildcard. An endpoint reserved for superusers that names no permission, such as the RBAC audit log, refuses any token whose admin scope names specific permissions.

The Workbench defines the following ten ADMIN permissions:

Each permission allows a specific class of management operation; for example, manage_users allows creating, editing, and deleting accounts.

An administrative permission applies only to what the holder can see. A probe, alert or notification channel override set on a cluster or a cluster group applies to every connection in it, so changing or deleting one requires the holder to see every one of those connections, whilst viewing one needs only one of them to be visible. The same applies to deleting a cluster or a cluster group, and to moving a cluster to another group, since each of those changes which overrides reach the cluster's connections.

A blackout or a blackout schedule on a cluster or a cluster group silences alerts on every connection in it, so creating, changing, stopping or deleting one likewise requires the holder to see every one of those connections. An estate-wide blackout or schedule silences alerts on every connection, so creating, changing, stopping or deleting one requires the holder to see every connection, although every user can view it. A blackout on a connection, cluster or group the holder cannot see at all is answered as though it did not exist.

An alert rule's defaults, a global probe configuration, and a notification channel with its email recipients apply to every connection, so changing an alert rule or a global probe configuration, or creating, changing or deleting a notification channel or a recipient, requires the holder to see every connection, although they stay readable to everyone else. A probe configuration on a single connection, cluster or group follows the rule for overrides above.

A change refused because a member connection is hidden answers in the same way as a missing permission, so it does not reveal which connections are hidden or how many. A connection the holder cannot see cannot be removed from a cluster either; the attempt is answered as though the connection were not a member. Superusers, and users granted access to all connections, see every connection and are not affected.

For detailed instructions about assigning permissions to a group, see Permission Management.

Related Pages

The following pages describe how to manage each part of the Workbench permission model:

• The Account Management page describes how to create and manage user and service accounts.
• The Group Management page describes how to create groups and manage their membership.
• The Token Management page describes how to create tokens and define their scopes.
• The Permission Management page describes how to assign and revoke permissions.