OpenClaw EnterpriseDOCSGitHub

Permissions cheat sheet

Look up which permission OpenClaw Control Plane (OCC) checks for a public operation. A permission is an exact action and resourceKind; a Role grants it through an AccessBinding. Missing grants are denied, matching Restrictions override grants, and one action never implies another. See Authorization for the full policy.

Actions

Action What it permits
create Create a resource in its parent Installation or Namespace.
read Read a resource or include it in a list; Secret reads return metadata, not values.
update Change a resource or its credential.
delete Request deletion of the exact resource.
deploy Create an Agent revision or recover its exact first-deployment receipt.
operate Chat in an Agent browser UI, stop an Agent, provision its runtime credentials, write its workspace files, read its runtime status, or use a bound Secret or credential source.
administer Run Installation administration, access the exact Agent’s native admin UI, or read its runtime log text. It does not imply read, deploy, or other actions.
read_logs Read the exact Agent’s runtime log text without administer. Not granted by bootstrap; grant it through a Namespace Role.
read_audit Read selected audit metadata for one Agent. Requires a direct AccessBinding on the Agent and a human session.

Resources and scopes

This is the set checked by current public operations. Native IAM bootstrap grants most of these pairs to the human administrator and the non-Agent bootstrap service principal. Grant read_logs and read_audit separately.

Resource kind Actions Scope checked
installation read, administer Singleton Installation.
namespace create, read, delete Installation for create; exact Namespace otherwise.
configuration create, read, update, delete Namespace for create; exact Configuration otherwise.
preset create, read, update, delete Namespace for create; list needs Namespace read and returns only Presets with exact read. Exact Preset otherwise.
service_account create, read, update, delete Namespace for create; exact ServiceAccount otherwise. Credential creation also uses update.
secret create, read, update, delete, operate Namespace collection for create; list needs Namespace read and returns only Secrets with exact read. Other actions target the exact Secret. operate is checked when a Secret is bound or used.
credential_source create, read, update, delete, operate Namespace collection for create; list needs Namespace read and returns only sources with exact read. Other actions target the exact source. operate is checked when a source is bound or deployed. update also gates rotation and needs secret:operate on each Secret it reads; Roles bootstrapped before update existed must have it granted.
agent create, read, update, delete, deploy, operate, administer, read_logs, manage_policy, read_audit Namespace for create; exact Agent otherwise. Native chat, administration, and audit reads require a human session. See Read an Agent’s audit events.
sandbox_policy read, update Exact Agent-owned policy, or an exact binding on its Agent. Reads and discovery require Agent read; preview/save/apply require Agent manage_policy and enabled editing; apply also requires read, as do Agent deploy and an Agent update with repository bindings when saved additions exist.
agent_revision read Exact AgentRevision, or an exact binding on its Agent; deployment-status reads use this permission too.

Namespace, Preset, Agent, ServiceAccount, AgentRevision, Secret, and credential source lists check each returned resource. Listing Agents, ServiceAccounts or Presets also requires namespace:read; listing AgentRevisions also requires agent:read on the parent. The HTTP API reference lists exact targets and conditions for each operation.

Sign-in, sign-out, and session lookup use session rules rather than resource permissions. Installation bootstrap and account creation require a human session; service-key administration also accepts an authorized Installation-scoped service key. A Namespace-scoped key cannot access another Namespace or Installation endpoints. An Installation-scoped key still needs its principal’s own grants; it does not inherit the issuer’s. See service key scope. An account created with the Installation administrator roleId holds only installation:administer and installation:read; see Appoint an administrator.

Configured Roles

The Installation iam configuration can declare Installation-level Roles with any permission in the table above except installation ones. OCC writes each as role_config_<id> and binds it only as the configuration says, or to each creator as the ownerRole. See Default users and configured Roles.

Denial messages

A 403 FORBIDDEN for a grant you lack names it and who grants it, for example Not authorized: this needs Agent deploy on Agent agt_1. Ask an Installation administrator to grant it. The Namespace policy API cannot grant create, so a create denial names its Namespace and says only an Installation administrator can create it. The message does not mention configured Roles, which can also grant create. The message names a resource ID only when your request sent it in the path or an ID field, or you can already read that resource, never a binding, Role or Restriction. A Secret or credential source that an Agent, Configuration or credential source binds is named only when you can also read the record that binds it. Log text needs Agent read_logs (or Agent administer). A Restriction, a missing grant and a resource that does not exist get the same message. A denial about your own account, session or provisioning job says so: The acting account is disabled., The acting identity is unavailable., The human administrator session is no longer current., The assigning session is no longer current., Only the initiating actor can retry provisioning. or Only the initiating actor can read provisioning status. A denial that names no grant says The exact platform operation was not authorized.

Additional checks

The Namespace policy API accepts the per-kind actions in the table above on agent, agent_revision, configuration, credential_source, preset, secret, and service_account, except create. It refuses, with 400 INVALID_REQUEST, a Role with a combination no operation checks, such as secret:read_logs or configuration:deploy, because it would grant nothing, and a Role with any create Permission, which no exact-resource binding can grant. On namespace it accepts only read. It can bind an existing human Principal or a Namespace-local ServicePrincipal to an existing exact resource, including the path Namespace itself. Exact Namespace access does not grant access to child resources. It cannot create Installation or Namespace-wide grants, including the collection permission needed to create resources. Existing Namespace-wide and Group bindings can still be listed or deleted. Groups and Restrictions cannot be managed through this API.

Per-Agent policy editing configuration requires Installation and exact-Agent administer. See policy authority.

Search documentation