Token Refresh
The canonical reference for OAuth token refresh — webhook-autonomous by default, notify hints, and the narrow opt-in TV-mediated path for built-in providers.
OAuth tokens expire; agents should never notice. This page is the single home for how refresh works — other pages link here instead of re-explaining it.
Custody rule first: by default, no credential material crosses Token Vault during refresh. There is exactly one narrow, opt-in exception, documented last.
Notify-only refresh (/v1/refresh-notify) — default
- Token Vault detects a token approaching expiry (or an agent actively waiting on one — the request carries
urgent: trueso your webhook can prioritize). - It notifies your webhook with provider hints (token URL, client ID — never a secret).
- Your webhook reads the refresh token from its own storage, calls the OAuth provider using its own client credentials, and stores the new tokens back.
Token Vault never sees any credential material. This is the path for any provider where you configured the OAuth app yourself.
Webhook-autonomous refresh
Your webhook can also ignore the notification schedule entirely and manage refresh on its own timer — the notification is a hint, not a command. Same custody properties as notify-only.
TV-mediated refresh (/v1/refresh) — opt-in exception
For Token Vault's built-in OAuth providers (Google, GitHub), where Token Vault owns the OAuth client_secret and your webhook has no credentials to refresh with, your webhook can opt in by advertising the tv-refresh capability at /v1/exchange:
- Phase 1 (
action: get) — Token Vault asks your webhook for the decrypted refresh token. - Token Vault calls the OAuth provider with its own
client_secret. - Phase 2 (
action: update) — Token Vault sends the fresh tokens back for your webhook to encrypt and store.
This is the only flow where Token Vault handles credential material — in transit only, never stored. Tokens expiring within 1 hour are refreshed automatically.
The killswitch applies here too
Revoke the tv-refresh capability (or take the webhook offline) and Token Vault has no credential path of any kind. The dashboard marks tokens using this flow with a blue TV Refresh badge; everything else shows green TV Zero.
Manual tokens
API keys and PATs added by hand have no refresh path — rotate them at the provider and update them in the dashboard (browser → webhook direct, as always).
Wire-level schemas for both endpoints: Webhook Endpoint Reference.
Ready to try it?
Sign up free with Google — your credentials stay on your own webhook, and the quickstart gets an agent fetching its first credential in about ten minutes.
MCP Proxy Endpoint
Reference for POST /api/proxy/mcp — proxy key auth forms, webhook credential injection, and the tv_session upstream auth type.
Agent Grants: Scoped, Time-Limited Credential Access
Create agent identities with tvagent_ API keys and grant them scoped, time-limited access to specific credentials — revocable instantly from the dashboard.