Skip to content

Authentication

How the Python SDK signs in as you, in a script, a notebook or a headless job. For apps where other people sign in, see Streamlit and FastAPI.

Sign in through the browser

In a script or notebook, call authenticate():

from sweatstack import Client

client = Client()
client.authenticate()

If the client finds no credentials, authenticate() opens your default browser for the SweatStack sign-in. The SDK then saves the tokens on your machine, and later runs use them without opening the browser. If credentials exist, authenticate() does nothing.

To sign in again, for example as another user, pass force=True:

from sweatstack import Client

client = Client()
client.authenticate(force=True)

The saved tokens live in a file only your user account can read, in the platform's data directory (~/Library/Application Support/SweatStack/ on macOS, ~/.local/share/SweatStack/ on Linux).

Use an API key

Create an API key at Settings → API. Treat it like a password.

A key acts only within the scopes you picked for it: it can't manage your apps or Pages, act as another user, or create another key. Those need your own sign-in.

Pass it to the client:

from sweatstack import Client

client = Client(api_key="your-api-key")

Or set it in the environment, and create the client without arguments:

export SWEATSTACK_API_KEY="your-api-key"

from sweatstack import Client

client = Client()  # reads SWEATSTACK_API_KEY

Run without a browser

On a server, in CI or in a container, set SWEATSTACK_API_KEY, and SWEATSTACK_REFRESH_TOKEN if the job outlives the access token. Don't call authenticate(). The SDK refreshes an expired access token with the refresh token and keeps the new one for the rest of the run. See Run scripts unattended.

Where the SDK looks for credentials

The access token and the refresh token always come from one source, the first of these that has either:

  1. The values passed to Client(api_key=..., refresh_token=...), or set by authenticate() in this process.
  2. The SWEATSTACK_API_KEY and SWEATSTACK_REFRESH_TOKEN environment variables.
  3. The tokens a browser sign-in saved on this machine.

The SDK never combines an access token from one source with a refresh token from another. A client given only an access token cannot renew it: when it expires, the next call raises SweatStackTokenRefreshError. Only tokens that came from the saved file are written back to it after a refresh.

If it finds none, a request fails with SweatStackAuthError.

Authenticate other people

An app that acts for other users signs them in through OAuth2 and OpenID Connect, and gets an access token per user. See OAuth2. The FastAPI and Streamlit helpers do this for you and give you a Client per signed-in user. For a custom flow, client.oauth has generate_pkce_params(), authorization_url() and exchange_code(); see the OAuth reference.

Use the client in a server

A server is shared by everyone who signs in, so nothing on its machine is a user's credential. Build one client per user from that user's own tokens, and tell it not to look elsewhere:

from sweatstack import Client

client = Client(
    api_key=session["access_token"],
    refresh_token=session["refresh_token"],
    ambient_credentials=False,
)

With ambient_credentials=False the client never reads the environment or the saved tokens and never writes them. Keep the tokens with the user's session, and store the new access token the client holds after a refresh (client.api_key) if the session outlives it. Never use a bare Client(), the module-level functions or authenticate() in a server: they look for credentials on the machine. The FastAPI and Streamlit helpers build their clients this way.

To act as another user you have access to, for example as a coach, see Clients.