Handle an action that waits for a person's approval

When an action needs a person's approval, the call answers approval_required. Why it happens, what the response holds, how long it lasts, and how to finish the action once approved.

Two things send a call to a person for approval:

• Actions the organization chose. An organization can list actions under Ask a person first on an API key or an AI teammate. Nothing is on that list unless someone puts it there. A connected app has no such list.
• Actions Nova protects with an identity check. A few actions make a signed-in person prove it is them again: changing where payouts are deposited, disconnecting the payment provider, changing someone's role or removing them, bulk data exports, carrying out privacy requests. Software cannot pass that check, so when a credential attempts one, a person approves it instead. details.action names the check.

Either way the action does not run until a person says yes.

What your software receives

HTTP/1.1 403 Forbidden

{
  "error": {
    "code": "approval_required",
    "message": "A person has to approve this action before it can run.",
    "request_id": "…",
    "details": {
      "action": "billing.invoices.send",
      "approval_request_uid": "agap_1a2b3c4d5e6f7a8b",
      "expires_at": "2026-09-29T13:00:00+00:00",
      "retry": "Repeat the same call after the request is approved."
    }
  },
  "detail": "A person has to approve this action before it can run."
}

At the same moment Nova notifies the credential's accountable person and the organization's admins. They approve or decline it in Nova's Approvals inbox (on both the AI Teammates page and the API & Connected Apps page).

Finishing the action

1. Tell the person what you tried and that it is waiting. Keep the approval_request_uid.
2. After it is approved, repeat exactly the same call: same method, same path, same query and the same body. It runs once.
3. A different call (another amount, another record, a changed field) is a different request and starts a new approval.

An approval lasts 72 hours (expires_at). An expired or declined request cannot be used; a new attempt starts a new one.

Over MCP

The tool result is marked as an error and carries the same error.code: approval_required and details. Say so to the person in plain words ("Sending the invoice needs someone to approve it in Nova"), then call the same tool with the same arguments once they have.

What to avoid

• Do not poll by repeating the call; each attempt while one is waiting is refused the same way and adds noise to the inbox.
• Do not work around it with a different operation that has the same effect. The organization chose this deliberately.
• If you need to know whether it has been decided, ask the person.