---
key: wait-for-a-person-to-approve
title: Handle an action that waits for a person's approval
audience: developer
section: api/agents
routes: []
since: 0.0.1
updated: 0.0.1
status: published
summary: 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.
keywords: [approval_required, approvals, ask a person first, human in the loop, 403, pending approval]
related: [api-errors, nova-mcp-tools, run-an-ai-teammate, approve-an-agents-request]
---

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
HTTP/1.1 403 Forbidden
```

```json
{
  "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.