Access Control for Agents, Skills, and More

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

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: 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 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, not from policies on a single resource.

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

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
`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. `*` 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. 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}.

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

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
`skill`	`use`
`plugin`	`use`
`artifact`	`download`
`team`	`join`, `share_assets` (both reserved; team membership and adding assets to a team follow team roles)
`agent_account`	Its own set, with no shared actions. See Agent accounts
`org`	Organization permissions, with no shared actions. See 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

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
`view_runs_own`	Reserved
`config:*` and the other `config:` actions	Agent settings governed by agent configuration policies (beta). `*` doesn’t cover them, an owner’s access included, and only policy administrators write them

Agent accounts

Agent accounts 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, DPoP, 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.

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, 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 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
`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 discoveries
`view_ai_inventory`	Viewing the AI inventory
`access_deploy`	Using Runlayer Deploy
`use_management_api`	Calling the management API
`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, 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
`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": ["*"].

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

{
  "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 as Tool Call Rate Limited.

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

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.

Access Control Cookbook - Copy-paste recipes for every resource type
Connector Access Control - Connector policies, conditions, and approvals
Agent Accounts - Identities for autonomous agents and services
Teams - Sharing resources with groups of people
Roles & Permissions - Built-in roles and the permissions they carry

Enable

Control

Self-Hosted Deployment

Operations

Cookbook

Integrations

Connectors

Resources

Access Control for Agents, Skills, and More

How It Works

Evaluation

Writing a Policy

Resource Types and Actions

Agents

Agent accounts

Organization permissions

Principals

Presets

Approvals and Rate Limits

Who Can Write Policies

​How It Works

​Evaluation

​Writing a Policy

​Resource Types and Actions

​Agents

​Agent accounts

​Organization permissions

​Principals

​Presets

​Approvals and Rate Limits

​Who Can Write Policies

​Related Documentation

How It Works

Evaluation

Writing a Policy

Resource Types and Actions

Agents

Agent accounts

Organization permissions

Principals

Presets

Approvals and Rate Limits

Who Can Write Policies

Related Documentation