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.

Parameters:

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

Initialize the session manager.

Functions

initialize async

initialize() -> OAuthTokenSet | None

Load existing tokens from store and validate.

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
tokens	OAuthTokenSet	The token set to save.	required

get_access_token async

get_access_token() -> str

Get a valid access token, refreshing if near expiry.

Returns:

Type	Description
str	A valid access token.

Raises:

Type	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:

Type	Description
OAuthTokenSet	A new token set.

Raises:

Type	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.