When a capability policy sets something to Human approval, the agent waits for human approval before taking action. Requests appear on the Approvals screen, and you're also emailed.
Before you start
A capability policy with at least one capability set to Human approval, used by an API key. Requests set to Guardian only reach you if Guardian passes them to a person.
The Approvals screen
Open the profile menu at the top right and choose Approvals.
How approvals work. Approving lets the key use that capability for now. The next time, it asks again.
My keys shows requests from your own API keys. All account keys shows every key's requests.
Requests waiting for you. It's empty when there's nothing to decide.
Step 1 - Read the request
Each request shows the key, the system, and what the agent wants to do. The most useful requests include the actual command and a reason. If a request doesn't give you enough to decide, deny it and ask the key's owner to add a reason.
Step 2 - Approve or deny
Click Approve or Deny. You can also decide from the email.
An approval covers that API key on that system, not just the session that asked. If the agent's session ends while it waits, it can open a new one and carry on.
How an agent should ask
Run the blocked command again with --request-approval, so the approver sees the real command instead of a capability name:
hv exec --request-approval \
--approval-reason "Building the release for OPS-4821" -- ./build.sh
hv approvals wait <approval-uuid> # waits until someone decides
hv exec -- ./build.sh # works while the approval lastsTo ask for a whole capability rather than one command:
hv approvals request --system buildbox shell.exec file.write \
--reason "Installing the toolchain for OPS-4821"Other commands: hv approvals list shows this key's open requests and approvals; hv approvals status shows one request.
NOTE: A command that needs approval exits with code 9, and the API returns ERR_STEP_UP_REQUIRED. Tell your agent that exit 9 means "ask for approval", not "failed".
If there are too many requests
If people start approving without reading, the approvals aren't protecting anything. To reduce them:
Gate fewer capabilities. Your own policy can require approval for
shell.execonly, instead of all six risky capabilities.Let Guardian handle routine requests. Set a capability to Guardian instead of Human approval. Guardian decides what it can and passes the rest to you. See Secure the account.
See past decisions
In Admin > Activity Log, approval events show as automation.approval.requested, automation.approval.blocked and automation.approval.expired. See The activity log.