Roles & permissions

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. 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.

​

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: 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.

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