Skip to main content

Operators and roles

Three separate rights apply to an agent wallet: update decides its limits, operate runs it inside those limits, and spend lets the agent ask for payments. An operator is a person who has been assigned to a wallet and holds operate on it. This page shows how to assign operators, what each right allows in the dashboard and in the API, and how to give a monitoring tool read-only access. The reasoning behind the split is in Organizations, applications and wallets; the full table of rights of every role is in Permissions & Roles.

From the dashboard​

What each right allows​

RightWhat it allows on an agent walletWho holds it
updateEdit the spending policy and the destination rules of a wallet or an application, set the monthly budget of an application, and assign operators.Owner and Admin.
operateGet its MCP configuration, register a new key for the agent, approve or decline held payments, pause and resume the wallet, and ask for a top-up.Owner and Admin on every wallet. Editor, shown as "Operator" in the dashboard, only on the wallets they are assigned to.
spendAsk Keyban to evaluate and sign a payment.The agent's API key, and nothing else.

Owner and Admin also create and delete wallets, and revoke an agent's previous key. A Viewer can read wallets, their payments and their policy, and can do nothing else. Replacing an agent's key goes through the API, and the steps are in What a leaked credential gives an attacker.

The monthly budget of the organization is reserved to the Owner role: only an Owner sets or removes it, and only an Owner approves or declines a raise request that reaches it. An Admin cannot, even with the organization settings right and even for their own request. An Admin can still set the budget of an application and the monthly budget of a wallet, and ask for a raise from the dashboard. See Control spending.

Some actions need more than the right. Every operate action (pausing and resuming a wallet, approving and declining a held payment, and the mission decisions) must be attributable to a person, so an API key is refused with 403 whatever its permissions, even one that belongs to an Owner. Approving or declining a held payment accepts a signed-in dashboard session or a person's OAuth sign-in (the kind keyban admin login uses), and never an API key. No admin tool does it. Publishing a mission, validating a trial or a run, declining a run and cancelling a trial or a run need a browser session: OAuth is refused there. The agent's own key never holds update or operate: an agent cannot change its limits, pause or resume its own wallet, or approve its own payment.

Choose the operators of a wallet​

  1. When you create a wallet, the wizard asks who operates it. Only members whose role grants operate can be picked. If you do not choose, you are the operator.
  2. On an existing wallet, open the wallet page and the Operators card, choose Edit, pick the members and Save. This needs update, so only Owner and Admin can do it. The list you save replaces the previous one.
  3. An operator who no longer wants the wallet can use Leave on the same card. It is disabled for the last operator: ask an Owner or Admin to assign someone else first.

A wallet always has at least one operator, and an empty list is refused. Assign operators with care: an operator receives the wallet's MCP configuration, so assigning one hands over what the agent needs to run, and they can approve that agent's held payments. The limits stay out of their reach, because only update edits them.

When a wallet has operators, they are the people notified by e-mail of a payment that waits for approval, and the payment shows in their Inbox as Yours to decide. Owner and Admin can still decide as a fallback. When a wallet has no effective operator, because the member left the organization or lost the role, Owner and Admin receive the requests instead, and the card says "No operator: admins receive the requests". See Approve payments.

Give a tool read-only access​

A follower key is an API key that can read agent wallet data and do nothing else: it holds read on agent wallets, never operate, spend or update. It suits a supervision or reporting script that follows spending and payment history, for example through the expense endpoints. See Track spending.

The dashboard has no button for it. An Owner or Admin, who hold the right to create API keys, mint one for a wallet through the API or with the admin tool create_wallet_follower_key, and give it a name. The key is shown once, in the response, and cannot be read again: store it at once. The follower key is created for one wallet but its read access is granted on agent wallets in general, so do not rely on it to hide the other wallets of the organization from whoever holds it.

What the agent can do​

Nothing in this feature is open to the agent: operators are assigned by people, and the agent's key can only ask Keyban to evaluate payments. The agent can still help the user find the right person:

  • When a payment is held, the agent tells the user to approve it in the Inbox. It cannot approve it, and no tool does. See Approve payments.
  • When a payment is refused because the wallet is paused, the agent reports policy/emergency-stop and asks the user to have an operator resume the wallet. See Refusal reasons.
  • When a payment is refused because a monthly budget is used up, the agent reports the level named in the reason and asks the user to have an Owner or Admin raise it (the organization budget is the Owner's alone). An agent key can never raise its own budget or set one.

An assistant using the admin tools of the Keyban MCP server, after keyban admin login, acts with the rights of the person who signed in. It can create a wallet with its operators, mint a follower key with create_wallet_follower_key, and, for an Owner, an Admin or an operator of the wallet, pause and resume it with freeze_wallet and unfreeze_wallet. Replacing the operators of an existing wallet is deliberately not exposed through MCP. See the Admin tools.

Limits​

  • Only a member whose role grants operate can be an operator: Owner, Admin or Editor. A Viewer cannot.
  • Assigning operators needs update. Pausing a wallet needs operate. They are separate on purpose.
  • A wallet cannot be left without an operator, and the last operator cannot leave.
  • The owner field that older integrations sent when creating a wallet is refused: use operators.
  • An API key cannot approve or decline a payment or a raise request, nor pause or resume a wallet: it gets a 403. A key bound to one agent wallet cannot set a budget either. Approvals and pauses accept a signed-in dashboard session or a person's OAuth sign-in. There is no admin tool to approve, so approve in the dashboard.
  • A follower key is shown only once, when it is minted. If it is lost, mint another.