Skip to content

Human approval per credential

SecurityImpreza documentationRead as Markdown ↗

Human approval (human-in-the-loop) lets you mark, per credential, the operations that must not run on the credential's own authority. A marked operation does not execute: it becomes an approval request pinned to the exact call, a person with management access approves or denies it in the clientarea, and only then — re-submitted with the approval id — does the operation run. Once.

This exists for the customer who hands an AI agent a credential and still wants a person in front of the irreversible calls. Scopes decide what a credential may do at all; spend ceilings decide how much it may spend; this decides who says yes to the calls that matter.

The policy

A policy is configured per credential in the clientarea (API Management → Approvals), by the account owner. It names:

Field Meaning
classes Operation classes to gate: destructive (delete, uninstall, terminate, cancel), spend (orders, upgrades, payments), security (rotate or revoke credentials, mint sub-credentials, export or rotate the .onion key, install the Impreza agent).
operations Individual MCP tool names to gate, e.g. impreza_order_vps.
ttl_minutes How long a request lives: 15–60 minutes, default 30.

Default is off. A credential with no policy behaves exactly as before — existing credentials change nothing until the owner marks them. A sub-credential never loosens its parent: the effective policy is the union of the parent chain's policies, so a child inherits every requirement and can only add more, and tightening a parent later tightens every child with it.

What happens when an operation is marked

  1. The agent calls the operation. It does not run. The answer is a stable approval_required result with the approval_id, the expiry, and the clientarea link — nothing was executed and nothing was changed.
  2. A webhook event agent.human_approval_requested is queued for the account (throttled per credential, like the spend-ceiling notices).
  3. A person approves or denies in API Management → Approvals. The page shows the operation, the credential, and a summary of the call. Argument values that could be secrets were never stored, so the page cannot show them.
  4. Once approved, the agent re-submits the same call with approval_id="apr_…". The operation then runs.
  5. Denied and expired requests also become webhook events (agent.human_approval_denied, agent.human_approval_expired).

The rules that make it safe

  • Pinned to the exact call. The request stores a digest of the normalized arguments. Re-submit with any argument changed and the execution is refused — approving "uninstall dpl_a" approves exactly that, not "uninstall anything".
  • Single use. Each approval executes exactly once. Two concurrent re-submissions race on an atomic claim and only one dispatches.
  • A credential never approves. There is no API route and no MCP tool that approves, denies, or edits a policy. Decisions exist only as clientarea POSTs behind a session, a team permission and a CSRF token — so an agent cannot approve itself, through a sub-credential, or through an API key. Read-only members see the queue but cannot decide; only a person with the manage products permission can approve or deny, and only the owner changes policies.
  • Independent of the other guards. The scope ladder, the two-step confirmation and the daily/monthly spend ceilings all still apply to an approved call. Human approval adds a check; it never removes one.

Plan-bound host request limits

The VPS reinstall pilot requires a separate owner grant for each credential, operation and server, followed by approval of the exact stored plan. Its request limit counts plans created over the last 24 hours across all servers for the credential, rather than starting a new counter for each server. The pending plan/operation limit uses the same shared scope. Denied, expired and completed requests still count toward the 24-hour request limit until they age out.

For a sub-credential, each credential in its parent chain is checked against its shared counts. The selected server grant and the strictest parent limits apply; plans requested by siblings also use the parent's allowance. Granting another server or increasing one server's limit does not reset these counters. A grant never replaces the human decision or permits an operation on another server.

Reading the state

  • REST: GET /v1/approvals (the queue), GET /v1/approvals/{approval_id} (one request), GET /v1/credentials/{id}/hitl-policy (a credential's stored and effective policy). All read-only.
  • MCP: impreza_list_approvals, impreza_get_approval and impreza_get_credential_policy — the same reads for the agent, so it can tell you what is parked instead of blindly retrying. Approving is not a tool and never will be.
  • Minting: impreza_mint_subcredential (and POST /v1/credentials) accepts a hitl_policy at creation — it can only add requirements, never drop one the parent carries.

Audit trail

The per-credential activity extract (GET /v1/credentials/activity?format=csv, or impreza_agent_activity) records the whole lifecycle next to the tool calls: hitl:request, hitl:approve or hitl:deny with who decided, hitl:execute when the approved call ran, and hitl:expire. Secret values and sensitive parameters are never written — the rows carry identifiers only.

Revoking plan-bound host permissions

The account owner can revoke the VPS reinstall pilot's explicit host grant even while the owned server is suspended. The credential must still be active and owned by the account. New or renewed grants require an active server.

Reactivation does not undo a revocation. The revoked marker stays stored, so the credential cannot fall back to the legacy reinstall route. A previously approved plan is refused before dispatch. Restoring permission requires a new explicit owner grant after the service is active again; it does not revive an older plan. Revocation does not cancel an operation already submitted to the provider, whose receipt can still be reconciled without restoring the old grant.

Managed ingress reload

Host plans also offer managed_service.reload: a reload of the managed ingress on a server you own, approved by a person and applied once. It needs Impreza agent 0.6.36 or later and a managed ingress unit that declares the fixed reload (ExecReload); the agent version alone is not enough. The loaded unit and its reload capability must be confirmed on the server before a plan is offered. Missing or changed reload support is a refusal, not proof that a reload works, and the capability read answers 503 on a server where it is not confirmed. VPS reinstall keeps its existing contract.

Managed reload is offered on Ubuntu 24.04 (amd64) servers. The owner grants the exact operation/server in the portal. Every credential ancestor must also grant that same operation. manage alone is insufficient. Renewing the OAuth credential of a connected AI tool keeps the same identity and its grants, so a granted operation is not lost at renewal; an explicit reauthorization revokes the previous credential. A grant is still not permanent: revoking it removes it. A verified operator recovery and health binding, active managed ingress unit with explicit reload support, current agent generation and an independently owned affected-app set are prerequisites. The agent creates its own maintenance journal directory when it is missing; you do not prepare it by hand.

Read GET /v1/host/services/{service_id}/maintenance, then prepare:

{"service_id":799,"operation":"managed_service.reload","ttl_seconds":300}

Use POST /v1/host/plans or impreza_prepare_host_plan. Reload accepts only those three fields; the technical TTL is 30–300 seconds (default 300). No unit, command, path, environment, template, package or restart fallback is accepted. The stored preview binds owner, credential, host generation/boot/state, capability, affected application references, connection-loss warning and deadline. An independent human must approve that exact immutable plan in the portal. The approval and the dispatch check compare the plan in a canonical form, so the way the database stores the preview cannot make a valid approval fail.

Apply through the existing plan endpoint/tool with exactly the returned plan_id, plan_digest and approval_id. Acceptance means a durable queued intent, not completion. Revocation/drift/expiry is checked again at poll dispatch. Other host writers are reserved out while the reload is pending. Reading the plan never redispatches; repeating apply returns the same plan, not another command. An uncertain or partial result stays visible for reconciliation. The agent's reconciliation observes the existing local journal before the next poll. It can complete only a durably acknowledged successful effect with fresh, matching agent/generation/boot/state/capability/app identity before and after route health. A healthy unit alone never proves that the original effect completed. A crash before the effect acknowledgement was durably saved, failed IPv6 after IPv4, unknown result, changed identity, cancelled reservation or backward clock is not certified; it is left for explicit operator reconciliation.

The agent never reloads or restarts during recovery. Its successful observation is saved before transmission and acknowledged by exact receipt, not just command ID. Authenticated result processing admits one monotonic partial-to-completed transition bound to the same plan, command, generation and fence; the original receipt bytes and original partial audit event remain preserved. Lost responses repost the same receipt; late partial/refused or conflicting observations cannot reopen a completed plan. A cancelled plan with a possible effect cannot be certified by a delayed healthy report.

No reset endpoint or automatic retry of the effect exists. A lost poll response without a local intent still needs operator reconciliation. Older journals without the effect proof remain blocked rather than being retroactively certified. Ordinary v1 receipts remain compatible; only a new recovered success adds the optional boolean reconciled:true. There is no automatic rollback.

When a reload stays partial

If a reload's outcome cannot be certified, the plan stays partial and its history is kept. While that plan is partial, the same service does not take another plan, so nothing new is applied on top of the unknown outcome. Other commands on the host are held only until the plan's expiry plus ten minutes. That clock does not close the partial plan, and it does not lift the hold on the same service. The Impreza agent keeps running: it reports the block locally, without restarting, reloading or retrying anything by itself. The plan the owner reads shows partial. The reason string is on the server, from impreza-agent maintenance status. It is not part of the plan payload.

Releasing the block is a deliberate local step. After checking the server, a person with root on it runs:

PLAN_ID='<plan_id>'  # the partial plan's plan_id
sudo impreza-agent maintenance status
sudo impreza-agent maintenance release --plan "$PLAN_ID"
  • status is read only. It says whether a maintenance blocks the server and what can end it.
  • release never reloads, retries, deletes the journal or changes the stored receipt. It refuses unless the open result was already reported, no operation is running, and the agent, generation, unit and reload bindings still match the plan. The stored ingress rules must still be enforced, and every bound route must be healthy at that moment.
  • A release does not prove that the original reload worked. It cannot repair a server whose root account is compromised.

After the release, the plan shows released, not completed: the partial outcome stays in the history and is never counted as a success. A new plan can then be prepared and approved on its own; nothing is replayed.

The Go SDK adds PrepareManagedServiceReload(ctx, serviceID, ttlSeconds); Python sync/async account resources add prepare_managed_service_reload(service_id, *, ttl_seconds=300). Preview/status are typed; these helpers cannot approve a plan.