Skip to main content

​
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

User Management

View and manage user roles and permissions across your organization

Role Definitions

Create and customize roles with granular permission controls

Agent Access

Control which agents users can interact with based on their roles

Tool Access

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

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

​
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. 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. 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. 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 [email protected] by default. For automatic diagnostic log uploads at startup and daily, see 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 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.

​
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 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. The hosted MCP request and response contract is documented in 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 for its scope and demo access gate settings. 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.

​
Built-in Roles

Genesis provides default roles for common use cases:

Admin

Default Role for Eve AgentFull access to all features, agents, tools, and administrative functions. Use sparingly and only for trusted administrators.

User

Default Role for New AgentsStandard 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

1

Apply Least Privilege

Grant users and agents only the minimum permissions required for their functions. Start with restrictive permissions and add access as needed.
2

Review Tool Access Regularly

Periodically audit which tools are enabled for each role. Remove access to tools that are no longer needed.
3

Review Global Tool Toggles

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

Use Role-Based Agent Assignment

Assign agents to roles based on their intended purpose. Specialized agents should have restricted tool access aligned with their function.
5

Monitor Agent Tool Usage

Regularly review which tools agents are attempting to use. Unusual tool access patterns may indicate misconfigurations or security concerns.
6

Secure Secrets Properly

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.