RBAC in Genesis: A Practical Guide

​

Foundational Mental Model: Agents as Engineers

• Agents (Eve, Adam, etc.) are first-class in RBAC. Each agent has an identity (agent ID) and can be assigned roles, just like human users.
• Users are people who log in (e.g. via Azure AD, OAuth). They also have roles.
• Tools are the capabilities agents use when you chat with them (e.g. querying a database, running Git operations, managing access). Which tools an agent can use can be restricted by role.
• Secrets store sensitive values (passwords, API keys). Access is determined by ownership, admin status, or role-based policies. You manage them in Config → Secrets (if you have access).
• Connections are named configurations for external systems (GitHub, Snowflake, Postgres, etc.). You create and edit them in Config → Connections. Credentials in connections are stored as secrets; who can use a connection depends on who has access to those secrets (and, for database connections added in chat, on an explicit allowed-agent list).

​

Hosted identity links

• POST /api/hosted-identities/initial-admin creates the sole initial admin and requires the hosted.identity.bootstrap management capability.
• POST /api/hosted-identities/invitations creates an ordinary hosted user and requires the caller’s manage_users permission.
• POST /api/hosted-identities/{binding_id}/revoke revokes one exact link; ordinary callers need manage_users, while emergency management callers need hosted.identity.emergency_revoke.

​

Establishing or recovering an administrator

• Default roles for new users. A brand-new user receives the roles in rbac.default_roles, or the list saved under Default Roles for New Users. The shipped default is admin and user, so on an unconfigured install the first person to sign in is an administrator. If the saved list cannot be read when a user is created, that user receives no roles rather than the shipped default.
• An existing administrator grants the admin role in Config → Users.
• Hosted installs create their first administrator with POST /api/hosted-identities/initial-admin, described above.
• Operator recovery, when no administrator can sign in. This needs access to the deployment’s infrastructure, not to Genesis:
  • Self-hosted (Kubernetes, Docker, Railway): the person signs in once, then an operator runs python -m genesis_bots.apps.cli grant-admin --email <person> --actor-email <operator> inside the Genesis container, from the app directory (/app in the standard image), and restarts the service. The grant is recorded in the admin audit log with source cli. If several users share the email, the command lists them; rerun it with --user-id. It refuses a user whose roles SCIM manages: grant admin through the identity provider’s group mapping instead, because the next SCIM sync resets that user’s roles to what the provider grants.
  • Snowflake (SPCS): insert the user’s admin row into the deployment’s CASBIN_RULE table, then suspend and resume the service. The restart briefly interrupts every user, and a direct table write records no Genesis audit event.
  • Databricks Apps: there is no shell into the App. With verified sign-in (PROXY_AUTH_DATABRICKS_VERIFY_TOKEN=true), its first administrator is seated at sign-in; see first administrator for Databricks Apps. You can also map a workspace group to admin in GENESIS_GROUP_ROLE_MAPPING; members receive the role when they sign in. Service principals are admitted as users only through the administrator-configured test-identity exception; see Databricks App test identities.
  Running servers hold role assignments in memory, so only the restart guarantees that the self-hosted or Snowflake grant takes effect.

​

Admin vs User: What Each Can Do

​

Admin

• Access every agent (including Eve). No per-agent configuration is required.
• Manage users and roles in Config → Users: assign and revoke roles, create custom roles, set default roles for new users, and configure which roles can access which agents and which capabilities (tools).
• Manage agents in Config → Agents: create, update, and delete agents.
• Create agents without global edit access with create_agents. The creator can then maintain the agents they create or import, but cannot edit unrelated agents unless a role grants management for those specific agent IDs.
• Review agent learning candidates in Pulse when granted manage_agent_learning: accept or dismiss lessons proposed for agents. Reading the learning queue, adoption history, and improvement report only requires access_pulse_panel.
• Manage managed artifacts when granted manage_skills, manage_flows, or manage_apps: register Git sources, sync Skills/Flows/Apps, and open workspace MR/PR flows from each library page. Binding logical dependencies after sync uses manage_git.
• Manage unified Git sources when granted manage_repos: register one repository with multiple scan_types_enabled values (including documents for Knowledge Base feeds), sync, and delete multi-type sources from Config → Managed Sources, Document Indexes → Sync from Git, or GET/POST/PATCH/DELETE /api/managed-sources. Holders of manage_repos can also use the legacy per-type repository routes; multi-type deletes must go through the unified API. On upgrade, Genesis backfills manage_repos once for the built-in admin role and for custom roles that already have all of manage_skills, manage_flows, manage_apps, and manage_git.
• Manage connections in Config → Connections: create, update, and delete connections and their credentials.
• Manage secrets in Config → Secrets: create, update, delete, and view all secrets. Only admins can update system-owned secrets.
• Edit the global Context Graph token cap in Digital Twin → Spend or through the SET_USAGE_BUDGET lineage action. This requires access_config_panel; the built-in admin role has it, and a custom role must be granted it explicitly.
• Use the scheduler and the Pulse (monitoring) panel.
• View all chat threads and view all secrets for auditing.

​

Environment snapshot export

​

Access Preview

​

User (regular user)

• Built-in user role defaults: view_apps, view_context_graph, view_deployments, view_flows, create_app, import_app, view_git, view_agents, view_skills, view_connections, view_scheduler, view_all_missions, view_sandboxes, use_cli_terminal, and ratify_source_contract
• ratify_source_contract lets user-role operators seal source contracts and grade Prover comparisons against them; this is not an admin-only task.
• Built-in user PAT permissions: access_pat_connections_databases, access_pat_connections_git, access_pat_connections_cloud, access_pat_connections_pipelines, and access_pat_connections_tools
• use_cli_terminal: Allows the user to attach a real terminal to their own private Claude Code workspace from the GUI or a laptop client. It is separate from view_sandboxes and manage_sandboxes; neither sandbox permission implies it. The feature also requires the cli_terminal.enabled deployment setting. Because the workspace is a genuine shell and Claude Code runs without permission prompts, grant this permission deliberately.
• Team Wiki commentary: Users with view_git can list, post, and soft-delete their own Markdown comments on any Team Wiki page through the dashboard commentary API (GET/POST/DELETE /api/wiki/v1/pages/{qualified_name}/commentary). Agent-, Flow-, and Librarian-driven learnings still follow wiki.write_enabled in AppConfig; background Librarian extraction also requires wiki.librarian_enabled (see Advanced Settings → Team Wiki / Librarian settings).
• wiki_author (non-default): Optional permission retained for legacy role grants. It is not included in built-in role defaults and is no longer required for dashboard wiki commentary.
• Agent access is not automatic. An admin (in Config → Users) assigns the user to a role and configures that role to have access to specific agents (e.g. the Data Agent and Report Agent). If nothing is configured, non-Eve agents may still be accessible by default in some setups; Eve is admin-only by design.
• If an existing built-in user role already has agent grants from before Adam was seeded, startup adds access to Adam once. An administrator can revoke that grant afterward; later startups do not restore it.
• Tool access: by default, a role can use all capabilities except those an admin has globally disabled (for example, the high-risk or coding-agent tool families). An admin can restrict a role so it can use only the capabilities explicitly granted to that role.
• Secrets: a user can create secrets they own (e.g. in Config → Secrets, if they have access). They can use a secret if they own it, or if it’s system/shared, or if they’re admin, or if their role has been granted access to that secret. They cannot update or delete system-owned secrets; only admins can.
• Connections: creating or editing shared connections in the UI requires the manage_all_connections permission (admins or a custom role with that permission). PAT-class saved connection modes (pat, api_token, api_key) also require the matching access_pat_connections_<category> permission for the connector category (databases, git, cloud, pipelines, tools) when you create, update, or test them. Roles without a category’s PAT permission can still use OAuth-based connection modes where available; token-only connectors in that category stay unavailable until an admin enables the capability. Using a connection is governed by secret access and, for database connections created in chat, by the allowed-agent list.

​

SCIM-provisioned users

​

OIDC group-to-role mapping (Helm-driven)

1. Helm groupRoleMapping.content — mounted at /app/.genesis/config/group-role-mapping.yaml with GENESIS_GROUP_ROLE_MAPPING_FILE
2. GENESIS_GROUP_ROLE_MAPPING — JSON object with the same group-id → role name shape (non-Helm fallback)

• On each login, Genesis reads group claims from the authenticated user (JWT groups for OIDC) and assigns mapped roles.
• Roles are removed when group membership is lost — but only for roles that appear as values in the mapping. Manually assigned roles outside the mapping are never removed.

​

QA Fleet service identity (automated testing)

​

Top-level workspace visibility

​

Agents, Tools, Secrets, and Connections

​

Agents

• Agents are set up in Config → Agents. manage_agents allows creating, updating, and deleting every agent. create_agents allows creating or importing new agents without editing existing ones; the creator receives a manage grant on each agent they create or import.
• A role can receive per-agent management grants without global manage_agents. Configure the complete list through the role’s agent-manage grants; those grants control editing, deletion, instruction reset, settings, skills, and knowledge-base assignments for the listed agents.
• If a creator grant is missing after creation or import, an administrator with manage_users can restore it from the agent’s creator grants in the RBAC administration surface. Creator grants are separate from chat-access grants.
• Each agent has an agent ID. Agents are assigned roles (e.g. Eve often has the admin role so she can manage users and access).
• When an agent does something in a chat, it acts under its own identity. Access to secrets and connections is checked for that agent (and, when you’re in the chat, for you). Capability (tool) access is checked for both you and the agent, and the two results are combined according to security.tool_auth_mode — see Capability authorization modes.
• At least one active agent must always hold manage_agents, otherwise no agent could administer agents from chat anymore. Genesis refuses the change that would leave none — deactivating or deleting that agent, revoking the role carrying the permission, removing the permission from that role, or deleting the role. Grant manage_agents to another active agent first, then repeat the change.

​

Tools (agent capabilities)

• Agents only use capabilities they’re allowed to use. Access is checked when a capability is used:
  • High-risk capabilities can be globally disabled by an admin; the current list includes dbt_action, execute_python_code, and _run_sqlite_cli_commands.
  • Coding-agent capabilities can also be globally disabled by an admin; this blocks delegated work through Claude Code, Codex, and Cortex Code until an admin re-enables those tools.
  • Per-role tool access: by default, a role can use all capabilities (except globally disabled ones). An admin can make a role restricted so it can use only the capabilities explicitly granted to that role.
  • Fail-closed when auth is enabled: if the tool-access check cannot complete—RBAC is unavailable, the check raises an error, or there is no user or agent principal on the request—Genesis denies the tool rather than running it. Users see an access-denied message; transient check failures suggest retrying shortly. With authentication disabled (typical local dev), the same conditions fail open so tools keep working.
• Admins configure role–agent and role–tool mappings in Config → Users, or by asking Eve in chat to assign roles and grant access to agents or capabilities.

​

Capability authorization modes

• union (the default): the capability runs if either role allows it. A user whose role does not grant a capability can therefore still reach it through an agent whose role does.
• intersection: the capability runs only if both roles allow it.

​

Secrets

• Who can create: In Config → Secrets, any user or agent with access can create a secret; they become the owner unless it’s created as a system secret. System secrets are readable by those with access; only admins can update or delete them.
• Who can use: A user or agent can use a secret if: they are the owner; or it’s system or shared; or they have the admin role; or they have a permission that grants broad secret access; or their role has been granted access to that specific secret (configured in Config → Users).
• Who can update/delete: The owner can update or delete their own secrets. Admins can update or delete any secret (including system). Shared secrets can be updated by any authenticated user. Non-owners cannot update or delete someone else’s personal secrets unless they are admin.

​

Connections

• Saved connections (Config → Connections): Credentials are stored in Genesis Secrets. Who can use a connection is determined by secret access (ownership, admin, role grants on the connection’s secrets, and double-key rules when enabled). Shared connections can list Roles with Access so only members of those roles see and resolve the connection.
• Per-agent connection profiles: Admins assign connection profile roles to agents from Agents → [agent] → Data Access (requires manage_users). A profile is a reusable custom role whose Roles with Access bindings on saved connections define what that profile grants. An agent can hold multiple profiles; its reachable connections are the union. With no profile, the agent inherits each connection type’s default. Built-in roles such as user cannot be profile roles. Agents with broad secret permissions (admin or view-all-secrets) can still reach connections beyond any profile until those broad roles are removed.
• Database connections created in chat: When an agent (e.g. Eve) adds a database connection during a conversation, that agent becomes the owner and specifies which other agents can use it (allowed-agent list, or all agents). Only the owner and agents on that list can use that connection.
• Access intent (database connections): Saved database connections can carry access_intent (unspecified, read_only, or read_modify). This is an awareness label for agents and the Agent Center badge — it does not replace database-role or RBAC enforcement.
• What users see in browsing APIs: /api/config/db-connections and the Data Explorer connection lists only return database connections visible to the current user. Direct calls to /api/data/... for a connection the user cannot use return 403 Forbidden instead of exposing metadata.
• Pipeline source access: Launchpad pipeline inspection and pipeline evidence use the selected repository’s normal view_git permission and repository-level read access. Selecting a repository does not grant access to it; a user who cannot read the repository cannot inspect its files or open pinned pipeline evidence.

​

Transition-contract verification and approval

• view_connections — browse the Migration verification page under Data (/data/verify/), list correspondence rules and verification requests, compile objectives, execute contracts, and read run reports. Also browse and run the Estate source-contract characterization surface (/api/estate/...): characterize snapshots, mine candidates, compile and verify contracts, run jitter campaigns, and read ledgers and attestations. This is the same permission family as Data Explorer connection access. The built-in user role includes it.
• ratify_transition_contract — approve (ratify) a qualified correspondence rule: the server signs a binding as the authenticated human approver. Included in the built-in admin role only; grant it explicitly to custom roles when operators other than admins must sign. Chat and agent tools can propose and qualify rules but never ratify — the in-app approval modal and POST /api/transition_contract/rules/{rule_hash}/ratify are the only signing surfaces.

​

Source-contract characterization and approval

• view_connections — browse and run the Estate API surface: characterize estates and non-data planes, mine rule candidates, compile draft contracts, verify against fresh characterization, run jitter and clone-jitter campaigns, and read snapshots, ledgers, deviations, and attestations. The Estate nav is shown by default; it is hidden only when a deployment set features.show_estate to false (show_estate is then false on GET /api/config/frontend). The built-in user role includes view_connections.
• ratify_source_contract — adjudicate mined rule candidates (accept_fact, endorse_policy, or reject), seal draft source contracts, and change ruling-library authority (settle, ratify provisional directions, unsettle, or answer build-time ruling questions). Prover review approvals, including disposition packages, bundles, correspondence rules, consult rulings, and Action Review requests, require ordinary Prover access (view_connections) but not this permission: any signed-in person may approve, including their own proposals. The admin console labels this permission Approve source contracts and manage estates. Included in the built-in admin role only; grant it explicitly to custom roles when operators need the authority-changing operations above. Agents can propose and trigger characterization workflows but never adjudicate, seal, or settle rulings — 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 are the human authority-changing surfaces. Browse the library with view_connections (GET /api/estate/rulings, GET /api/estate/ruling-questions). For Prover approval identity and audit details, see Roles and Approvals.

​

Agent action approval (CRM merges and beyond)

• 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 all /api/salesforce/merge/..., /api/crm/.../merge/..., and cross-provider /api/crm/merge/approvals routes (preview, list, approve, and execute). Included in the built-in admin role only; grant it explicitly to custom roles when operators other than admins must review merges without also holding manage_all_connections. Grant this only to roles held by people — both approving and executing require a genuinely authenticated human, and this permission decides who that can be. List and approve operations are scoped to connections the caller can access; holding approve_agent_action does not grant visibility into every connection. Agents can preview and request approval through connector tools but cannot approve on behalf of a human.

​

Blueprints

• Who owns a blueprint: Genesis resolves blueprint ownership from blueprint_manifest.yaml. It checks the top-level created_by field first, then falls back to legacy blueprint.created_by.
• Who can use it by default: When authentication is enabled, the owner automatically passes Blueprint RBAC checks. Newly created and copied blueprints are owner-only by default until you grant additional access.
• How access is granted: Blueprint access is role-based and uses the Blueprint actions view, edit, manage, and execute. Grants apply only to configured RBAC roles—the built-in roles and any custom roles defined in Config → Users. Genesis rejects grant requests for unknown role names.
• Blueprint-wide role permissions: In addition to per-blueprint grants on blueprint:<name>, admins can grant a custom role view_all_blueprints or manage_all_blueprints so members get every existing and future blueprint in one action. view_all_blueprints grants the usable read level (view and execute) on all blueprints — matching the default per-blueprint grant on the built-in user role. manage_all_blueprints grants full control (view, edit, manage, and execute), including sharing and access management. Genesis checks ownership and per-blueprint grants first, then falls back to these role permissions — the same pattern as view_all_missions / manage_all_missions. The built-in admin role includes both permissions; the built-in user role does not include either by default.
• Granting from the UI: On a blueprint’s access panel, choose a role from the searchable Select a configured role list. The Grant button stays disabled until you pick a matching configured role; typed search text cannot become a grant on its own.
• What happens on rename: Renaming a custom or remote-backed blueprint requires Blueprint manage access. When a rename succeeds, Genesis migrates stored Blueprint role grants from the old resource name to the new one so existing view, edit, manage, and execute access continues to apply.
• What appears in the library: The Blueprint Library and related listing APIs return only blueprints the caller can view. For visible blueprints, Genesis separately evaluates whether the caller can manage, edit, or execute.

​

Apps, missions, and shared-role visibility

• Without explicit grants, apps stay owner-scoped by default and mission visibility follows the underlying thread access rules.
• For team-style sharing, admins can grant a custom role the view_shared_role_resources permission. When two users share that same role, Genesis lets them see each other’s apps and mission-backed threads without adding per-app grants or thread invitations one by one.
• This is a view-only widening. It does not grant app refresh, edit, or manage, and it does not let teammates hide, delete, or change access on each other’s threads.
• Built-in roles do not include view_shared_role_resources by default.

​

Practical Flows

​

Who creates a connection, and how can an agent use it?

• Connections in Config → Connections
  • Creation: An admin (or a user with manage_all_connections) creates the connection in the UI. Credentials are stored as secrets. For database connections, optionally set Access intent (unspecified, read_only, or read_modify) as an awareness label.
  • Use by an agent: When an agent uses that connection (e.g. to access GitHub or Snowflake), Genesis checks whether the agent (and your role, if relevant) can access the connection’s secrets. Typical setup: create the connection, bind Roles with Access on the connection (or grant secret access on a custom role), create a connection profile role if you want a reusable bundle, then assign that profile to the agent on Data Access. Double-key and user OAuth rules still apply at runtime.
• Database connections created in chat
  • Creation: In a chat, you (or an admin) ask an agent (e.g. Eve) to add a database connection. The agent that creates it becomes the owner and specifies which agents are allowed to use it.
  • Use: Only the owner and agents on the allowed list (or all agents, if configured that way) can use that connection.

​

Who can create and use a secret?

• Create: Anyone with access to Config → Secrets can create a secret; they become the owner unless it’s created as a system secret. Creating secrets in the UI may require the manage_secrets permission if your administrator has restricted access.
• Use: As above—owner, system/shared, admin, or a role with access to that secret. When an agent uses a connection whose credentials are in secrets, that agent’s identity is used for the check.
• Update/delete: Owner or admin; system secrets only by admin; shared by any authenticated user.

​

How are users given access to interact with an agent?

• Agent access is controlled by role → agent policies, not by a single “user” permission.
  1. Assign the user to a role: An admin goes to Config → Users, finds the user, and assigns a role (e.g. user or a custom role).
  2. Give that role access to specific agents: In Config → Users, the admin configures which agents each role can access (e.g. “user role can access the Data Agent and Report Agent”). Eve is special: the admin role can always access all agents; other roles need explicit access to Eve, and typically only admins are given access to Eve.
  3. If no agent-access policies are configured for the user role, Genesis may allow access to non-Eve agents by default (to avoid locking everyone out); Eve remains admin-only.
• So: user gets a role → that role is granted access to specific agents → the user can open chats with those agents. Admins do this in Config → Users (roles and agent access). An admin can also ask Eve in chat to assign a role to a user or to grant a role access to an agent. For chat-based user targeting, see rbac_action guidance.

​

Admin audit log

SELECT action,
       actor_user_id,
       actor_email,
       target_type,
       target_id,
       source,
       timestamp
FROM   ADMIN_AUDIT_LOG
WHERE  action LIKE 'role.%'
ORDER  BY timestamp DESC
LIMIT  100;

• Dashboard: the Config → Admin Audit Log page lists events with date, action, actor, target, and source filters, a row-detail view of the details JSON, and CSV export.
• REST API: GET /api/admin/audit-log returns a cursor-paginated list and accepts since, until, action (exact match), action_prefix (prefix match), actor_user_id, target_type, target_id, and source filters; GET /api/admin/audit-log/{audit_id} returns a single event.

​

Summary Table

​

FAQ: Connections and credentials (Git, Databricks, Snowflake, etc.)

​

Whose credentials are used when I chat with an agent (e.g. clone a repo, create a pull request (PR))?

​

When would my (the user’s) Personal Access Token (PAT) or connection be used?

​

What’s the best way to summarize how PATs work for agents?

​

We want all work in an external tool (e.g. GitHub, Jira) to show up as “Genesis.” What do we do?

​

In a mission or blueprint (e.g. automations), whose PAT is used—the agent’s or the user who started it?

​

Can we declare the connection once at mission setup (e.g. “use my Databricks” or “use my Snowflake”) and have it used for the whole mission without asking again?