Overview
A mock token is a string an agent fills in place of a real value. Agent Vault’s proxy replaces it with the real value inside its own browser, at the moment of filling. Outside the proxy it is just text.Token shapes
Card expiry is never a token. Fill the real
expiryMonth and expiryYear from
the catalog. Like the brand and last four digits, the expiry is not sensitive.
Where each kind resolves
An authorized destination is a site the account holder approved or added, a
login’s website, or a host on an active allowlist agent card. See
Destinations. Identity, address, card and security
code tokens check it on every fill, in addition to the agent card rules. On any
other site the fill pauses and asks the account holder. If they deny the site or
let the request expire, the fill is refused with
destination_unauthorized.
The rules travel with the token, not with the tool that fills it. A login token
filled through fill_checkout is checked exactly as if it were filled through
fill_login. See URL locking.
Tokens are stable
Tokens are derived from the account and the record, not issued per session.- They do not expire. Proxy sessions do.
- Rotating a password does not change its token.
- Enrolling 2FA does not change any of that login’s other tokens.
- A token you cached last week still works today, as long as the record and field behind it still exist.
token_not_found. So does an optional login field the account holder
removed: clearing a login’s email or username retires its tokens.email or
tokens.username, and removing its authenticator secret retires tokens.totp.
Each also drops out of the catalog. Fetch a fresh catalog after the account
holder edits a login, and whenever a fill returns token_not_found.
Renaming an address changes its tokens
An address token carries the address’s label, and the label is how the token is looked up. When the account holder changes an address’s label, every token for that address changes with it. A cachedav_addr_ship_street1_u7x2k returns
token_not_found once ship is renamed, and the catalog lists the new
av_addr_<new-label>_... tokens instead. Fetch a fresh catalog after any address
edit.
The other labelled kinds:
Tokens are inert outside the proxy
Type a token into a form through plain Playwright and the merchant receives the literal stringav_card_1_number_u7x2k. The checkout fails and nothing real is
exposed. That is why the catalog is safe to give an agent, and safe to appear in
its logs.
Split phone tokens
phone_area, phone_prefix and phone_line are views of the same stored number
as phone, for forms that ask for it in three boxes.
They resolve only for a ten-digit North American number. For any other number
they throw token_not_found, because the 3-3-4 shape does not exist elsewhere: a
UK area code is 2 to 5 digits and an Indian mobile has no area code at all.
For a number outside +1, use phone_country with phone_national, which resolve
for any country.
phone itself is the whole number in E.164 form, such as +15550100134, for a
phone saved with the current Country code and Number fields. An older
phone stored only as free text fills that text unchanged until the account
holder saves it again. See
Older phone numbers.
All five phone parts are newer than phone. A catalog from a deployment that
predates them has no such keys, so check before filling.
Card sequence numbers
Then in av_card_{n}_... comes from a per-account counter, minted for
uniqueness and display only. It never decides which rules apply: a card’s rules
are found through the card’s own record. Numbers are never reused, even after a
card is deleted.
If one mock card number matches several differently configured cards, the fill
is refused with
card_blocked. The result is the same on every attempt. Use a
different card, or ask the account holder to remove the duplicate.Refusals tied to the grammar
Full list: Error codes.