> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentvault.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Approvals and notifications
> Answer the requests that pause your agent, and choose how Agent Vault reaches you.
Answer the requests that pause your agent mid-checkout, and set up alerts so you
see them in time. Setting up alerts on your phone takes about 2 minutes.
## What can need you
Every request except an agent signup shows as a banner at the top of each
dashboard page, whatever your notification settings.
Email, desktop notifications and background alerts reach you only when that
channel is on and the request's switch under [Events](#events) is on.
The link in the email works without signing in. See
[Keep request links private](#keep-request-links-private).
| Request | Why it appears | Time to answer |
| - | - | - |
| [Purchase approval](#purchase-approvals) | A purchase is at or above the agent card's **Require confirmation above** amount, or its total could not be read | About 5 minutes |
| [New site](#new-site-approvals-and-destinations) | Your agent wants to use your saved details on a site for the first time | About 15 minutes |
| [Security code](#security-code-requests) | A checkout needs your card's security code (CVV), on a deployment with live security code entry | About 3 minutes |
| [Verification step](#verification-handoffs) | Your bank, a one-time code or a human check needs you | About 10 minutes |
| [Agent signup](/dashboard/logins#approve-an-agent-signup) | An agent asks to create an account for you. Answered on **Logins**, with no banner | 24 hours |
All but the agent signup expire within 15 minutes, so turn on
[Background alerts](#set-up-this-device) on your phone. Email and background
alerts reach you with no dashboard tab open. Desktop notifications do not.
## Purchase approvals
You see these when an agent card has **Require confirmation above** set. See
[Agent cards](/dashboard/agent-cards#require-approval-above-an-amount). You can
also see one on a card with spending limits and no threshold, when the page's
total is over a limit and your agent's is not: see
[When your agent and the page disagree on the total](#when-your-agent-and-the-page-disagree-on-the-total).
The banner reads **A purchase is waiting for your approval**. It names the
agent card, the site, the amount when known, and why it was held.
Use the banner, or the **Approval needed** page the email links to. That page
also shows a screenshot of the checkout with your details blacked out. A
screenshot larger than 768 KB is left out, and the request still appears
without it.
Your agent continues straight away if you approve.
| Why it was held | What you are deciding |
| - | - |
| Over your threshold | Whether to spend this much |
| The page's total is over a spending limit, but your agent's total is under half of it and fits | Which total is real |
| Total unknown, or in a currency that could not be converted | Whether to go ahead without a confirmed amount |
| Total reads as under your threshold but could not be confirmed | The same |
Agent Vault cannot prove an unreadable total is under your threshold, so it asks.
An agent card with no threshold asks only when your agent and the page disagree
on a total that is over a spending limit (below). If part of the order is paid
another way, such as a gift card, the request says so.
### When your agent and the page disagree on the total
Your agent can say what it expects to pay. When that differs from the total
Agent Vault read on the page, the request shows both, for example **Agent says
$9.00 ยท page reads $108.00**. Each is in its own currency.
When your agent's total is under half the page's, the page may have read the
wrong price, such as an annual price for a monthly plan. You then choose:
| Buttons | When | What approving does |
| - | - | - |
| **Approve at $9.00**, **Approve at $108.00**, **Deny** | The page's total is over your threshold | Approve at your agent's total to count $9.00 against your limits. Approve at the page's total to count $108.00 |
| **Approve at \$9.00**, **Deny** | The page's total is over a spending limit, and your agent's fits | Counts \$9.00 against your limits. The page's total is not offered, because the limit would refuse it |
Deny if the page's total is the real one. Approving at your agent's total covers
one fill on that site. If the page's total goes up before the card is filled,
or a limit is reached in the meantime, the fill is refused.
### After you decide
| You | What happens |
| - | - |
| Approve | The agent continues. If the total goes up, becomes unreadable or changes currency before the card is filled, or the checkout moves to another site, the fill is refused and a retry asks you again |
| Deny | Nothing is filled |
| Do nothing | The request expires after about 5 minutes. Nothing is filled, and a retry asks you again |
Once settled, the page shows **Approved**, **Denied**, **Request expired** or
**Request timed out**.
## New-site approvals and destinations
Your card, security code, identity and addresses fill only on your
[destinations](/dashboard/destinations). The first time your agent tries a new
site, the banner reads **A new site is waiting for your approval**. You have
about 15 minutes to click **Approve** or **Deny**.
If the same checkout runs on other sites and its recipe has been checked by a
person, one approval covers all of them. Otherwise each site asks you
separately. See
[When one checkout runs on several sites](/dashboard/destinations#when-one-checkout-runs-on-several-sites).
## Security code requests
Agent Vault never stores your card's security code, so a checkout that asks for
it needs you.
Not every deployment supports live security code entry. On a deployment
without it, a checkout that needs the code fails at once with
`cvv_entry_required`. No request, banner, email or entry page is created, and
nothing you do can supply the code. See [CVV policy](/security/cvv-policy).
The banner reads **Your agent needs your card security code**. Click **Enter
security code**, or open the emailed link.
On the **Enter your security code** page, type it into **Security code
(CVV)**. It takes 3 or 4 digits. Anything else shows **Enter the 3- or
4-digit security code from your card.**
The page shows **Security code received**.
The code goes straight to the checkout, is used once and is never stored. Your
agent never sees it.
The link works only while the checkout waits: about 3 minutes, or less if
Agent Vault restarts. After that, opening it shows **Request expired**, and a
code sent from a page already open is refused with **This request was already
used or has expired.** Nothing reaches the checkout. Ask your agent to retry for
a new link. More:
[Live CVV entry](/guides/live-cvv).
## Verification handoffs
Your agent hands you the live checkout when it reaches your bank's check (3-D
Secure), a one-time code or a CAPTCHA.
The banner names the step, for example **Your bank needs to verify a
payment**. Click **Open live checkout**, or open the emailed link.
Click the live page and type as usual, or approve the payment in your banking
app.
Click **I'm done** to let your agent continue, or **I couldn't complete
this** to stop.
Your agent is paused and cannot see what you type. If nothing was filled from
your vault before the handoff, screenshots afterwards are not blacked out, so
your agent is told not to take any.
If you leave and come back, the banner button reads **Resume checkout**. More: [Handling challenges](/guides/challenges).
## Notification settings
In the sidebar, under **Account**, click **Settings**.
| Channel | Reaches you | Default |
| - | - | - |
| Dashboard banner | While a dashboard tab is open | Always on |
| **Email notifications** | Your account email, one email per event | On |
| **Desktop notifications** | While the dashboard is open in a tab | Off |
| **Background alerts** | Even with no dashboard tab open | Off |
The banner is built from the waiting request itself, so it appears even if
every other channel fails. Email, desktop notifications and background alerts
are best effort. An email that asks you to act is retried a few times if sending
fails; other sends are not retried. Do not rely on a single channel.
### Set up this device
Use the browser you normally use.
Under **This device**. Allow notifications when the browser asks.
Each browser is set up on its own.
You can have up to 20 devices set up for **Background alerts**. Turning it on in
a 21st browser still succeeds, and silently removes the device you set up
longest ago, which stops getting alerts. The dashboard has no list of your
devices. To check a device, open **Settings** in that browser. The
**Background alerts** switch is on only while that browser is still set up. If
the switch is off, turn it on again.
Your phone now gets an alert for every request that needs you (purchase and
new-site approvals, security codes, verification steps) and for three security
events: an agent is auto-paused, an API key is revoked, and an agent stores a
new authenticator secret. Each one arrives only while its switch under
[Events](#events) is on.
If your device is offline, the browser's push service holds the alert for at
most 10 minutes, then drops it. A request can still be waiting after that, so
check the dashboard banner when you come back online.
On iPhone and iPad, add the site to your home screen first (**Share**, then
**Add to Home Screen**) and open the dashboard from there. If your browser blocks
notifications for the site, allow them in its site settings.
### Events
Each switch controls one event across every channel you have turned on. With
a switch off, no channel sends that event, even a channel that is on.
**Background alerts** carry only the events listed under
[Set up this device](#set-up-this-device). Turning on a switch for any other
event does not send it to your phone.
These switches do not change what an agent card's
[webhook](/dashboard/agent-cards#notification-webhook) receives.
| Group | Switch | Default |
| - | - | - |
| **Needs you** | **A purchase needs my approval** (also new sites) | On |
| **Needs you** | **A checkout needs my card security code** | On |
| **Needs you** | **A checkout needs me to clear a bank or verification step** | On |
| **Spending** | **A transaction is declined** | On |
| **Spending** | **A spending limit is hit** | On |
| **Spending** | **An agent is auto-paused** | On |
| **Spending** | **Every card fill** | Off |
| **Security** | **My agent's traffic didn't use my connection** | On |
| **Security** | **Which residential exit my agent's session used** | Off. The **Residential exit** row on **Activity** is recorded either way; this switch only adds the email and desktop alerts |
| **Security** | **My agent creates or changes a login** | On |
| **Security** | **My agent hits a rate or session limit** | On. Sent at most once an hour for each kind of limit, however often the agent hits it |
| **Security** | **An agent connects for the first time** | On |
| **Security** | **An API key is revoked** | On |
| **Security** | **An agent stores a new authenticator secret** | On |
Keep the three **Needs you** switches on. With one off, a checkout that needs you
can expire before you notice.
If you set up a [tunnel](/sdk/tunnel) so sites see your own internet connection,
this tells you some of a session's traffic went out through Agent Vault's address
instead. HTTPS traffic stays encrypted either way. If any of that traffic used plain
HTTP, the alert says it was readable along the way. If it was all HTTPS, the
alert says everything stayed encrypted. It is sent at most once per session.
When it lists sites, it names up to three and counts the rest. Agent Vault
stops counting at 100 sites per session. For plain HTTP sites it does not flag
that it stopped, so if the alert reports 100 plain HTTP sites, the real number
may be higher. See
[Ceilings](/reference/limits#ceilings).
Where Agent Vault sends sessions out through a residential connection instead of
your own, each session that reached a site ends with one record of which exit it
used: the country, how much it sent and received, and whether the provider
stopped carrying it before it ended. It never names an IP address, because
Agent Vault never learns it. Nothing is wrong when you see it:
the session went out the way it was meant to.
The record always appears on [**Activity**](/dashboard/activity) as
**Residential exit**. Turn this switch on only if you also want an email and a
desktop notification for every such session. It is never sent as a
**Background alerts** notification. See
[Residential egress](/sdk/tunnel#residential-egress).
## Keep request links private
Each emailed link carries a one-time token. Anyone with the link can act on that
one request, which is what lets you approve from your phone without signing in.
Do not forward these emails.
Links are short-lived and work for one request only. If you delete your account,
every pending request is removed and its link stops working.
## For developers
| Switch group | Event types |
| - | - |
| Needs you | `approval_required`, `cvv_required`, `challenge_required` |
| Spending | `denied_fill`, `limit_threshold`, `auto_pause`, `card_fill` |
| Security | `untunneled_egress`, `egress_used`, `agent_login_change`, `agent_throttled`, `key_first_use`, `key_revoked`, `totp_enrolled` |
Approval outcomes reach your agent as `approval_denied` or `approval_timeout`. See
[Error codes](/sdk/error-codes) and [Webhooks](/reference/webhooks).
**Next:** [Activity](/dashboard/activity) to see recorded events, including the ones you were emailed about.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.