vendo.tokenFor() sits one long-lived secret: your service key. It stays
on your backend, your agent never sees it, and every call trades it for a token
that lasts ten minutes. This page is what happens behind that one call.
Where the key lives
You never create this key or paste it anywhere. On Vendo Cloud, the first time anything reaches your door, Cloud mints one for your tenant — which is why init never asks. For a local dev door, init generates one itself and writesVENDO_SERVICE_KEY into .env.local. The console is where you see the Cloud
one, rotate it, or revoke it.
Your agent only ever gets the ten-minute token, never the key, and tokenFor is
the only line of your own code that touches either one.
Who the audit says acted
Every call the token makes is recorded under two names: the user it acts as, and the key that asked for it. The key shows up as a short fingerprint —svc:5c006a4c, say — so an audit row
can tell you which key acted without the key itself ever landing in it.
To your policy this is that user, not an agent: a write still parks for
approval, and the approval names the tool and the person.
Rotating a key
Rotating never cuts anything off mid-flight. Create the replacement in the console, restart your backend so it picks the new one up — the SDK fetches the key itself, there is nothing to copy — then delete the old one. Tokens the old key already handed out keep working for up to ten minutes.When the mint refuses
Three of these come from the exchange; the last shows up later and gets misread.invalid_client is vague on purpose: anything more specific would tell whoever
is guessing which half of the credential they got right.
The 401 looks like a key problem and isn’t. The exchange never checks that the
user id is real, so a token for a stranger mints happily and dies on the first
request, when the door asks your app who that is and gets nobody back.
The broker
The broker is the piece that hands out the tokens, and on Vendo Cloud you don’t run it —VENDO_API_KEY is the whole setup. It asks one thing of you:
VENDO_BASE_URL has to be an https:// origin. Only the sign-in page needs to
be reachable from a browser — tokenFor dials out from your backend, so nothing
has to reach in.
Handing your own agent a bearer is one call:
app/api/agent-token/route.ts