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

# Roles & Permissions

> Manage admin roles and platform capabilities

## How Authorization Works in Runlayer

Runlayer uses two independent authorization layers:

<CardGroup cols={2}>
  <Card title="Fine-Grained Access (FGA)" icon="user-shield">
    Controls who can access **platform features** — managing MCPs, viewing audit logs, creating policies, configuring settings. Enforced on every dashboard API endpoint. **This is what roles and capabilities control.**
  </Card>

  <Card title="Policy-Based Access Control (PBAC)" icon="filter">
    Controls what happens when users **invoke MCP tools** through the proxy. Policies evaluate conditions like IP range, tool name, or OAuth status at call time. See [Policies](/platform-policies).
  </Card>
</CardGroup>

|                    | FGA (Roles)                                   | PBAC (Policies)                                             |
| ------------------ | --------------------------------------------- | ----------------------------------------------------------- |
| **Controls**       | Platform features (dashboard, API)            | MCP tool invocations                                        |
| **Enforced at**    | API endpoints                                 | MCP proxy                                                   |
| **Configured via** | Role assignment or SCIM group-to-role mapping | Access policies                                             |
| **Example**        | "Can this user view audit logs?"              | "Can this user call `query_database` on the Snowflake MCP?" |

A user needs **both**: the right role to access platform features, AND a matching policy to call MCP tools.

***

## Roles

| Role                | Description                                                            |
| ------------------- | ---------------------------------------------------------------------- |
| **Super Admin**     | Full platform access. Manages roles, settings, and all features.       |
| **Security Admin**  | Monitors security, manages policies, reviews audit logs and user info. |
| **IT Admin**        | Manages connectors, policies, and user MCP access.                     |
| **Analytics Admin** | Views org-wide metrics, audit logs, and exports usage data.            |
| **Developer**       | Deploys MCPs, manages agent accounts, uses the management API.         |
| **Helpdesk**        | Views user info and audit logs for support purposes.                   |
| **User**            | Uses assigned MCPs only. No admin features.                            |

<Note>
  Users without any admin role are assigned the **User** role by default. They can only use MCPs they have been granted access to.
</Note>

***

## Capability Matrix

Each role grants a fixed set of capabilities. Super Admin has all capabilities. To see the full, up-to-date matrix, go to **Settings → Roles** in your Runlayer dashboard.

<Info>
  The capability matrix is updated as new features arrive. The live version in **Settings → Roles** is always the source of truth.
</Info>

***

## Where to Find Key Settings

Admin configuration lives under **Settings** in the Runlayer dashboard. Which pages a user can see and change depends on their role capabilities. Quick map:

| Settings page                        | What it configures                                                                  | Docs                                                               |
| ------------------------------------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **Settings → Users**                 | User accounts and role assignments                                                  | [Assigning Roles](#assigning-roles)                                |
| **Settings → Roles**                 | Live capability matrix for each role                                                | [Capability Matrix](#capability-matrix)                            |
| **Settings → General**               | Directory sync (SCIM), full session scanning, OAuth redirect URIs, agent run limits | [Sessions](/platform-sessions), [Connectors](/platform-connectors) |
| **Settings → Policies**              | Global access policies (PBAC)                                                       | [Policies](/platform-policies)                                     |
| **Settings → Security Scanners**     | ToolGuard scanners, PII rules, skill risk policy, session scanning (AgentGuard)     | [ToolGuard Models](/runlayer-toolguard), [AgentGuard](/agentguard) |
| **Settings → AI Providers**          | LLM providers and recommended model for agents                                      | [Agents](/platform-agents)                                         |
| **Settings → Agent Accounts**        | Agent account credentials for programmatic access                                   | [Agent Accounts](/platform-agent-accounts)                         |
| **Settings → Integrations**          | Slack integration and Runlayer Assistant                                            | [Slack Notifications](/platform-slack-notifications)               |
| **Settings → MDM Configuration**     | AI Watch deployment via MDM                                                         | [Deploy AI Watch](/shadow-ai/deploy)                               |
| **Settings → User mapping**          | Resolve unresolved device usernames to Runlayer users                               | [Identity Mapping](/shadow-ai/identity-mapping)                    |
| **Settings → AI Clients**            | Manage the organization's AI client allowlist                                       | [Detect](/shadow-ai/detect)                                        |
| **Settings → Personal API keys**     | API keys tied to your user identity                                                 | [Management API](/platform-api)                                    |
| **Settings → Organization API keys** | Organization-scoped API keys (e.g. Deploy, AI Watch Scan roles)                     | [Management API](/platform-api)                                    |
| **Settings → Workspace**             | Workspace-level options, e.g. showing admin setup instructions to all users         | —                                                                  |

***

## Separation of Duty

Certain role combinations cannot be assigned to the same user to prevent conflicts of interest:

| Forbidden combination      | Reason                                                      |
| -------------------------- | ----------------------------------------------------------- |
| Security Admin + IT Admin  | Separates security oversight from infrastructure management |
| Security Admin + Developer | Separates security policy control from code deployment      |

If you attempt to assign a forbidden combination, the assignment will fail with an error. To resolve, remove one of the conflicting roles first.

Role separation controls platform administration. It does not automatically prevent someone who creates an agent from later being granted permission to use that agent; agent usage is controlled by agent sharing, connector policies, and MCP access policies. For high-risk agents, keep creator/admin roles narrow, share the agent to a pilot group at **Can use**, and grant only the connector tools that group needs.

***

## Assigning Roles

Use these steps when SCIM is not enabled.

<Steps>
  <Step title="Navigate to Users">
    Go to **Settings → Users** and select the user you want to manage.
  </Step>

  <Step title="Edit Roles">
    Click **Edit** next to the user's current role(s).
  </Step>

  <Step title="Select Role(s)">
    Choose one or more roles from the dropdown. Users can hold multiple roles — their capabilities are the union of all assigned roles.
  </Step>

  <Step title="Save">
    Confirm the assignment. Changes take effect immediately.
  </Step>
</Steps>

<Warning>
  Only users with the **Manage Admins** capability (Super Admin) can assign or remove roles.
</Warning>

<Note>
  If SCIM is enabled, roles cannot be assigned manually here. See the [SCIM Role Sync](#scim-role-sync) section below for more details.
</Note>

***

## SCIM Role Sync

When SCIM is enabled, manual roles and groups assignments are not supported. Your identity provider (e.g. Okta, Azure AD, Google Workspace) becomes the source of truth.

* Groups can be updated via the SCIM configuration in your identity provider.
* Roles are determined by the groups-to-roles mapping. To configure this, go to **Settings → General → Manage Directory Sync** and scroll down to the "Role assignment" section.

Note: forbidden role combinations are enforced during sync: if the IdP assigns conflicting roles (e.g. Security Admin + IT Admin), the sync skips the conflicting assignment and logs a warning.

***

## Migration from Admin to Super Admin

Previously, Runlayer had a single **Admin** role with full permissions. This has been replaced by **Super Admin** and several specialized roles.

**What changed:**

* All existing Admin users have been automatically migrated to **Super Admin**
* No permissions changed — Super Admin has the same capabilities as the old Admin role
* No action is required from your side

**Recommended next step:** Review your Super Admin users and consider whether a narrower role (Security Admin, IT Admin, etc.) would be more appropriate. Specialized roles reduce blast radius if an account is compromised.

***

## Best Practices

<AccordionGroup>
  <Accordion title="Start with the narrowest role">
    Assign the most specific role that covers the user's responsibilities. You can always add more roles later. A security analyst likely needs Security Admin, not Super Admin.
  </Accordion>

  <Accordion title="Prefer specialized roles over Super Admin">
    Super Admin should be limited to a small number of trusted users. Most admin tasks are covered by Security Admin, IT Admin, or other specialized roles.
  </Accordion>

  <Accordion title="Review role assignments quarterly">
    People change teams. Remove roles that are no longer needed. Check that separation of duty rules are still appropriate.
  </Accordion>

  <Accordion title="Respect separation of duty">
    The forbidden role combinations exist for good reason. If someone needs capabilities from both Security Admin and IT Admin, consider whether the tasks can be split between two people instead.
  </Accordion>
</AccordionGroup>

***

## Related Documentation

<CardGroup cols={2}>
  <Card title="Policies" icon="filter" href="/platform-policies">
    Configure PBAC policies for MCP tool access
  </Card>
</CardGroup>