> ## Documentation Index
> Fetch the complete documentation index at: https://docs.komodor.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Roles & permissions
> Capabilities, policies, and roles — how default-deny access is composed, and the three ways to scope a grant to the right resources.
Every identity in a workspace — a member, a service account, or an agent — acts through **roles**
that decide what it may do. This page explains the built-in roles, the three-layer model they are
built from, and how to scope a grant so an identity reaches exactly the resources it should. You
manage all of it under **Settings → Roles**, **Policies**, and **Access explorer**.
## Built-in roles
Built-in roles are listed under **Settings → Roles** with their type — **built-in** or **custom** —
the policies behind them, and how many identities hold each one. They are displayed with a
`builtin:` prefix — `builtin:admin` — so your own roles can use the plain names without colliding.
Built-in role names are fixed; the policies behind them can still be customized.
| Role | What it is for |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Owner** | The full capability catalog, workspace-wide. Granted automatically to the first person in a new workspace, and the last owner can never be removed — a workspace cannot lock itself out. |
| **Admin** | A delegated administrator; today it confers the same full catalog as Owner. |
| **Developer** | Builds and tests: agents, workflows, knowledge bases, judges, and the tool surface, plus binding existing credentials to what they build. Cannot manage members, secrets, workspace integrations, or the authorization model itself. |
| **Operator** | Runs the platform in production: invokes agents, manages and cancels runs, owns triggers and channels, drives chat and tool calls, triages issues. Does not build, and does not administer identity or secrets. |
| **Member** | The default for new people. Day-to-day use — invoke agents, run workflows, chat, search knowledge, read quality and issues — without building or administering. |
| **Viewer** | Every read capability and nothing else. Can look at everything, including the audit log, and change nothing. |
| **Agent** | The least-privilege default granted to an agent at registration. Roughly the Developer surface minus the credential-minting actions an autonomous worker must never hold. |
Defaults are deliberately conservative: the first person becomes **Owner**, everyone after that is a
**Member**, and a freshly registered agent gets **Agent**. An owner or admin can change any
assignment at any time.
Custom roles sit in the same list, marked **custom**, and are assigned exactly like built-in ones.
## The three layers
* **Capabilities** are the individual actions the platform authorizes — invoking an agent, reading a
run, managing a trigger, creating an API key. Every governed route checks exactly one.
* **Policies** are named bundles of capability grants, managed under **Settings → Policies**, each
with its own scope. Policies organize; they never restrict.
* **Roles** link one or more policies, and a role is what you assign. When a role is granted, the
identity receives the capabilities from those policies.
A **grant** is what binds the two ends together: it binds a subject to a role or to a capability,
over a resource scope. The Policies screen lists them on its **All grants** tab.
Access is **additive and default-deny**. An identity's access is the union of every grant reaching
it, and an action with no matching grant is denied. Within a single grant every condition must hold
— the capability, the resource scope, and any selector or expiry.
### What the capabilities cover
Capabilities are grouped by the area they act on: agents, runs, workflows, triggers and schedules,
channels and routing, chat, knowledge bases, quality and issues, credentials and secrets,
integrations, the MCP Gateway, identity and access, workspace settings and audit, and the
authorization model itself.
The console follows the same gates. A settings tab you lack the capability for renders locked with
an explanation, and an action you cannot perform does not appear as a button. The server enforces
every action regardless of what the console shows.
## Scoping a grant
A role decides *what* an identity can do; each grant inside it decides *which resources* that
applies to. There are three ways to express scope, and they compose.
### Workspace-wide
The default: the capability applies to every resource of that kind in the workspace — read any run,
invoke any agent. This is what the built-in roles use.
### One resource, or a pattern
Pin a grant to a single resource by id, or cover a group with a glob pattern using `*` as the only
wildcard:
| Pattern | Matches |
| --------------- | --------------------------------------------------- |
| `payments-*` | Every agent whose id starts with `payments-` |
| `*-staging` | Ids ending in `-staging` |
| `prod-*-worker` | Ids starting with `prod-` and ending with `-worker` |
Every other character matches literally, and the pattern must match the **whole** id — `payments-*`
matches `payments-refunds`, never `refunds-payments`.
### Labels
Patterns depend on naming discipline; labels scope by meaning. Attach `key = value` labels to
resources and scope a grant to a selector that matches them:
* A grant scoped to `team = payments` reaches every resource carrying that label, whatever it is
called.
* Keys and values are yours to choose — `team`, `env`, `region`, whatever dimension fits.
* A selector can reference the acting identity's own attributes. `team = $principal.team` means
"resources whose team matches the caller's own" — one grant that gives every member access to
their own team's resources.
A selector that references an attribute the identity does not have **fails closed** and matches
nothing. A missing attribute can only narrow access, never widen it.
**Where labels live.** Agents, credentials, channels, knowledge bases, MCP servers, and workflows
are labeled directly, each with its own label editor. Runs, chat sessions, triggers, and schedules
inherit the labels of the agent they belong to. Attributes on people and service accounts are
edited from their own settings screens.
### Expiry
Any grant can carry an expiry, so temporary access cleans itself up instead of lingering until
somebody audits it.
## Next steps
Ask what an identity can do, and test one action against one resource.
The same model applied to a non-human principal.
The runtime check that sits on top of a permission.
Every role, policy, grant, and attribute change is recorded.
## Related topics
- [Before you begin](/get-started/before-you-begin.md)
- [Accounts & members](/security-and-governance/identity-and-access/accounts-members.md)
- [Control plane](/get-started/architecture/control-plane.md)
- [API keys](/security-and-governance/identity-and-access/api-keys.md)
- [Service accounts](/security-and-governance/identity-and-access/service-accounts.md)