Identity and access

Hubzoid enforces access in the agent runtime, in code that runs before a tool executes. The model is never the gate. This page describes the model that code implements: who a caller is, what they hold, which channels may reach restricted tools, where each decision is recorded and what happens when something goes wrong.

When to use thisCopy Anchor Link

Read this before you put a tool in restricted/, grant access to a person or the account a workflow runs as, or open a chat surface such as Slack or WhatsApp to restricted tools. For the hands-on version, follow Restrict a tool. To manage grants with a screen instead of the CLI, see Agents and access.

The modelCopy Anchor Link

A grant is one row: a subject holds a permission in a domain. Hubzoid keeps grants in the hz_grants table of the operational database and evaluates them with Casbin, using direct grants only. In a managed hub no role or group carries permissions, so the question "what can this person do in this agent?" has exactly one answer in one table.

[request_definition]
r = sub, dom, act

[policy_definition]
p = sub, dom, act

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = (r.sub == p.sub || p.sub == "*") && (r.dom == p.dom || p.dom == "*") && (r.act == p.act || p.act == "*")

A request is allowed when any grant matches. Each part matches exactly or through the * wildcard. Subjects, domains and permissions are compared in lowercase with surrounding spaces trimmed, so Ledger, LEDGER and ledger are the same key. The source is in hubzoid/access/store.py (opens in a new tab).

SubjectsCopy Anchor Link

DomainsCopy Anchor Link

PermissionsCopy Anchor Link

These rules apply to every write, from the Console or the CLI:

• Granting any permission other than use_hub in an agent also grants use_hub there, in the same transaction. Anyone who can use a tool can open the agent that has it.
• Removing use_hub removes every permission the subject holds in that agent.
• * is never a grantable permission, and new grants to the * subject are refused.
• The last organization administrator, meaning the last manage_access grant in *, cannot be removed, blocked, demoted or deleted.
• Every write increments a policy revision in the same transaction. Each process compares the revision before a check and reloads its in-memory policy when it has moved, so a change applies on the next check in every bridge that shares the database, with no restart.

How a decision is madeCopy Anchor Link

1. Caller identity. Each request binds an identity: the user (an email, or on a legacy hub a workflow subject) and the surface the request arrived on. On a hub that still uses legacy group access, the identity also carries the caller's groups. Outside a request, for example in hubzoid test, the identity is anonymous.
2. Surface check. An anonymous caller is refused. A caller whose surface is not in the restricted surfaces list is refused before any grant is read. A grant is necessary but never sufficient.
3. Account check. A blocked account is refused. If the access store cannot be read, the call is refused.
4. Grant check. On a managed hub, Casbin answers can(subject, hub, permission). On a hub with legacy group access, the permission must match one of the caller's groups.
5. Decision logged. The guard writes one row to hz_access_decisions. If that row cannot be written, the call is refused even when it was allowed, so every call that ran has a row.
6. Tool runs. Only now does the tool's own code execute.

A refused call does not raise an error into the conversation. The model receives a message it can explain to the person:

[access denied: 'payroll_run' requires the 'payroll' permission, which the current user does not have. This attempt was logged.]

Each row stores a short reason. The Console's Activity page explains each one in words.

Entering an agentCopy Anchor Link

A managed hub checks use_hub before any tool is involved. The chat endpoint takes the caller from headers set by the trusted front end (X-OpenWebUI-User-Email or X-Hubzoid-User), never from the request body. A request with no verified identity, or without use_hub, receives 403. If the access store cannot be read, the request fails with 503 rather than passing. The hosted MCP server applies the same use_hub check when it verifies a caller's key. A blocked account is turned away at both doors on every hub.

SurfacesCopy Anchor Link

The surface records the channel a request came through. By default only surfaces where each request carries one verified identity, a signed-in person or the account a workflow run acts as, may reach restricted tools.

Change the list with HUBZOID_RESTRICTED_SURFACES. It is a comma-separated, complete list that replaces the default of owui,web,api,mcp,workflow. Restart the hub after changing it.

HUBZOID_RESTRICTED_SURFACES=owui,web,api,mcp,workflow,slack-dm

SLACK_IDENTITY_MAPPING only supplies the identity. Slack requests reach restricted tools when that identity holds the grant and slack-dm is in the list. WhatsApp and Telegram senders are identified through the hub roster in identity/. See Slack and WhatsApp and Telegram.

Hidden versus refusedCopy Anchor Link

Each restricted tool gets two layers, built from the same tool registry that every backend uses.

Hiding is the clean experience. The refusal at call time is the wall. It holds when a tool is reached some other way: a prompt that names it, or an MCP client that calls a tool by name. Hiding writes nothing, so a person who never sees a tool leaves no row in Activity. Only calls are logged.

Two more details keep the wall intact. Sub-agents that the main agent delegates to are built from the same guarded registry. When a restricted tool has the same name as a built-in or tools_local/ tool, the restricted one replaces it, so an unguarded copy can never shadow it.

The decision logCopy Anchor Link

Each decision is one row in hz_access_decisions, written by the runtime at the moment of the call. The chat app never sees tool calls, so this is the only record of them.

Read it in the Console under Activity, Tool decisions, or on the server:

hubzoid audit ./finance --denied --user priya@example.org --limit 100

Changes to access are a separate record, hz_access_audit, with the actor, action, subject, agent and permission of every grant, removal, account creation, approval, password reset, role change and deletion, block, migration, schedule pause and run cancellation. Hubs upgraded from releases that wrote monthly logs/access-*.jsonl files import those files once, the first time the hub records or reads a decision, and leave the files in place.

Fail-closed behaviorCopy Anchor Link

Every failure denies. No failure falls back to a more permissive path.

Managed hubs and legacy group accessCopy Anchor Link

Each hub has its own authority marker, casbin_authoritative:<hub> in the hz_meta table. Hubs in one deployment therefore move to managed access one at a time, and an unmigrated hub keeps working exactly as before.

A hub created with hubzoid init becomes managed the first time the configured owner signs in, and that owner becomes the first organization administrator. hubzoid access bootstrap does the same from the server:

hubzoid access bootstrap --admin you@example.org --authoritative ./finance

An existing group-based hub moves with hubzoid access migrate. It previews the change, checks effective access for both permitted and denied users, and cuts over in one transaction after writing a backup. The whole procedure, including rollback, is in Access administration.

Next stepsCopy Anchor Link

Read this page as Markdown