Skip to content

Document automatic upstream token refresh behavior #607

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jhrozek merged 1 commit into from
Mar 12, 2026
Merged

Document automatic upstream token refresh behavior #607

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions docs/toolhive/concepts/backend-auth.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -269,6 +269,17 @@ This mechanism allows MCP servers to call external APIs with the user's actual
credentials from the upstream provider, while the client only needs to manage a
single ToolHive-issued JWT.

#### Automatic token refresh

Upstream access tokens have their own expiration, independent of the ToolHive
JWT lifespan. When the stored upstream access token has expired, ToolHive
automatically refreshes it using the stored refresh token before forwarding the
request — your MCP session continues without re-authentication.

If the refresh token is also expired or has been revoked by the upstream
provider, ToolHive returns a `401` response, prompting you to re-authenticate
through the OAuth flow.

:::warning[Session storage limitations]

By default, session storage is in-memory only. Upstream tokens are lost when
Expand Down