# Approval

> Approvals: the calls NoClick holds for your account's owner's yes, read and answered from your own code.

When an agent, a connected app, a key used through MCP or an app's own code makes a purchase, a deletion that can't
be undone, a call your policy holds or one that raises a spending limit, NoClick holds the exact call and sends your
account's owner a link to approve it. Your code may answer it too, with one of your account's secret keys that
names the `approvals:answer` scope (a key with every scope, `*`, holds it only when it's named too):

```python
for approval in noclick.Approval.list(status="pending"):
    if approval.price and approval.price["amount_usd"] <= 20:
        approval.approve(note="Under $20: fine.")
```

A key never answers a call made with it (by its own code, through MCP, or by an agent or app acting as it), never
approves one whose terms a person accepts (it may decline it), and approves only what it could make itself: the
scopes the call needs (never a call only the owner and their NoClick assistant make), and a price that fits the key's
own monthly cap beside what it spent and approved this month (what it approves also counts against what it may
still spend itself). NoClick then runs an approved call itself, once, exactly as it was held, with no scope the
answering key lacks. While your account holds a key that would approve it, a call whose link reaches no person is
still held, with an empty `sent_to`, for your code (or the owner, signed in) to answer.

## noclick.Approval

```python
class Approval
```

A call held for your account's owner's yes, as they see it on its page.

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `str` |  |
| `status` | `str` |  |
| `action` | `str | None` | What the call does, in a person's words. |
| `price` | `dict[str, Any] | None` | A purchase's price: `amount_usd`, `recurrence`, `terms` and `renewal`; None for anything else. |
| `reason` | `str | None` | Why it waits for a person. |
| `operation` | `str` | The API operation it calls, by name (`phone_numbers_create`). |
| `method` | `str | None` |  |
| `path` | `str | None` |  |
| `arguments` | `dict[str, Any]` | Its arguments as the page shows them, secrets masked. |
| `connection` | `dict[str, Any]` | Who made it: `kind` (`assistant`, `agent`, `connected_app` or `key`) and `name`. |
| `user_id` | `str | None` | The user it acts for (None for your account). |
| `operation_id` | `str` | The held call's operation: `noclick.Operation.from_id(...).wait()` gives what it returned once approved, or raises once declined or expired. |
| `impact` | `dict[str, Any] | None` | What a deletion takes with it; None for anything else. |
| `consent` | `list[dict[str, Any]]` | Terms a person accepts by approving it (each `terms`, `title`, `url`): only the owner approves such a call. |
| `sent_to` | `list[str]` | Where NoClick sent the owner its link: `whatsapp`, `imessage`, `email`, or `web` (a card in the chat they were watching); empty when it reached nobody and waits for your code. |
| `created_at` | `Any` |  |
| `expires_at` | `Any` | When it lapses unanswered (a day after it was held). |
| `decided_at` | `Any` |  |
| `decided_by` | `str | None` | Who decided: `owner` (signed in, or from NoClick's link) or `code`; None while pending. |
| `decided_by_key` | `dict[str, Any] | None` | The key whose code decided (`key_id`, `key_name`); None otherwise. |
| `note` | `str | None` | What whoever decided wrote with it. |

### Approval.from_id

```python
noclick.Approval.from_id(approval_id, *, client=None) -> Approval
```

A lazy reference to an approval by its id (an `noclick.ApprovalRequired`'s `approval_id`).

Parameters:

- `approval_id` (`str`, required)
- `client` (`Client | None`, default `None`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: `Approval` The approval; it loads the first time it's used.

Usage:

```python
approval = noclick.Approval.from_id(held.approval_id)
print(approval.status, approval.action, approval.price)
```

### Approval.list

```python
noclick.Approval.list(
    *, status=None, limit=None, user=..., client=None
) -> list[Approval]
```

Calls held for your account's owner's yes, newest first: the first 20, or the first `limit` (at
most 100), with `status` one of `pending`, `approved`, `declined`, `expired`, `used` or
`canceled`. Acting for a user, that user's alone.

Parameters:

- `status` (`str | None`, default `None`)
- `limit` (`int | None`, default `None`): Return at most this many.
- `user` (`Any`, default: the current user): Who the call acts for. Defaults to the user set by `noclick.as_user` (none: the account itself).
- `client` (`Client | None`, default `None`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: `list[Approval]` Each approval as its page shows it.

Usage:

```python
for approval in noclick.Approval.list(status="pending"):
    print(approval.action, approval.connection["name"], approval.expires_at)
```

### Approval.approve

```python
approval.approve(*, note=None) -> Approval
```

Approve it from your own code, with one of your account's secret keys that names the
`approvals:answer` scope; NoClick then runs the call itself, once, exactly as it was held. Refused
with `noclick.PermissionDenied` for the key the call was made with, a call whose terms a person
accepts, one needing a scope the key lacks or only the owner makes, a key acting for a user, and a key
without the scope; with `noclick.SpendCapExceeded` when its price, beside what the key spent and
approved this month, is past the key's own monthly cap.

Parameters:

- `note` (`str | None`, default `None`)

Returns: `Approval` This approval, answered: `status` is `approved`, then `used` once the call ran;
`decided_by` is `code`.

Usage:

```python
approval = noclick.Approval.from_id(held.approval_id)
approval.approve(note="Within this week's budget.")
noclick.Operation.from_id(approval.operation_id).wait()
```

### Approval.decline

```python
approval.decline(*, note=None) -> Approval
```

Decline it from your own code, as `approve` answers it: the call never runs, and whoever made it
is told why, with your `note`. A call whose terms a person accepts may be declined from code too.

Parameters:

- `note` (`str | None`, default `None`)

Returns: `Approval` This approval, answered: `status` is `declined`.

Usage:

```python
for approval in noclick.Approval.list(status="pending"):
    if approval.impact:
        approval.decline(note="Deletions wait for Monday's review.")
```
