Agents and access

Each hub in a deployment appears in the Console as an agent. Its page is where you decide who can use it and what each person may do, check its scheduled work and review what happened in it.

When to use thisCopy Anchor Link

Use the Access tab to add a new user, give an existing user an agent, grant or remove a restricted capability, delegate an agent to another administrator, or replace an old "Everyone signed in" grant with named people. The rules the tab applies are described in Identity and access. For a first grant from start to finish, follow Restrict a tool.

The agent cardsCopy Anchor Link

Agents in the sidebar is the Console's landing page. Below the totals it shows one card for every agent you manage. Search with Find an agent by name or by key. The count beside the search shows how many agents you manage.

Each card shows the agent's name, its key (the hub folder name in lowercase), its tags, and Tokens used and Approx. cost for the chosen period.

Select a card, or Manage access, to open the agent's Access tab. Runs & schedules and Activity go straight to those tabs.

An agent's pageCopy Anchor Link

The agent page has a header with the agent's name, its access tag and its key, and three tabs. Each tab has its own address, so you can bookmark it. When you can use the agent yourself, Open chat with and the agent's name opens it in the chat app.

The Access tabCopy Anchor Link

The Access tab, headed "Access to" and the agent's name, lists the people with direct access and what each may do. Add user sits at the top. Search by name or email. Results are shown 50 at a time.

Capability tags tell you how each capability is held:

When the agent is tagged Legacy access, a warning explains that its access is still managed in the chat app, and Add user and the edit controls are disabled. The existing chat app access keeps applying. The Console API refuses edits to such an agent as well, so nothing written here could be overwritten later by migration. Migrate the hub with hubzoid access migrate, as described in Access administration.

Everyone signed inCopy Anchor Link

Access goes to named people. Nobody can create access for everyone who can sign in, organization administrators included. The Console has no control for it, and the API, changes proposed by an agent, hubzoid grant '*' and the access store all refuse it.

An agent that was open to every signed-in user before this release, or before its hub was migrated, keeps that access as an Everyone signed in row with Use this agent, and a notice above the list says it was carried over. It keeps working until an organization administrator removes it. Agent administrators see the row as Read-only. To replace it with named access:

1. Give the people who need the agent their own access: Add user for someone new, or Edit access on their row, or Add an agent on their details under People, for an existing user. Give access to the account your workflows run as in the same way.
2. Select Remove on the Everyone signed in row. The confirmation says how many users open the agent only through it. They, and anyone who signs up later, lose entry. Named grants are not affected.
3. Confirm with Remove access for everyone.

On the server, hubzoid revoke '*' use_hub --hub finance ./finance does the same. While the grant exists, the editor shows Public beside Use this agent for a person without a direct grant, and its help says that a direct grant keeps their access after "Everyone signed in" is removed.

Add userCopy Anchor Link

Add user always creates a new user, with their first access to this agent, in one step. It never changes an existing account. Add user on the People page works the same way, with initial access chosen per agent.

1. Enter the person's Name and Email address. They sign in with this email.
2. Type a Password, or select Generate for a random 20-character one made in your browser. It must be at least 8 characters and at most 72 bytes. Alternatively, tick Google sign-in only, described below.
3. Choose capabilities. Use this agent is ticked to start with.
4. Select Review changes. The review shows the new user, the agent and each capability being added. Select Create account.
5. The panel confirms that the person can now sign in, and shows the chat address, their email and the password once, with Copy and Copy sign-in details. Share them yourself. No invitation or email is sent. The password is never stored or logged, and it is cleared when you select Done.

The account is created with the chat app's normal user role. The Administrator role is set later from the user's details under People.

Google sign-in only creates an account with no password to share. The person selects Google on the chat app's sign-in page, and the chat app links that sign-in to the account by email. It can be ticked only when the chat app has Google sign-in configured and OAUTH_MERGE_ACCOUNTS_BY_EMAIL=true. Otherwise it is disabled with a hint. When Google sign-in is limited to some email domains, only those addresses are accepted. See Authentication.

The account and its access live in two systems that cannot commit together, so every result says exactly what exists:

Add user needs account management set up on the server: the chat app's internal address, which hubzoid run and a gateway provide, and the chat app service account in HUBZOID_GATEWAY_ADMIN_EMAIL and HUBZOID_GATEWAY_ADMIN_PASSWORD. Until then the panel says that creating accounts isn't set up on this server.

To give access to an email before its account exists, for example for someone who will first sign in through single sign-on, use the server or the management API: hubzoid grant priya@example.org use_hub ./finance, or POST /portal/api/access/apply. The Console no longer does this. Until the person signs in, their status reads Not signed up yet.

Edit accessCopy Anchor Link

Edit access on a row opens the editor for that person, titled "Edit access". From a user's details under People, Edit access next to an agent, or Add an agent for an agent they can't use yet, opens the same editor directly, through an address of the form #/agents/<key>/access?edit=<email>. Add an agent starts with Use this agent ticked.

The editor shows the person with their email and account status, then Capabilities in groups. Empty groups are hidden.

Hub access and No longer available are always open. The other groups start collapsed, and their header says what they hold, for example "Restricted tools · 2 selected", adding "· 1 not configured" or "· needs attention" when that applies. Choices are kept when a group is collapsed. Group headers and help buttons work with a keyboard, by touch and with a screen reader.

Each capability shows its label, a Sensitive tag where declared, and a short status when its settings are missing, such as "Jev key missing", or "Not checked" when they may be in a secret the Console does not read. Configuration is separate from permission. You can grant a capability before it is configured, but it cannot run until an operator adds the setting, and adding a setting never grants anyone access. The question mark button beside a capability shows its description, where it works (chat, assistants over MCP or workflows) and why it is locked.

The editor applies the same rules as the server and labels a locked checkbox instead of failing on save:

A person blocked by an administrator gets a warning, and new capabilities are locked while existing ones can still be removed. A person whose chat account is unavailable gets a warning that it was removed or not found and that access resumes if the account reappears, with the same locks. If a selected capability can no longer be granted when you review, for example because it was removed from the agent meanwhile, the editor opens its group and marks it.

Remove all access removes use_hub and with it every capability the person holds in this agent, in one request. Access inherited from organization administrator rights or "Everyone signed in" still applies. Cancel with unsaved edits asks before discarding them.

A workflow:<name> or workflow:md:<task> identity from before workflows ran as user accounts keeps its row, labelled Legacy service identity, and its access can still be changed or removed. New ones cannot be added in the Console, and runs that act as an account do not use their grants. Give the account the workflow runs as the access it needs instead.

Delegating an agentCopy Anchor Link

To delegate an agent, an organization administrator ticks Manage access under Administration for a person. That person becomes an agent administrator for this agent only. They can open the Console, see this agent, its runs and activity and the people with access to it, and add users with access to it. Because every direct capability includes Use this agent, they can chat with the agent too. Restricted tools still need their own grants.

An agent administrator grants or removes only the capabilities they hold in that agent themselves, never Manage access. They cannot change their own access or an organization administrator's, remove all access from someone who holds a capability they do not, or remove "Everyone signed in". They cannot approve sign-ups, reset passwords, change roles or delete users. The server checks every change, and a refusal names the capabilities that are outside their access.

Sensitive capabilitiesCopy Anchor Link

A capability is sensitive only when it is declared so. Hubzoid never infers it from a name. For a restricted tool, declare it in identity/permissions.yaml in the hub:

payroll:
  label: Run payroll
  description: Process employee payroll and view salaries.
  sensitive: true

That file labels restricted tools only. An entry for a built-in capability is ignored. Built-in capabilities declare their own sensitivity, as Share artifacts publicly does, and connector capabilities are sensitive.

A sensitive capability shows an orange Sensitive tag in the editor and an orange tag in the table. When a change grants one, the review adds the warning "This grants a sensitive capability", names each sensitive capability and asks you to make sure the person should have it.

Review and saveCopy Anchor Link

Nothing is saved while you tick boxes. Review changes shows the change before anything is written.

The review shows the person with their email and the agent, then:

• Adding: each capability being added, with its Sensitive tag and a note when it can't run until configured.
• Removing: each capability being removed.
• A warning when Use this agent is removed. The person loses access to the agent, or, when they still hold it through organization administrator rights or "Everyone signed in", only their direct access is removed.
• The sensitive capability warning, when one is being granted.

Select Back to adjust, or Save change (Save N changes for several) to apply. When the change removes Use this agent, the button reads Remove access.

How saving worksCopy Anchor Link

The whole change set is sent in one request, POST /portal/api/access/apply, with the policy revision that was current when the tab loaded. The server then:

1. Refuses any change to an agent that still uses legacy access.
2. Checks each capability against the agent's catalog. A capability that does not exist, or one that comes with Use this agent, is refused, except a removal of a grant already held.
3. Refuses any grant to "Everyone signed in".
4. For an agent administrator, refuses changes outside the capabilities they hold there, Manage access, their own access and an organization administrator's access.
5. Refuses new grants to a blocked or unavailable account.
6. Takes the database write lock, confirms the revision has not moved, applies every operation and increments the revision, all in one transaction.

Either every change applies or none does. If access changed after you loaded the page, the save is refused, the panel reads "Nothing was saved" and the Console reloads the current access so you can review again. If the response is lost, for example to a network drop or a server error, the panel reads "Save not confirmed", because the transaction may have committed just before the connection failed. The Console reloads the access so you can see what applies before trying again.

After a successful save, the editor closes and a notice reads "Access updated". The permission check changes immediately, and the chat app's agent list follows it. While a save is in flight, the editor cannot be closed and navigation is held. With unsaved edits, leaving the page asks for confirmation first. Every saved change appears under Activity, Access changes, with you as the actor.

Blocked people on the Access tabCopy Anchor Link

The Console no longer blocks or reactivates people. Someone blocked in an earlier release, or by the safeguard for an email reused by a new chat account, lost every direct grant when they were blocked, so they usually no longer appear on Access tabs. Rows marked Blocked that do appear are usually accounts that were removed or can no longer be found in the chat app. They keep their grants but hold nothing effective, so their capabilities read No access until the account is available again. To offboard someone, delete the user under People. See People and activity.

Next stepsCopy Anchor Link

Read this page as Markdown