> ## Documentation Index
> Fetch the complete documentation index at: https://docs.genesiscomputing.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Security Controls
> Comprehensive security controls for managing user access, roles, permissions, and tool usage in Genesis Data Agents
## Overview
Genesis Data Agents provides enterprise-grade security controls through a multi-layered approach to access management. Administrators can control what users can see, which agents they can interact with, and what actions agents can perform on behalf of users.
## Users and Roles Management
The Users and Roles Management interface provides a centralized location for managing all security configurations. Access this through the Genesis UI sidebar under **Config → Users & Roles**.
### Key Features
View and manage user roles and permissions across your organization
Create and customize roles with granular permission controls
Control which agents users can interact with based on their roles
Manage which tools are available to different roles
## Role Configuration
### Editing Roles
When editing a role, you'll have access to five main configuration sections:
**Name**: The role identifier (e.g., "admin", "user", "data\_analyst")
**Description**: A clear explanation of the role's purpose and intended users
Controls what users with this role can access within the Genesis UI, including:
* `access_config_panel`: Access to configuration panel
* `access_pulse_panel`: Access to pulse/monitoring panel
* `manage_genesis_enhancements`: Open the Genesis Enhancements page to view and submit enhancement requests
* `manage_users`: Manage users and roles
* `manage_agents`: Create, update, delete agents. At least one **active**
agent must always hold this permission so agent administration from chat
remains possible; Genesis refuses lifecycle or RBAC changes that would
leave none.
* `manage_document_indexes`: Create and manage document indexes, add documents, and poll background upload status through the document-index API.
* `manage_repos`: Manage unified Git-backed sources for skills, flows, apps, blueprints, and document indexes (Knowledge Base feeds) (`/api/managed-sources`; **Config → Managed Sources** and **Document Indexes → Sync from Git**)
* `manage_skills`: Register and sync managed Skill Git sources; edit/push skill workspaces
* `manage_flows`: Register and sync managed Flow Git sources; edit/push flow workspaces; manage flow bindings
* `manage_apps`: Register and sync managed App Git sources; edit/push app workspaces
* `manage_git`: Bind managed-artifact dependencies and administer shared Git repository settings used by Blueprints and artifact libraries
* `manage_all_connections`: Manage all database connections
* `manage_secrets`: Manage secrets and credentials
* `access_pat_connections_databases`: Allow PAT-class saved connection modes
for database connectors
* `access_pat_connections_git`: Allow PAT-class saved connection modes for
Git & Code connectors
* `access_pat_connections_cloud`: Allow PAT-class saved connection modes for
Cloud & Storage connectors
* `access_pat_connections_pipelines`: Allow PAT-class saved connection modes
for Data Pipelines connectors
* `access_pat_connections_tools`: Allow PAT-class saved connection modes for
Dev Tools connectors
* `view_apps`: View the apps library and app deployments
* `view_context_graph`: View the Context Graph / Digital Twin
* `view_deployments`: View the deployments panel
* `view_flows`: View flows
* `view_connections`: View database connections in Config and Data Explorer, browse or run governed transition-contract verification under **Data → Migration verification**, and browse or run the Estate source-contract characterization API (`/api/estate/...`)
* `ratify_transition_contract`: Approve (sign) qualified correspondence rules for a migration transition; required for the in-app rule approval modal and `POST /api/transition_contract/rules/{rule_hash}/ratify`. Agents and chat can propose and qualify rules but cannot ratify. Included in the built-in `admin` role; requires authentication enabled and a configured ratifier signing key
* `ratify_source_contract`: Adjudicate mined source-contract rule candidates, seal draft source contracts, and change ruling-library authority (settle, ratify provisional directions, unsettle, or answer build-time ruling questions); required for `POST /api/estate/candidates/{candidate_id}/adjudicate`, `POST /api/estate/contracts/{contract_id}/seal`, and the ruling-library write routes under `/api/estate/rulings/...` and `/api/estate/ruling-questions/{question_id}/answer`. Browse the library with `view_connections` (`GET /api/estate/rulings`, `GET /api/estate/ruling-questions`). Agents can propose and trigger characterization workflows but cannot adjudicate, seal, or settle rulings. Included in the built-in `admin` role; requires authentication enabled and a genuinely authenticated human caller
* `approve_agent_action`: Sign off on an action an agent has staged but cannot authorize for itself, such as an irreversible CRM record merge; required for CRM merge preview, approval, and execute routes (`/api/salesforce/merge/...`, `/api/crm/.../merge/...`, `/api/crm/merge/approvals`). Included in the built-in `admin` role; grant explicitly to custom roles when reviewers should not also hold `manage_all_connections`. Requires authentication enabled and a genuinely authenticated human caller for approve and execute; list and approve operations are scoped to connections the caller can access
* `manage_upgrades`: Use the **Upgrades** page on a managed deployment to configure upgrade policy and maintenance windows, pause upgrades, record customer scan results, and approve releases. Included in the built-in `admin` role. Every page operation requires this permission; changes additionally require a genuinely authenticated human, so an agent cannot make them even when its role holds the permission. With authentication disabled, the page is read-only. For the deployment flag that exposes this page, see [Advanced Settings — Launchpad feature flags](/docs/Setup/Advanced-Settings#launchpad-feature-flags).
* `approve_agent_action` also authorizes an authenticated human to waive a server-owned Blueprint `required_check` through `POST /api/runs/{run_id}/required-checks/{check_name}/waive`. Internal service tokens cannot record this waiver.
* `view_scheduler`: View scheduler jobs and history
* `view_sandboxes`: View sandboxes and deployment runtimes
* `view_shared_role_resources`: See missions and apps created by other members of a role you share
* `view_all_threads`: View all chat threads
* `view_all_secrets`: View all secrets
* `view_model_config`: See active chat and embedding model configuration
* `view_all_blueprints`: View and run every blueprint (`view` + `execute`) without per-blueprint grants
* `manage_all_blueprints`: Full control of every blueprint (`view`, `edit`, `manage`, `execute`), including sharing and access management
* `wiki_author`: Legacy non-default permission for operator-authored wiki
learnings. Dashboard commentary uses `view_git` instead; grant `wiki_author`
only when a custom integration still expects the retired learnings API.
`view_shared_role_resources` is intended for team-style roles. When two users share a role that includes this permission, Genesis can show them each other's missions and apps without manual invitations. It widens only view-style access and is not assigned to built-in roles by default.
Team Wiki page commentary in the dashboard (`GET`/`POST`/`DELETE`
`/api/wiki/v1/pages/{qualified_name}/commentary`) requires `view_git`. Callers
can delete only their own live comments. Agent- and Librarian-driven learnings
still depend on `wiki.write_enabled` in AppConfig when writes are enabled.
These PAT permissions are separate from `manage_all_connections`. Each one
controls whether a role can create, update, or test PAT-class saved
connections for one connector category. When a category permission is
absent, Genesis hides PAT-based auth modes for that category in the
Connections UI and blocks PAT-based connection saves and tests there.
Connection discovery applies the same boundary: the finder considers only
connections visible to the requesting user, usable by that user, and
accessible to the active agent. It does not expose a hidden or inaccessible
connection merely because a pasted URL matches its host. A recommendation
selection is validated again against the original user, agent, and thread
before the connection is used.
Genesis uses the top-level `view_*` permissions to decide whether major
workspaces appear in the primary sidebar when authentication is enabled.
`manage_genesis_enhancements` opens the Genesis Enhancements page so holders
can view and submit enhancement requests without `access_config_panel` or
the built-in `admin` role. It grants no other configuration access. The
Genesis Enhancements API routes accept either `access_config_panel` or
`manage_genesis_enhancements`; dormant-review scheduler start and stop still
require `manage_scheduler`.
Specify which data agent that users with this role can interact with. \
\
You can:
* Grant access to specific agents by selecting them individually
* Restrict access by leaving agents unselected
* Update agent access as your organization's needs evolve
Control which secrets stored in the Genesis Secret Vault are accessible to this role. This ensures sensitive credentials are only available to authorized users.
Define which tools agents can use when acting on behalf of users with this role.
By default, all tools are allowed for backward compatibility. Administrators should review and restrict tool access based on security requirements.
**Configuration Options**:
* Select specific tools to allow
* Use "Select All" and then remove specific tools to create an allowlist
* Remove tool access entirely to create the most restrictive permissions
## Three-Layer Tool Control System
Genesis implements a sophisticated three-layer approach to tool access control, providing defense-in-depth security:
### Layer 1: Tool Configuration (Agent Toolbox)
An agent must have a tool in its toolbox to use it. This is the foundational layer of tool access.
**How it works**:
* Each agent has a configured set of tools available in its toolbox
* By default, agents can add tools to themselves dynamically as needed
* Administrators can disable the "Allow Agents to Add Tools to Itself" setting to prevent self-service tool addition
**Use Case**: Limit agent capabilities at the agent definition level, ensuring agents only have tools relevant to their purpose.
### Layer 2: RBAC Tool Usage Control (Primary Access Control)
This is specific to User + Agent interactions. Agent-only access is different
and does not consider user roles.
Genesis has two authorization modes at this layer, and the default is the
permissive one:
* **`union` (default)**: the tool runs if **either** the user's role **or**
the agent's role allows it.
* **`intersection`**: the tool runs only if **both** the user's role **and**
the agent's role allow it.
In `union` mode a user whose role does not grant a tool can still reach that
tool through an agent whose role does. Deployments that must not permit this
have to select `intersection` — see [Strict
settings](#strict-settings-for-regulated-deployments) below.
**How it works**:
* Each role has a list of allowed tools defined by the administrator
* Administrators can include or exclude any tool for any role
* The configured authorization mode decides how the two role checks combine
**Example Scenario**:
```
Agent "DataAnalyst" has the `_query_database` tool in its toolbox (Layer 1 ✓)
User "John" has role "Viewer" (Layer 2 check)
Agent "DataAnalyst" has role "Analyst" (Layer 2 check)
"Viewer" does NOT allow `_query_database`, "Analyst" does:
→ union mode: tool execution is ALLOWED (the agent's role grants it)
→ intersection mode: tool execution is BLOCKED (the user's role does not)
Neither "Viewer" nor "Analyst" allows `_query_database`:
→ Tool execution is BLOCKED in both modes
```
**Agent-only runs**: a scheduled job, a webhook, or any other run with no user
context is authorized against the agent's role alone, in both modes. Genesis
records that no user context was present in the authorization log line for the
call.
**Fail-closed on check errors**: When authentication is enabled, tool access is
**fail-closed**. If Genesis cannot complete the authorization check, the tool is
denied rather than executed. This applies when RBAC is unavailable or not
initialized, when the per-tool check raises an error, or when neither a user nor
an agent principal is present on the request. Users see an access-denied message
in chat; when the block is caused by a failed check (not a role or global
policy), the message notes that access was denied as a safety measure and that
retrying shortly may help—contact an administrator if it persists. When
authentication is disabled (typical local development), the same conditions
**allow** the tool so local tooling is not blocked.
**Configuration**: Navigate to **Users & Roles → Edit Role → Tool Access** to configure tool permissions for each role.
### Strict settings for regulated deployments
Two settings control how strict Layer 2 and connection credential access are.
Both live in the `security` section of Genesis configuration:
| Setting | Default | Effect |
| - | - | - |
| `security.tool_auth_mode` | `union` | `union` allows a tool when either principal's role grants it; `intersection` requires both. Applies to tools only. |
| `security.force_double_key_on_connections` | `false` | When `true`, makes every saved connection behave as if `require_double_key` were on, regardless of each connection's stored value. Applies to connections only. |
**The two settings are independent, and neither overrides the other.** They
govern different resources — one the tool check, one every connection — so all
four combinations are available and each means exactly what it says. Turning on
`security.force_double_key_on_connections` does not narrow tool authorization,
and selecting `intersection` does not change how connections are treated. A
regulated deployment that wants both sets both.
Set either as an environment variable
(`SECURITY_TOOL_AUTH_MODE=intersection`,
`SECURITY_FORCE_DOUBLE_KEY_ON_CONNECTIONS=true`), through a Helm value that sets
those variables, or in **Config → Advanced Settings**.
Note the scope of `require_double_key`: it decides whether both the user and the
agent must pass secret-level access checks **at a connection**, which covers both
resolving that connection's credentials and whether the connection is visible at
all. It does not affect tool authorization, which is what
`security.tool_auth_mode` covers.
#### What double key means when only one principal is present
Double key asks two principals to pass. A request that carries only one — a
scheduled job or a webhook, which arrives with an agent and no user — cannot
answer that question, and Genesis does not answer it the same way everywhere.
This is the behaviour of `require_double_key` itself, and turning on
`security.force_double_key_on_connections` extends it to every connection rather
than changing it:
| Boundary | A request with an agent and no user |
| - | - |
| Listing a connection, or checking whether it is visible | **Denied** — with no user there is no second principal, so the connection does not appear. |
| Resolving a connection's credentials | **Allowed**, against the agent's own secret access. |
| The permission check on a database connection | **Allowed**, against the agent's own access. |
The practical effect is that a strict deployment hides a connection from an
agent-only listing while still letting that same agent use its credentials, so
scheduled work keeps running. Deployments that need agent-only credential use
blocked outright should use the agent's toolbox (Layer 1) or the connection's
allowed-agent list, both of which apply regardless of how many principals a
request carries.
Two provider features read the connection's own stored `require_double_key` and
are **not** raised by `security.force_double_key_on_connections`: Databricks headless M2M
embeddings, and the Google Chat shared service-account event route. Both are
capability checks rather than access checks — they ask whether a connection can
serve a call that has no user at all, and both already refuse a connection whose
stored flag is on. Extending the switch to them would not add a check, because
there is no second principal to ask for; it would withdraw the capability from
every strict deployment. To block either one, turn on `require_double_key` on the
connection it uses, which is the setting those checks read.
If `security.tool_auth_mode` holds a value that is neither `union` nor
`intersection`, Genesis logs the misconfiguration and uses `intersection` — an
unreadable security setting must not resolve to the permissive one.
Every tool authorization decision is written to the log with the mode in force,
which principal or principals satisfied the check, and what decided the outcome,
so an auditor can tell a union-mode grant from an intersection-mode grant after
the fact. Grants and denials alike are kept **whatever `LOG_LEVEL` the deployment
runs at**: these records go to a dedicated audit logger that the level filter does
not apply to, so raising the level to quieten a busy server does not thin the
audit trail. A denial is emitted at WARNING and a grant at INFO, so the two are
still distinguishable in the stream.
### Layer 3: Global Tool Toggles (System-Level Override)
These system-wide toggles provide an additional safety layer by blocking specific tool families regardless of other configurations.
**How it works**:
* Independent control that overrides Layer 1 and Layer 2
* Blocks specific high-risk and coding-agent tools identified by Genesis
* When a tool family is blocked, those tools are unavailable system-wide
**Current High-Risk Tools**:
* `dbt_action` — **dbt Actions**
* `execute_python_code` — **Local Python Execution**
* `run_repo_script` — **Repository Required Checks**
* `_run_sqlite_cli_commands` — **SQLite CLI Commands**
**Current Coding Agent Tools**:
* `_claude_code` — **Claude Code**
* `_codex_code` — **Codex**
* `_cortex_code` — **Cortex Code**
**Override Behavior**: Even if:
* ✓ An agent has the tool configured (Layer 1)
* ✓ Layer 2 authorizes the call under the configured mode
If the relevant global tool toggle blocks that tool family, the tool will still be **blocked**.
**Configuration**: Navigate to **Config → Workspace Policies** and use
**Tool Permissions → High-Risk Tool Controls** or
**Tool Permissions → Coding Agent Controls**.
Genesis persists the last saved **High-Risk Tool Controls** state across
restarts, so the selected blocked or allowed state remains in effect until an
admin changes it. Some deployments hold these switches fixed; see
[Workspace Policies](/docs/Setup/Workspace-Policies) for the conditions and
how forced policy interacts with role permissions.
Where a deployment does not hold a policy fixed, Layer 3 provides a convenient single-switch control for disabling a sensitive tool family. See [Workspace Policies](/docs/Setup/Workspace-Policies) for deployment-specific behavior.
## Sandbox Thread Token Controls
When a chat thread runs Claude Code in a sandbox container or Kubernetes Pod, Genesis
mints a thread-scoped token for the agent's calls back to MCP and the internal LLM proxy.
The token is resolved to the user who owns that thread, never to the system user, so the
usual RBAC, tenancy, connection, and tool checks continue to apply.
The token is valid only for its own `(bot, thread)` identity. If the caller supplies the
optional `x-genesis-thread-id` header, it must match the token's thread. Genesis fails
closed when the token is invalid, expired, presented for another thread, or the thread
has no resolvable owner. A separate route-and-method capability contract limits the REST
calls the MCP server can make on the agent's behalf to conversation and governed-data
operations; configuration, user/RBAC, connection, credential, and secret management
remain outside the contract. Requests outside it return `403`.
Unowned coding and sandbox runs receive an additional execution contract on the
permitted tool-call route; see [Tool-call execution contract](/docs/Genesis-API/Tool-Call-Endpoint#post-apitool_call)
for the prohibited operations, refusal response, and permitted read exceptions.
A sandbox token cannot `POST` a message to the thread it was minted for, including
the `/messages`, `/messages/sync`, and `/messages/websocket` endpoints. Genesis
returns `403` because the token acts as that thread's owner, so accepting the
request would record the agent as the owner speaking; the agent's words reach its
own thread through its output. Messages to other threads remain allowed.
When a sandbox request is rejected at the HTTP authentication boundary, the client
sees the credential-specific cause: `Authorization: Bearer gsk_...` is a
per-sandbox-run token and expires with that run. A personal access token
(`gp_...`) is not a substitute for the sandbox token, and vice versa.
Genesis persists the token record in the metadata store, so a backend restart does not
extend its lifetime or invalidate it early; the token's stored expiry and revocation
state remain authoritative. If the token store cannot be used, Genesis rejects the
request rather than bypassing token validation.
This control is an endpoint ceiling, not a replacement for user authorization: the
sandbox agent still acts with the owning user's effective permissions. For request
headers and response codes, see [Hosted MCP gateway endpoints](/docs/Genesis-API/API-Reference#hosted-mcp-gateway-endpoints).
The sandbox connectivity probe at `/api/internal/sandbox-llm/api/hello` is a separate
`GET`/`HEAD` reachability check: it returns `200` without a thread token and does not
invoke the LLM proxy. See [Internal sandbox LLM proxy endpoints](/docs/Genesis-API/API-Reference#internal-sandbox-llm-proxy-endpoints).
## GenesisApp Server Token Controls
GenesisApps use `X-Genesis-App-Token` for server-originated calls, but the token
is limited to the platform routes in the app server token capability manifest.
Calls outside that contract return `403`; app code should fetch
`GET /api/apps/{app_id}/capabilities` rather than assume that a route is
available. The full route list and response contract are documented in the
[Genesis App server token capability manifest](/docs/Genesis-API/API-Reference#genesis-app-server-token-capability-manifest).
## Genesis Desktop lock and origin controls
In Genesis Desktop laptop mode, the backend refuses API requests while the app
is locked. Only the lock-screen status, sign-in start, sign-in status and
cancellation (`/api/desktop/auth/attempt` and `/api/desktop/auth/cancel`),
callback, activation, check-in, and sign-out routes remain available; `GET` and
`HEAD` reads of
`/api/desktop/activity` and `/api/desktop/update/` are also allowed. The update
read lets **Update now** on the **Update required** lock screen check the
install's release channel; see [Genesis Desktop release-channel updates](/docs/Genesis-API/API-Reference#genesis-desktop-release-channel-updates).
Other desktop API routes and the MCP, Git, SCIM, and Outpost tunnel API surfaces
stay locked. Requests from a website other than the app are rejected by the
desktop origin guard, which also limits sign-in initiation to the desktop
client. These desktop-only controls do not change behavior on hosted deployments.
Desktop activity tracking counts a person's interactions, not the process's
background work. API writes count only when they do not carry this process's
valid internal service token; chat prompts identified as internal service calls,
such as scheduled-flow prompts, are also excluded. This keeps background lineage,
twin-client, and scheduler work from being attributed to someone using Desktop.
Without authentication, an API write with a missing or invalid internal service
token is still treated as a person's interaction.
For Genesis Desktop's per-install master-key handling and saved-credential
recovery, see [Master encryption key](/docs/Setup/External-Secrets#master-encryption-key).
Signing in and activating are required to use Genesis Desktop. Each process
start must also receive a successful live answer (an activation or check-in)
from the provisioner before the app can be used; while it is running, it must
receive another successful answer at least once per hour. If no live answer has
been received since start, or the last successful answer is more than an hour
old, the API is locked against new work. A turn already in progress can finish
and continue streaming; the lock screen appears after it finishes. Once the
offline grace expires, the lock screen says:
`Genesis can't reach the Genesis servers. Check your internet connection and try again.`
The provisioner can also require an app update. When the running version is
below its required minimum, or the provisioner refuses it outright, Desktop
locks with `lock_reason: "update_required"` and refuses new API work with HTTP
`423`; an active agent turn can finish before the lock screen appears. Desktop
continues checking in at its normal cadence, so a policy change that lowers the
minimum can unlock the app at the next check-in. The status fields and
provisioner policy contract are documented in
[Genesis Desktop version policy](/docs/Genesis-API/API-Reference#genesis-desktop-version-policy).
The 30-day desktop trial is informational: days remaining appear below the
user's initials, and an in-app banner appears after it ends, but trial status
never locks the app. When an install is revoked, the lock screen's **Contact
Genesis** action points to `info@genesiscomputing.ai` by default. For automatic
diagnostic log uploads at startup and daily, see [Genesis Desktop diagnostics](/docs/Genesis-API/API-Reference#genesis-desktop-diagnostics).
Sharing a full-screen app URL does not share the opener's session or app grants.
For top-level app proxy links, Auth0 and OIDC deployments can send an anonymous
viewer through sign-in and return them with a short-lived token that is moved
into an app-scoped HTTP-only cookie; the viewer must still pass the app's normal
`view` authorization check. See [Genesis App proxy behavior](/docs/Genesis-API/API-Reference#genesis-app-proxy-behavior)
for the redirect conditions and token handling.
For anonymous top-level `/git/...` page opens, the Git Browser shell does not
grant repository access; see [Git repository and file endpoints](/docs/Genesis-API/API-Reference#git-repository-and-file-endpoints).
## Headless Hosted MCP Authentication
Headless MCP clients can authenticate to the hosted `/mcp/` transport with a
Genesis personal access token instead of browser OAuth. Send the token as
`Authorization: Bearer gp_...`; Genesis hydrates the persisted PAT owner and
enforces that user's roles, agent access, permissions, and deployment access.
Invalid or unverifiable owner identity returns `401`, while a valid PAT whose
owner is not allowed to access the deployment returns `403`.
HTTP authentication and authorization refusals use the standard JSON error
envelope and include a correlation ID in both `request_id` and `X-Request-Id`.
This applies to PAT, GenesisApp, sandbox-thread, and other API credentials;
see [HTTP authentication refusal responses](/docs/Genesis-API/API-Reference#http-authentication-refusal-responses)
for the shared fields and `error_type` values.
PATs are bearer credentials: create an expiring token from **API Keys**, store it
as a secret, and revoke it there when it is no longer needed. For the creation,
rotation, and REST schemas, see [Personal access tokens](/docs/User-Guide/Personal-Access-Tokens).
The hosted MCP request and response contract is documented in [Hosted MCP gateway
endpoints](/docs/Genesis-API/API-Reference#hosted-mcp-gateway-endpoints).
Signed artifact download links are the exception to the hosted transport's normal
browser-session or bearer requirement: the HMAC-signed, single-use, expiring token
in `artifacts[].download_url` authenticates `GET /api/mcp/artifacts/{artifact_id}`.
## Hosted Try Me Instance Isolation
Try Me's provisioner credential is not a user credential; see the
[internal demo API routes](/docs/Genesis-API/API-Reference) for its scope and
[demo access gate settings](/docs/Setup/Advanced-Settings#demo-access-gate).
An identity denied by the gate is rejected before Genesis provisions a user
record. In a browser, the denial leads to the refusal page instead of restarting
sign-in; see [HTTP authentication refusal responses](/docs/Genesis-API/API-Reference#http-authentication-refusal-responses).
## Built-in Roles
Genesis provides default roles for common use cases:
**Default Role for Eve Agent**
Full access to all features, agents, tools, and administrative functions. Use sparingly and only for trusted administrators.
**Default Role for New Agents**
Standard user access with configurable agent and tool permissions. The
built-in `user` role includes all five category-scoped PAT connection
permissions, so dashboard users can post Team Wiki commentary (via
`view_git`) and use PAT-class saved connection modes across
Databases, Git & Code, Cloud & Storage, Data Pipelines, and Dev Tools
unless an admin removes those permissions.
## Current User Information
View your own role assignments and permissions by navigating to
**Users & Roles → Current User Info**. This section shows:
* Your assigned roles (or the active **Access Preview** role set when preview is on)
* Permissions granted to you (preview-aware, matching the same source as `GET /api/rbac/me/permissions`)
* Agents you have access to
* Tools you're authorized to use
## Security Best Practices
Grant users and agents only the minimum permissions required for their functions. Start with restrictive permissions and add access as needed.
Periodically audit which tools are enabled for each role. Remove access to tools that are no longer needed.
For production environments, review both High-Risk Tool Controls and Coding Agent Controls. Disable either family unless your users and agents explicitly need those capabilities.
Assign agents to roles based on their intended purpose. Specialized agents should have restricted tool access aligned with their function.
Regularly review which tools agents are attempting to use. Unusual tool access patterns may indicate misconfigurations or security concerns.
Leverage the Secret Access configuration to ensure sensitive credentials are only available to roles that absolutely require them.
## Creating Custom Roles
To create a new role tailored to your organization's needs:
1. Navigate to **Users & Roles** in the Genesis UI
2. Click **Create New Role**
3. Configure the four main sections:
* **Basic Information**: Name and description
* **Permissions**: UI and system access
* **Agent Access**: Which agents this role can use
* **Tool Access**: Which tools are permitted
4. Click **Save** to activate the role
Custom roles can then be assigned to users and agents as needed.
## Agent Role Assignment
All agents are assigned roles just like users:
* **Eve** (the primary Genesis agent) has the **admin** role by default
* **New agents** are automatically assigned the **user** role
* Administrators can assign additional roles to agents as needed
* Agent role permissions are combined with user role permissions at Layer 2, according to `security.tool_auth_mode`
Remember: An agent having a tool and being allowed to use it are two different
things. In the default `union` mode either principal's role can authorize the
call; set `security.tool_auth_mode` to `intersection` when both must.
## FAQ
The agent will immediately lose access to that tool. Any in-progress operations using that tool will fail, and future attempts to use it will be blocked.
Yes! Use the Agent Access section when editing a role to specify exactly which agents users with that role can interact with.
Layer 2 (RBAC) provides granular, role-based control over individual tools. Layer 3 adds system-wide global toggles for high-risk tools and coding-agent tools. Layer 3 is simpler but less flexible because it blocks an entire tool family regardless of role permissions.
By default, yes—agents can add tools to their toolbox. However, even if they add a tool (Layer 1), they still need role permission to use it (Layer 2). Admins can also disable self-service tool addition entirely.
Navigate to **Config → Workspace Policies**. The **Tool Permissions**
section lists the current high-risk tools and coding-agent tools, along
with whether each family is globally allowed or blocked.