Connecting an agent
How the connect flow works under the hood — save an API key, mint a short-lived session token, and let the partner service verify it
Connecting an agent
When your agent uses a service on your behalf, it never sends your password or your long-lived key. Instead, three pieces cooperate: your key stays on your machine, your agent works with short-lived session tokens, and the partner service verifies each token with AgentOnboard. This page explains that mechanism so you can trust it.
The flow, end to end
You save an API key
You create an API key in your dashboard and save it once with aon save <your-api-key>. The CLI writes it to ~/.agentonboard/ on your machine. This is the only long-lived secret in the whole system, and it never leaves your machine.
Your agent mints a session token
Whenever your agent needs to call a partner service, it exchanges the saved key for a session token with aon token get. The token is valid for 5 minutes — long enough for the call, short enough that a leaked token is nearly useless.
Your agent calls the partner API
Your agent sends the session token in an x-session-token header on the request — the convention used by AgentOnboard's reference implementation. Check the partner's documentation for where their API expects it.
The partner verifies the token
The partner's API sends the token to POST /api/verify together with its own partner key. AgentOnboard answers with your AgentOnboard login email — or a structured error if the token is invalid or expired.
The partner serves your data
The partner looks up your account by email and serves your data — or rejects the request if the token could not be verified. You never interact with the partner's authentication system directly; your agent just works.
Why this is safe
Your long-lived key never leaves your machine
The key you save with aon save is used only to mint session tokens. It is never sent to a partner service, and no partner ever sees it. Even if a partner were compromised, they could not extract your key.
Session tokens are short-lived
Each session token expires after 5 minutes. If a token is intercepted or leaked, it stops working almost immediately — unlike a password or an API key, which stay valid until revoked.
Partners see only tokens, not you
A partner verifies a session token and gets back one thing: your email. That is all they need to serve you, and all they ever learn about your AgentOnboard setup.
Where the pieces live
| Piece | Where it happens | More |
|---|---|---|
| Save the key | Your machine, via aon save | Stored in ~/.agentonboard/ |
| Mint a token | Your machine, via aon token get | Valid for 5 minutes |
| Verify the token | AgentOnboard API, POST /api/verify | SDK & verify documents the contract |
| Map to your account | Partner's own database, by email | Email & identity explains the join key |