StreamlitAuth class

Handles SweatStack authentication and provides UI components for Streamlit apps.

This class manages OAuth2 authentication flow for Streamlit applications and provides convenient selector components for activities, sports, tags, and metrics. Once authenticated, the client property provides access to the SweatStack API.

Example

import streamlit as st from sweatstack.streamlit import StreamlitAuth

Initialize authentication

auth = StreamlitAuth( client_id="YOUR_APPLICATION_ID", client_secret="YOUR_APPLICATION_SECRET", redirect_uri="http://localhost:8501", )

Add authentication to sidebar

with st.sidebar: auth.authenticate()

Check authentication

if not auth.is_authenticated(): st.write("Please log in to continue") st.stop()

Use the authenticated client

st.write("Welcome to SweatStack") latest_activity = auth.client.get_latest_activity() st.write(f"Latest activity: {latest_activity.sport} on {latest_activity.start}")

Switch between accessible users (admin feature)

with st.sidebar: auth.select_user()

Attributes:

Name	Type	Description
client		The SweatStack Client instance for API access.
api_key		The current API access token.

__init__(client_id=None, client_secret=None, scopes=None, redirect_uri=None)

Initialize the StreamlitAuth component.

Parameters:

Name	Type	Description	Default
client_id		OAuth2 client ID. Falls back to SWEATSTACK_CLIENT_ID env var.	None
client_secret		OAuth2 client secret. Falls back to SWEATSTACK_CLIENT_SECRET env var.	None
scopes	List[Union[str, Scope]]	OAuth2 scopes. Falls back to SWEATSTACK_SCOPES env var. Defaults to data:read, profile.	None
redirect_uri		OAuth2 redirect URI. Falls back to SWEATSTACK_REDIRECT_URI env var.	None

authenticate(login_label=None, show_logout=True)

Authenticates the user with SweatStack.

This method handles the authentication flow for SweatStack in a Streamlit app. It checks if the user is already authenticated, and if not, displays a login button. If the user is authenticated, it displays a logout button.

When the user clicks the login button, they are redirected to the SweatStack authorization page. After successful authorization, they are redirected back to the Streamlit app with an authorization code, which is exchanged for an access token.

In proxy mode, this method only shows the login button if not authenticated. The proxy handles the OAuth callback and token exchange.

Parameters:

Name	Type	Description	Default
login_label	str | None	The label to display on the login button. Defaults to "Login with SweatStack".	None

Returns:

Type	Description
	None

behind_proxy(redirect_uri, header_name='X-SweatStack-Token', logout_uri='/logout') classmethod

Create a StreamlitAuth instance for use behind a proxy.

Use this method when your Streamlit app runs behind a proxy that handles authentication and passes the SweatStack access token via an HTTP header.

Parameters:

Name	Type	Description	Default
redirect_uri	str	The URI to redirect to after login (used by proxy).	required
header_name	str	The HTTP header name containing the access token. Defaults to "X-SweatStack-Token".	'X-SweatStack-Token'
logout_uri	str	The URI to redirect to for logout. Defaults to "/logout".	'/logout'

Returns:

Name	Type	Description
StreamlitAuth	StreamlitAuth	An instance configured for proxy mode.

Example

auth = StreamlitAuth.behind_proxy( redirect_uri="https://myapp.example.com/app", )

if not auth.is_authenticated(): st.error("Missing authentication header") st.stop()

activities = auth.client.get_activities()

get_authorization_url()

Generates the OAuth2 authorization URL for SweatStack.

This method constructs the URL users will be redirected to for OAuth2 authorization. It includes the client ID, redirect URI, scopes, and other OAuth2 parameters.

Returns:

Name	Type	Description
str		The complete authorization URL.

is_authenticated()

Checks if the user is currently authenticated with SweatStack.

This method determines if the user has a valid API key stored in the session state or in the instance. It does not verify if the API key is still valid with the server.

Returns:

Name	Type	Description
bool		True if the user has an API key, False otherwise.

logout_button()

Displays a logout button and handles user logout.

In standard mode, clears the stored API key from session state, resets the client, and triggers a Streamlit rerun.

In proxy mode, displays a styled link that redirects to the logout URI.

select_activity(*, start=None, end=None, sports=None, tags=None, limit=100)

Select an activity from the user's activities.

This method retrieves activities based on specified filters and displays them in a dropdown for selection.

Parameters:

Name	Type	Description	Default
start	date | None	Optional start date to filter activities.	None
end	date | None	Optional end date to filter activities.	None
sports	list[Sport] | None	Optional list of sports to filter activities by.	None
tags	list[str] | None	Optional list of tags to filter activities by.	None
limit	int | None	Maximum number of activities to retrieve. Defaults to 100.	100

Returns:

Type	Description
	The selected activity object.

Note

Activities are displayed in the format "YYYY-MM-DD sport_name".

select_metric(allow_multiple=False)

Select a metric from the available metrics.

This method displays metrics in a dropdown or multiselect for selection.

Parameters:

Name	Type	Description	Default
allow_multiple	bool	If True, allows selecting multiple metrics. Defaults to False.	False

Returns:

Type	Description
	Metric or list[Metric]: The selected metric or list of metrics, depending on allow_multiple.

select_sport(only_root=False, allow_multiple=False, only_available=True)

Select a sport from the available sports.

This method retrieves sports and displays them in a dropdown or multiselect for selection.

Parameters:

Name	Type	Description	Default
only_root	bool	If True, only returns root sports without parents. Defaults to False.	False
allow_multiple	bool	If True, allows selecting multiple sports. Defaults to False.	False
only_available	bool	If True, only shows sports available to the user. If False, shows all sports defined in the Sport enum. Defaults to True.	True

Returns:

Type	Description
	Sport or list[Sport]: The selected sport or list of sports, depending on allow_multiple.

Note

Sports are displayed in a human-readable format using the display_name function.

select_tag(allow_multiple=False)

Select a tag from the available tags.

This method retrieves tags and displays them in a dropdown or multiselect for selection.

Parameters:

Name	Type	Description	Default
allow_multiple	bool	If True, allows selecting multiple tags. Defaults to False.	False

Returns:

Type	Description
	str or list[str]: The selected tag or list of tags, depending on allow_multiple.

Note

Empty tags are displayed as "-" in the dropdown.

select_user()

Displays a user selection dropdown and switches the client to the selected user.

This method retrieves a list of users accessible to the current user and displays them in a dropdown. When a user is selected, the client is switched to operate on behalf of that user. The method first switches back to the principal user to ensure the full list of available users is displayed.

Returns:

Name	Type	Description
UserSummary		The selected user object.

Note

This method requires the user to have appropriate permissions to access other users. For regular users, this typically only shows their own user information.

switch_to_principal_user()

Switches the client back to the principal user.

This method reverts the client's authentication from a delegated user back to the principal user. The client will use the principal token for all subsequent API calls and updates the session state with the new API key.

Returns:

Type	Description
	None

Raises:

Type	Description
HTTPStatusError	If the principal token request fails.