🚧 Roadmap — The capability described here is on the roadmap. The concepts and design are settled; interfaces and steps are subject to the final release.
Let an agent reach third-party services for a user
By the end of this guide you will know:
- How an agent gets to use a user's third-party services (mail, calendar, chat, storage) while never holding the user's credentials
- What "custody for credentials, dispatch for tokens" looks like as a sequence of steps
- What happens after a user disconnects an account
Prerequisites
- You understand the mechanics of Token Dispatcher
- You can already issue delegate tokens (see Quickstart)
- You know which third-party services the agent needs and the minimum scopes required
Four stages
Stage 1 · Connect: the user brings an account in
The user clicks "connect my mailbox" in your application and goes through that third party's standard authorization flow (OAuth 2.1 authorization code + PKCE). You declare the scope requested — this is the first gate: if you ask for read/write on all mail here, you can never take it back later.
Once authorization completes, the credential returned by the third party enters custody. Your application never receives the credential itself — you get a connection record: which user, which service, connection status, granted scope.
Stage 2 · Authorize: the user lets an agent use that connection
A connection existing does not mean an agent can use it. For that, the user grants one delegation stating "this agent may use my connected mailbox, read-only".
Keeping the two layers separate pays off: a user can connect an account for their own use first and decide later whether an agent may use it too; revoking an agent's delegation leaves the connection intact.
Stage 3 · Dispatch: the agent asks every time it needs access
When the agent needs access, it presents its delegate token to the custody layer and requests an access token for the scope it needs. The custody layer runs the dispatch checks:
| Check | Outcome if it fails |
|---|---|
| The delegate token is valid and unexpired | Dispatch refused |
| The delegator is the owner of this connection | Dispatch refused (prevents using A's delegation to reach B's account) |
| Requested scope ⊆ delegated scope ∩ the connection's granted scope | Refused, or only the intersection is dispatched |
If the checks pass, a short-lived, attenuated access token is dispatched and recorded in the audit chain. The agent uses it to call the third-party service.
Stage 4 · Expiry: it lapses or gets recalled
The access token expires on schedule; the agent must request again to continue — which means every single use passes through a fresh check, rather than one authorization granting indefinite passage.
Three recall paths:
- The user revokes the agent's delegation → subsequent requests are refused; the connection itself remains
- The user disconnects the account → all dispatch against that connection stops immediately and the credential in custody is cleared per policy
- An administrator trips the agent's kill switch → all dispatch for that agent stops (see Revocation and incident response)
Design guidance
Narrow the scope in two places. What you request from the third party at connect time sets the ceiling; what you grant the agent at delegation time sets the actual value. If the ceiling is too high, the user's account is already over-exposed to the custody layer even when the delegation is narrow — request minimally from the connect step onward.
Create separate connections for separate purposes. If "personal assistant, read-only" and "marketing tool, read-write" share one connection on the same service for the same user, you can only request the wider of the two. Separate connections, each minimal.
Never put a token in logs or prompts. A dispatched access token is short-lived, but it is still a credential. Log the audit_id and the connection ID, never the token itself.
FAQ
Can the agent see the user's password or refresh token? No. What an agent receives is always only the dispatched short-lived access token. The original credential stays inside the custody layer and is returned neither to the agent nor to your application.
What if the user changes their third-party password? The credential in custody may become invalid. Dispatch then fails and you should guide the user to reconnect.
Can several agents share one connection? Yes. A connection belongs to the user; a delegation belongs to the "user × agent" pair. Each agent requests separately, is bounded separately, and enters the audit chain separately.
Next steps
- Token Dispatcher — the mechanics and the three usage archetypes.
- Agents reaching third-party SaaS — the scenario view.
- Audit and accountability chain — how dispatch events join the chain.