pywry.auth.session

OAuth2 session manager with automatic token refresh.

---

SessionManager

pywry.auth.session.SessionManager

SessionManager(provider: OAuthProvider, token_store: TokenStore, session_key: str = 'default', session_store: SessionStore | None = None, refresh_buffer_seconds: int = 60, on_reauth_required: Callable[[], None] | None = None)

Manages OAuth2 token lifecycle with automatic refresh.

PARAMETER	DESCRIPTION
provider	The OAuth2 provider for token refresh. TYPE: OAuthProvider
token_store	Store for persisting tokens. TYPE: TokenStore
session_key	Key used to identify stored tokens (e.g., user ID). TYPE: str DEFAULT: 'default'
session_store	Session store for internal session management. TYPE: SessionStore DEFAULT: None
refresh_buffer_seconds	Seconds before token expiry to trigger refresh (default 60). TYPE: int DEFAULT: 60
on_reauth_required	Callback invoked when refresh fails and re-authentication is needed. Signature: on_reauth_required() -> None. TYPE: callable DEFAULT: None

Initialize the session manager.

Functions

initialize async

initialize() -> OAuthTokenSet | None

Load existing tokens from store and validate.

RETURNS	DESCRIPTION
OAuthTokenSet or None	The stored tokens if valid, or None if no tokens are stored or they have expired.

save_tokens async

save_tokens(tokens: OAuthTokenSet) -> None

Persist tokens and schedule background refresh.

PARAMETER	DESCRIPTION
tokens	The token set to save. TYPE: OAuthTokenSet

get_access_token async

get_access_token() -> str

Get a valid access token, refreshing if near expiry.

RETURNS	DESCRIPTION
str	A valid access token.

RAISES	DESCRIPTION
TokenExpiredError	If the token is expired and cannot be refreshed.

refresh async

refresh() -> OAuthTokenSet

Refresh the access token.

Uses the stored refresh token to obtain a new access token. Falls back to on_reauth_required if refresh fails.

RETURNS	DESCRIPTION
OAuthTokenSet	A new token set.

RAISES	DESCRIPTION
TokenRefreshError	If refresh fails and no re-auth callback is set.

logout async

logout() -> None

Clear all tokens and cancel scheduled refresh.

Optionally revokes the token at the provider.