> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runlayer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Access Control for Agents, Skills, and More

> Control who can use and manage agents, skills, plugins, artifacts, agent accounts, teams, and organization permissions with the same policies as connectors.

> [!WARNING]
>
> **Early Access Feature**: Policies beyond connectors are in early access and are not enabled for workspaces by default. Contact your Runlayer team to turn them on. Until then, [connector policies](https://docs.runlayer.com/platform-policies.md) keep working as they do today, and a policy on any other resource answers `409` with code `unified_policy_engine_inactive`. So does a connector policy the connector format can't express, such as a rate limit or a `team` principal. Owners and sharers may get `403` instead.

[Connector policies](https://docs.runlayer.com/platform-policies.md) decide who can call which tools. The same policies extend to everything else in Runlayer: agents, skills, plugins, artifacts, agent accounts, teams, and the organization itself. Sharing an agent, giving someone an admin permission, and letting one person rotate an agent account's secret are all policies, decided by the same rules as connector access.

For copy-paste examples covering every resource type, see the [Access Control Cookbook](https://docs.runlayer.com/cookbook-access-control.md).

## How It Works

Every policy answers one question: who can do what to which resource, and under which conditions.

| Part | What it says | Example |
| - | - | - |
| **Principal** | Who the policy applies to | The **Support** group |
| **Effect** | Whether it grants or takes away | `allow` |
| **Resource** | What it applies to | The **Triage** agent |
| **Actions** | What the principal can do | `view`, `run` |
| **Conditions** | Optional runtime rules | Only from the corporate IP range |

Shares you create in the share dialog, the access a resource's owner has, and the permissions that come with each role are stored as policies of the same shape. You don't write those yourself; Runlayer keeps them in step as you share, transfer, and assign roles.

### Evaluation

Policies combine the same way as [connector rules](https://docs.runlayer.com/platform-policies.md#how-rules-combine): no access by default, allows add up, and deny wins. Two details matter more once policies cover every resource:

* **Deny beats everything.** A matching deny removes the action even from the resource's owner, from anyone it was shared with, and from resources shared with the whole organization. "Everyone except group X" is an `org` allow plus a `group` deny.
* **Actions are flat.** No action implies another. Granting `manage_access` does not grant `view`, so list every action the principal needs.

Super admins are the organization's root account. To restrict one, have a policy administrator write the deny on the resource. That is the only kind of deny certain to apply to a super admin. Don't rely on a deny written by a resource's owner or sharer, or on an [organization permission](#organization-permissions) deny.

A few checks run before resource policies are evaluated and are not subject to them. A connector's owner, or its creator while it's still a draft, and holders of the connector-management permission open the connector without a policy check. Calling its tools still goes through connector policies, and editing an active connector or deleting one takes the connector-management permission. Role permissions, such as **Manage security policies**, come from your roles and from [organization permissions](#organization-permissions), not from policies on a single resource.

> [!NOTE]
>
> Enforcement is live on every open, run, call, and download. List pages don't yet subtract deny policies, so a resource shared with everyone that you've been denied can still appear in a list; opening it answers `403`.

***

## Writing a Policy

Policies are managed in **Settings → Policies** and through `POST /api/v1/policies`, the same endpoint as [connector policies](https://docs.runlayer.com/platform-policies.md#api). Instead of the connector format's `action` and `scope`, they name an `effect`, a `resource`, and the `actions` it covers. The examples on this page use the `RUNLAYER_URL` and `API_KEY` conventions from the [access control recipes](https://docs.runlayer.com/cookbook-access-control.md#prerequisites).

```bash theme={null}
curl -s -X POST "$RUNLAYER_URL/api/v1/policies" \
  -H "x-runlayer-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principal": { "type": "group", "ids": ["'$GROUP_ID'"] },
    "kind": "permission",
    "effect": "allow",
    "resource": { "type": "agent", "ids": ["'$AGENT_ID'"] },
    "actions": ["view", "run"],
    "description": "Support group can run the triage agent",
    "conditions": []
  }' | jq '{id, principal, effect, resource, actions}'
```

| Field | Description |
| - | - |
| `principal` | Who the policy applies to. See [Principals](#principals) |
| `kind` | `permission`, `approval_requirement`, or `rate_limit`. Defaults to `permission` |
| `effect` | `allow` or `deny`. Required for `permission`; omit it for the other kinds |
| `resource` | `{ "type": "<type>", "ids": ["<uuid>"] }` for specific resources, `{ "type": "<type>", "all": true }` for every resource of a type, or `{ "type": "org" }` for organization permissions |
| `actions` | Action names valid for the resource type. See [Resource Types and Actions](#resource-types-and-actions). `*` matches every action on the type except agent configuration actions |
| `description` | Shown in the policy list |
| `conditions` | Optional rule groups, the same as connector policies. See [Condition Field Reference](https://docs.runlayer.com/platform-policies.md#condition-field-reference). Payload conditions only make sense with connector tool actions. Access to agents, skills, plugins, and artifacts is checked with no request to test a condition against, so there a conditional allow grants nothing and a conditional deny always applies |

To change a policy, send the fields you want to change to `PUT /api/v1/policies/{policy_id}`. To remove it, call `DELETE /api/v1/policies/{policy_id}`.

> [!TIP]
>
> Connector policies you already have keep working unchanged. A policy in this format on one connector, naming a user, group, role, agent account, attributes, or Everyone, is saved as a regular connector policy when its actions follow the connector layout, so it also works before early access is turned on. An allow or approval lists `view`, `use`, then `call_tool:` entries, then `read_resource:` entries, with at least one of each of the last two. A deny lists the `call_tool:` and `read_resource:` entries, and starts with `view` and `use` only when it covers `call_tool:*` and `read_resource:*`. Like any connector policy, it needs the security-policies permission.

***

## Resource Types and Actions

Every resource type except agent accounts, sessions, and the organization carries the shared actions:

| Shared action | Allows |
| - | - |
| `view` | Seeing the resource and its details |
| `edit` | Changing the resource's configuration |
| `share` | Granting others access, up to the actions you hold yourself |
| `manage_access` | Changing and removing others' access, including grants you didn't create |
| `delete` | Deleting the resource |
| `transfer_ownership` | Reserved. A resource's owner can transfer it, and so can anyone granted the `transfer_resource_ownership` [organization permission](#organization-permissions) |

Each type adds its own actions:

| Resource type | Additional actions |
| - | - |
| `connector` | `use`, `call_tool:*` or `call_tool:<name>`, `read_resource:*` or `read_resource:<uri>`, plus `edit_security`, `run_diagnostics`, and `view_metrics`, which follow role permissions today: a connector's security settings come with **Manage security policies**, and a grant on one connector doesn't change who can edit them |
| `agent` | `run`, `copy`, `view_runs_all`, `view_runs_own`, and `config:` actions. See [Agents](#agents) |
| `skill` | `use` |
| `plugin` | `use` |
| `artifact` | `download` |
| `team` | `join`, `share_assets` (both reserved; team membership and adding assets to a team follow [team roles](https://docs.runlayer.com/platform-teams.md#team-roles-and-asset-access)) |
| `agent_account` | Its own set, with no shared actions. See [Agent accounts](#agent-accounts) |
| `org` | Organization permissions, with no shared actions. See [Organization permissions](#organization-permissions) |
| `session` | `view_content` and `view_tool_calls`, deciding who reads a session's content, without conditions. Session policies are turned on separately from this early access; contact your Runlayer team |
| `policy` | Reserved |

> [!NOTE]
>
> Connectors are the exception to owner access. Owning a connector grants `view` only; who can call its tools comes from connector policies. Administrators with the security-policies permission write any of them. Once early access is on, someone an administrator has granted `share` on the connector can also write the ones the connector format can't express, such as policies naming a team, the organization, or owners, and rate limits, within the actions they hold. A policy the connector format can express, such as one naming users or groups, needs the security-policies permission.

### Agents

| Action | Allows |
| - | - |
| `run` | Running the agent |
| `copy` | Making a personal copy of the agent in Runlayer Go. Needs `run` alongside it |
| `view_runs_all` | Seeing every run of the agent on its **Sessions** tab without edit access. A deny hides other people's runs whatever the share level. On Runlayer-managed agents, such as the Runlayer Assistant, only edit access shows other people's runs. See [Who can see an agent's runs](https://docs.runlayer.com/platform-agents.md#who-can-see-runs) |
| `view_runs_own` | Reserved |
| `config:*` and the other `config:` actions | Agent settings governed by [agent configuration policies](https://docs.runlayer.com/platform-policies.md#agent-configuration-policies) (beta). `*` doesn't cover them, an owner's access included, and only policy administrators write them |

### Agent accounts

[Agent accounts](https://docs.runlayer.com/platform-agent-accounts.md) aren't shared like other resources. Each management task is its own action, so you can hand someone exactly one responsibility for one account.

| Action | Allows |
| - | - |
| `view` | Seeing the account and its configuration |
| `edit` | Changing the name and description, and disabling the account |
| `edit_security` | Changing every security setting: [server scoping](https://docs.runlayer.com/platform-agent-accounts.md#resource-scoping-enforcement), DPoP, [strict mode](https://docs.runlayer.com/platform-agent-accounts.md#strict-mode) and its login redirect URIs, and the token and delegation lifetimes. Also re-enabling a disabled account. Needs `edit` alongside it |
| `edit_permissions` | Adding and removing the account's connectors and the tools it can call |
| `rotate_credentials` | Issuing a new client secret |
| `delete` | Deleting the account |
| `use` | Creating and revoking your own delegations and session grants for the account |

The account's owner holds all of these. An `edit` grant alone reaches neither the security settings nor rotation, and someone who can only disable an account can't re-enable one a security team turned off.

> [!WARNING]
>
> `rotate_credentials` returns a new client secret, which lets its holder act as the account. Grant it, and `edit_security`, only to someone you would trust with the account's credentials.

Identity attributes stay with agent account administrators. They decide which attribute-based policies the account matches, so no grant or ownership changes them. Who can create agent accounts is an [organization permission](#organization-permissions), `create_agent_account`.

### Organization permissions

Organization permissions grant or take away a role permission for specific people without changing their role. They use `{ "type": "org" }` with no ids. An allow adds the permission on top of what the person's roles give them; a deny takes it away, even from someone whose role includes it. The [capability matrix](https://docs.runlayer.com/platform-roles.md#capability-matrix) in **Settings → Roles** shows which roles hold each permission today.

These actions each make up a whole permission, so an allow on its own grants it:

| Action | Allows |
| - | - |
| `view_audit_logs_own` | Viewing your own [audit logs](https://docs.runlayer.com/platform-audit-logs.md) |
| `view_audit_logs_all` | Viewing everyone's audit logs |
| `view_unredacted_content` | Viewing audit log content that is redacted by default |
| `manage_audit_redaction` | Changing audit log redaction settings |
| `view_ai_outputs_all` | Viewing what the model wrote in anyone's session |
| `view_agent_universe` | Viewing the Agent Universe, which shows the organization's agents, sessions, and Shadow AI discoveries in one view |
| `export_usage_data` | Exporting usage data |
| `view_user_info` | Viewing user and group information |
| `view_catalog`, `manage_catalog` | Browsing or managing the connector catalog |
| `view_shadow_mcp` | Viewing [Shadow AI](https://docs.runlayer.com/shadow-ai.md) discoveries |
| `view_ai_inventory` | Viewing the AI inventory |
| `access_deploy` | Using [Runlayer Deploy](https://docs.runlayer.com/platform-deploy.md) |
| `use_management_api` | Calling the [management API](https://docs.runlayer.com/platform-api.md) |
| `manage_org_settings` | Changing organization settings. A deny also takes away managing identity providers |
| `manage_mdm_config` | Managing MDM configuration |
| `transfer_resource_ownership` | Transferring resources you don't own |
| `manage_admins` | Assigning and removing administrators |
| `request_session_break_glass`, `approve_session_break_glass` | Requesting, or approving someone else's request for, temporary access to a protected session |
| `create_skill`, `create_plugin` | Using skills or plugins in Runlayer and its API: creating your own, and opening ones shared with you or with the whole organization. A deny takes that away, not only creating |

These actions are one part of a broader permission. An allow grants the permission only when the person also holds the other parts, through their roles or other organization allows, and a deny on any one part removes the whole permission:

| Action | Part of |
| - | - |
| `view_metrics_all` | Viewing organization-wide [analytics](https://docs.runlayer.com/platform-analytics.md), together with per-connector metrics |
| `manage_security_policies`, `manage_policies` | **Manage security policies**, together with connector security settings |
| `manage_identity_providers` | Managing identity providers, together with `manage_org_settings` |
| `create_connector` | Managing connectors |
| `create_artifact` | Using agents, which also covers creating artifacts. A deny stops a person using agents, not only creating artifacts |
| `create_agent_account` | Managing agent accounts. On its own, an allow still lets a person create agent accounts; Developers hold it by default |
| `create_team` | Managing teams |

`create_agent` is checked alongside using agents, and everyone who can use agents holds it by default. A deny stops a person creating agents and leaves using agents and creating artifacts alone.

`use_agents`, `use_teams`, `use_assigned_connectors`, `override_connector_access`, `use_procedures`, and `manage_procedures` stand for role permissions that switch a feature on. They don't reach any resource by themselves, but a deny takes the feature away: denying `use_agents` stops a person using and creating agents. `view_metrics_own` grants and denies nothing.

Organization policies have a few rules of their own:

* You can only grant or deny organization permissions you hold yourself, so a policy administrator can't hand out `manage_admins`.
* They take a user, group, role, team, attributes, `org`, or Everyone principal. Agent account and `owner` principals, and approval requirements, are refused.
* A permission check has no tool call behind it, so a condition on tool arguments or request context reads as unknown: a deny with one still applies, and an allow with one grants nothing.
* A change can take up to five minutes to reach every request.
* You can't change or remove an organization deny that applies to you unless you hold `manage_admins`.
* Don't rely on an organization deny to restrict a super admin.

***

## Principals

| Type | Selector | Matches |
| - | - | - |
| `user` | `{ "type": "user", "ids": [...] }` | The listed users |
| `group` | `{ "type": "group", "ids": [...] }` | Members of the listed groups |
| `role` | `{ "type": "role", "ids": [...] }` | Users holding the listed roles |
| `team` | `{ "type": "team", "ids": [...] }` | Members of the listed [teams](https://docs.runlayer.com/platform-teams.md) |
| `agent` | `{ "type": "agent", "ids": [...] }` | The listed agent accounts |
| `attributes` | `{ "type": "attributes", "attributes": { "department": "Finance" } }` | Users and agent accounts whose attributes equal every listed value (exact equality, primitives only) |
| `org` | `{ "type": "org" }` | Every member of the organization |
| `any` | `{ "type": "any" }` | Any authenticated subject (**Everyone** in the UI) |
| `owner` | `{ "type": "owner" }` | Whoever owns the resource being checked. Used by the built-in owner policies; not something you normally write |

`team`, `org`, and `owner` work only in the format on this page, not in the connector format with `action` and `scope`. These are the only spellings the API accepts: `agent_account`, `all: true`, and `attrs` principals answer `422`, as does `"ids": ["*"]`; use `agent` for agent accounts and `org` or `any` for everyone. Responses echo the same spellings, except that a built-in every-user or every-agent policy reads back as `"ids": ["*"]`.

> [!TIP]
>
> Prefer `group`, `team`, or `role` over long lists of users. Membership changes from your identity provider apply on their own, without editing the policy.

***

## Presets

Viewer, Editor, and Manager are named bundles of actions. The share dialog's **Can use** level is Viewer and its **Can edit** level is Manager; **Editor** is an API bundle. They expand to raw actions, so writing the same actions by hand has the same effect.

| Preset | Actions |
| - | - |
| Viewer | `view` plus the actions that use the resource: `use` and `call_tool:*` on connectors, `run` and `copy` on agents, `use` on skills and plugins, `download` on artifacts. Teams have no such action, so Viewer on a team is `view` only |
| Editor | Viewer plus `edit` and `share` |
| Manager | Editor plus `manage_access` |

`delete` and `transfer_ownership` are never in a preset. Agent accounts, sessions, and organization permissions have no presets; list their actions.

***

## Approvals and Rate Limits

Policies carry the same [human approval rules](https://docs.runlayer.com/platform-policies.md#human-approval) as connector policies, plus rate limits.

An `approval_requirement` pauses matching connector tool calls until someone approves them. It has no `effect`, and it applies to connectors only. Approval rules are in beta.

```json theme={null}
{
  "principal": { "type": "any" },
  "kind": "approval_requirement",
  "resource": { "type": "connector", "ids": ["<connector-id>"] },
  "actions": ["call_tool:create_refund"],
  "description": "Refunds need approval"
}
```

A `rate_limit` caps how many matching tool calls go through in a fixed window. `window` is `minute`, `hour`, or `day`. `per` is `user`, `session`, or `org` and decides whose calls share one count. Calls over the limit are refused and appear in the [audit log](https://docs.runlayer.com/platform-audit-logs.md) as **Tool Call Rate Limited**.

```json theme={null}
{
  "principal": { "type": "any" },
  "kind": "rate_limit",
  "resource": { "type": "connector", "ids": ["<connector-id>"] },
  "actions": ["call_tool:*"],
  "rate_limit": { "max_calls": 100, "window": "hour", "per": "user" },
  "description": "100 calls per hour per user"
}
```

Rate limits apply to connector resources and `call_tool` actions only. Both examples name `any` so they also cover agent accounts acting on their own; `org` covers only people, and agents acting for them.

***

## Who Can Write Policies

* **Administrators** with the security-policies permission write any policy, except organization permissions they don't hold themselves.
* **Owners and sharers.** The owner of an agent, skill, plugin, artifact, or team, or anyone granted `share` on it, writes policies on exactly that resource. A grant is bounded by what its author holds: the owner can grant any action, everyone else only the actions they hold. The owner can also deny anyone. Someone with `share` can deny only named users or agent accounts who don't own the resource, and only actions they hold themselves. Owners and sharers can't write policies on Runlayer-managed agents, or agent configuration rules.
* **Access managers.** Anyone granted `manage_access` on a resource changes or removes others' grants on it.
* **Agent accounts.** An agent account isn't shareable, so only administrators with the security-policies permission write policies on it.
* **Agent account connectors.** An agent account's connector policy (a connector-shape allow naming exactly one agent account, on one connector, without conditions) can also be written by agent account administrators and by anyone holding `edit_permissions` on that account, the account's owner included. Unless they administer agent accounts or connectors, or own the connector, the tools are limited to the ones they can call themselves, and `"*"` is saved as that list. Writing one for an account and connector that already have one updates its tools; if that existing policy also covers other accounts or connectors, the write answers `409`. A policy naming several accounts is written by administrators with the security-policies permission. See [Who can add a connector](https://docs.runlayer.com/platform-agent-accounts.md#who-can-add-a-connector).

Administrators with the security-policies permission can change or remove any deny; an organization deny that names them also needs `manage_admins`. Anyone else changes a deny only as the resource's owner, or as its author when the deny doesn't name them.

Two guardrails apply to every write. The built-in role and owner policies are read-only. A change that would leave the organization with no super admin able to manage admins and security policies is rejected, so you can't lock yourself out.

***

## Related Documentation

* [Access Control Cookbook](https://docs.runlayer.com/cookbook-access-control.md) - Copy-paste recipes for every resource type
* [Connector Access Control](https://docs.runlayer.com/platform-policies.md) - Connector policies, conditions, and approvals
* [Agent Accounts](https://docs.runlayer.com/platform-agent-accounts.md) - Identities for autonomous agents and services
* [Teams](https://docs.runlayer.com/platform-teams.md) - Sharing resources with groups of people
* [Roles & Permissions](https://docs.runlayer.com/platform-roles.md) - Built-in roles and the permissions they carry


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.