Authentication

OAuth2Handler

polar_flow.auth.OAuth2Handler

OAuth2 authorization flow handler for Polar AccessLink API.

This class handles the OAuth2 authorization code flow for obtaining access tokens from Polar AccessLink API.

Example

oauth = OAuth2Handler(
    client_id="your_client_id",
    client_secret="your_client_secret",
    redirect_uri="http://localhost:8000/callback"
)

# Step 1: Get authorization URL
auth_url = oauth.get_authorization_url()
# Redirect user to auth_url

# Step 2: Exchange authorization code for token
token = await oauth.exchange_code(code="authorization_code_from_callback")

# Step 3: Use token with PolarFlow client
async with PolarFlow(access_token=token.access_token) as client:
    ...

__init__(client_id, client_secret, redirect_uri=None)

Initialize OAuth2 handler.

Parameters:

Name	Type	Description	Default
client_id	str	OAuth2 client ID from Polar AccessLink admin	required
client_secret	str	OAuth2 client secret from Polar AccessLink admin	required
redirect_uri	str | None	Optional redirect URI (must match registration)	None

Raises:

Type	Description
ValueError	If client_id or client_secret is empty

exchange_code(code) async

Exchange authorization code for access token.

After the user authorizes your application, they will be redirected to your redirect_uri with a 'code' parameter. Use this method to exchange that code for an access token.

Parameters:

Name	Type	Description	Default
code	str	Authorization code from callback URL	required

Returns:

Type	Description
OAuth2Token	OAuth2Token containing access_token and user_id

Raises:

Type	Description
ValueError	If code is empty
AuthenticationError	If token exchange fails (invalid code, etc.)
PolarFlowError	If request fails

Example

# In your callback handler:
code = request.args.get("code")
token = await oauth.exchange_code(code)
# Store token.access_token for future API requests

get_authorization_url(state=None)

Generate authorization URL for user to visit.

The user should be redirected to this URL to authorize the application. After authorization, they will be redirected back to your redirect_uri with an authorization code.

Parameters:

Name	Type	Description	Default
state	str | None	Optional state parameter for CSRF protection. If not provided, a random state will be generated.	None

Returns:

Type	Description
str	Authorization URL to redirect the user to

Example

oauth = OAuth2Handler(...)
auth_url = oauth.get_authorization_url(state="random_string")
# Redirect user to auth_url

OAuth2Token

polar_flow.auth.OAuth2Token

Bases: BaseModel

OAuth2 access token response.

user_id property

Get the user ID as string.

Returns:

Type	Description
str	Polar user ID as string

load_token_from_file

polar_flow.auth.load_token_from_file(path=None)

Load access token from file.

Parameters:

Name	Type	Description	Default
path	Path | None	Token file path. Defaults to ~/.polar-flow/token	None

Returns:

Type	Description
str	Access token string

Raises:

Type	Description
FileNotFoundError	If token file doesn't exist
ValueError	If token file is empty or invalid

Example

from polar_flow.auth import load_token_from_file token = load_token_from_file() async with PolarFlow(access_token=token) as client: ... sleep = await client.sleep.list()