Ask before a sensitive action

Bind a token to one action, ask AuthFI whether the agent may do it, and wait for a person to approve when a rule requires one.

Before an AI agent does something that matters, such as sending money or merging code, it asks AuthFI. The answer is allow, deny or approval_required. Use this guide to add that question to your agent, and to wait for a person when the answer is approval_required.

Before you begin

You need:

• A registered agent and its access token. See Give an AI agent an identity.
• The permission for the action it asks about, given to the agent through a role, and a capability granted for it. The console shows a capability as a permission. See Limit what an agent may do.

curl https://acme.authfi.io/apis/regional/v1/ai/auth/transaction-token \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "transfer:accounts",
    "resource": "account:4821",
    "context": { "amount": 1200, "currency": "USD", "account_type": "business" }
  }'

{
  "data": {
    "transaction_token": "eyJhbGciOiJFZERTQSIs…",
    "txn": "0b7d6a52-…",
    "token_type": "N_A",
    "expires_in": 60
  }
}

export TRANSACTION_TOKEN=<the transaction_token from the response>

curl https://acme.authfi.io/apis/regional/v1/agents/authorize \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_7f3a9c21",
    "transaction_token": "'"$TRANSACTION_TOKEN"'",
    "action": "transfer:accounts",
    "resource": "account:4821",
    "context": { "amount": 1200, "currency": "USD", "account_type": "business" }
  }'

{ "data": { "decision": "approval_required", "approval_id": "3f0c2b6e-…", "reason": "policy_step_up" } }

{
  "data": {
    "approval_id": "3f0c2b6e-…",
    "status": "approved",
    "requesting_action": "transfer:accounts",
    "approver_user_id": "5a1e…",
    "created_at": "2026-10-09T10:02:11Z",
    "resolved_at": "2026-10-09T10:02:48Z",
    "expires_at": "2026-10-09T10:17:11Z"
  }
}

Check that it works

Run the three steps with an action that one of your project rules sends to a person. That is a policy with the effect "Require step-up".

1. The authorize response has "decision": "approval_required" and an approval_id.
2. Poll the approval. Its status is pending.
3. In the console, open Approvals. Under "Agents waiting to do something", choose Allow on the request and confirm.
4. Poll again. The status is approved, and approver_user_id and resolved_at are set.

Open an approval request directly

An agent can also open an approval request without the authorize step. Use this for an action that your own code decides is sensitive.

A client assertion is the short statement the agent signs with its private key to prove who it is. Build one as you do in Give an AI agent an identity.

The response is 202 Accepted with the approval, in the pending status. Poll it as in Wait for a person.

How an approval is decided

• A person decides. The decision is made by a signed-in person on the Approvals page. An agent cannot approve through its own credentials.
• A policy decides when to ask. An action needs approval when a project policy with the effect "Require step-up" matches it.
• No answer is a denial. A request that nobody answers expires. An expired request can never be approved.
• Everything is recorded. The request, who decided, and when are in the audit record.

Troubleshooting

Next steps