OAuth2/OpenID

Info

For local development, you can generate API keys directly, or authenticate using the Python client library.

In a hurry and/or familiar with OAuth2? Here is a quick step-by-step guide:

1. Create an application - Create the application here.
2. Client ID - The Application ID shown after saving is your OAuth 2 client id.
3. Scopes – Request any mix of data:read, data:write, and profile.
4. Authorization endpoint - https://app.sweatstack.no/oauth/authorize?client_id={client_id}&redirect_uri={redirect_uri}&scope={comma_separated_scopes}&response_type=code
5. Token endpoint – Exchange codes or refresh tokens at POST https://app.sweatstack.no/oauth/token
6. Authenticated calls – Include the access token on every request in the headers: Authorization: Bearer {access_token}

Why OAuth2?

OAuth2 solves two distinct problems:

1. Delegated access — a user can let your app call our API without sharing their password.
2. Scoped tokens — the access you obtain is limited in time (expires) and scope (e.g., only data:read instead of data:write).

The core idea is a dance in which your application, you (the developer), and the end‑user’s browser exchange short‑lived codes and long‑lived tokens so each party only sees what it absolutely needs.

The OAuth2 specification defines a number of different flows. SweatStack supports several flows. Which flow you choose depends on your application type.

Flow	Best for
Authorization Code	Server‑side apps
Authorization Code + PKCE	Browser‑based apps and mobile apps

If you are unsure, pick Authorization Code + PKCE. It’s the modern default, very secure and works (almost) everywhere.

1 — Create an Application

1. Sign up or sign in if you haven't already. Any user can create applications.
2. In the menu bar at the top, go to Settings → API → Create Application or go there directly.
3. Fill:
   • Name - Shown on the consent screen
   • Description - Shown on the consent screen
   • URL - The URL of your application where users can find out more about it
   • Image URL - URL to an image that will be shown on the consent screen
   • Redirect URIs - Where we’ll send the user back (HTTPS, partial URIs are allowed)
   • Privacy Statement/Policy URL - A URL to your privacy statement or policy
   • Published - Published applications are visible at https://app.sweatstack.no/apps. Apps can still iniate the OAuth2 flow even if they are not published.
4. Press Create Application
5. The Application ID show at the top is your OAuth2 client ID.

Optional: If you will be using the Authorization Code (without PKCE) flow, you will need to generate a secret:

1. In the Secrets section at the bottom, fill out a label for the secret and click Create new secret.
2. Copy the secret and store it in a secure location. The Secret is your OAuth2 client secret. Your can create as many secrets as you want and revoke them at any time.

Warning

Treat the secret like a password: Never put it in mobile or SPA code or any other place that is accessible by users.

2 — Authorize the User

Determine the scopes your app needs

SweatStack supports the following scopes:

• data:read - Read access to user data
• data:write - Write access to user data. Also allows deleting data. Does not allow reading data.
• openid - openid specific scope. Not used by SweatStack at the moment.
• profile - Access to profile information.

Build the authorization URL

Authorization Code + PKCEAuthorization Code

With PKCE, you need to generate a code verifier and code challenge:

1. Generate a random code verifier (between 43-128 characters)
2. Create a code challenge by hashing the verifier with SHA-256 and base64url encoding it

Store the code verifier securely - you'll need it later in the OAuth2 flow when exchanging the authorization code for tokens.

GET https://app.sweatstack.no/oauth/authorize
    ?response_type=code
    &client_id={client_id}
    &redirect_uri={redirect_uri}
    &scope={comma_separated_scopes}
    &state={optional_state}
    &code_challenge={code_challenge}
    &code_challenge_method=S256

The authorization URL will look like this:

https://app.sweatstack.no/oauth/authorize?response_type=code&client_id=abcd1234&redirect_uri=https://your-awesome-app.com/oauth-callback&scope=data:read&code_challenge=1234567890&code_challenge_method=S256

GET https://app.sweatstack.no/oauth/authorize
    ?response_type=code
    &client_id={client_id}
    &redirect_uri={redirect_uri}
    &scope={comma_separated_scopes}
    &state={optional_state}

The authorization URL will look like this:

https://app.sweatstack.no/oauth/authorize?response_type=code&client_id=abcd1234&redirect_uri=https://your-awesome-app.com/oauth-callback&scope=data:read

Now redirect or pop‑up the user to that URL. They log in, grant access, and we redirect them back.

3 - Receive the Callback and Exchange for Tokens

Authorization Code + PKCEAuthorization Code

The redirect will look like this:

https://your-awesome-app.com/oauth-callback?code={authorization_code}&state={optional_state}

Use the code together with the code_verifier that you generated earlier to exchange for tokens.

POST https://app.sweatstack.no/oauth/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=authorization_code" \
    -d "code={authorization_code}" \
    -d "client_id={client_id}" \
    -d "code_verifier={code_verifier}"

The redirect will look like this:

https://your-awesome-app.com/oauth-callback?code={authorization_code}&state={optional_state}

Use the code together with the client secret to exchange for tokens.

POST https://app.sweatstack.no/oauth/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "client_id={client_id}" \
    -d "client_secret={client_secret}" \
    -d "grant_type=authorization_code" \
    -d "code={authorization_code}" \

The response will look like this:

{
  "access_token": "eyJhbGciOi…",
  "expires_in": 3600,
  "refresh_token": "def50200…",
  "scope": "data:read",
  "token_type": "Bearer"
}

Store the access_token and refresh_token in a secure location.

4 — Refresh the Access Token

Access tokens expire after some time. When the access token expires and the user has not withdrawn consent, you can refresh it by exchanging the refresh token for a new access token.

Authorization Code + PKCEAuthorization Code

POST https://app.sweatstack.no/oauth/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "grant_type=refresh_token" \
    -d "refresh_token={refresh_token}" \
    -d "client_id={client_id}" \

POST https://app.sweatstack.no/oauth/token \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -d "client_id={client_id}" \
    -d "client_secret={client_secret}" \
    -d "grant_type=refresh_token" \
    -d "refresh_token={refresh_token}" \

SweatStack will return a shiny new access token, similar to the one you got when you first authorized the user.

Example response:

{
  "access_token": "eyJhbGciOi…",
  "expires_in": 3600,
  "refresh_token": "def50200…",
  "scope": "data:read",
  "token_type": "Bearer"
}

5 — Authenticate API Requests

To authenticate API requests to SweatStack, add the access token as a Bearer authorization header:

GET https://api.sweatstack.no/api/v1/activities/ \
     -H "Authorization: Bearer {access_token}"

OAuth2/OpenID Client Libraries

Although it is very well possible to implement the OAuth2 flow manually, it is recommended to use a client library. Some client libraries can use "well-known endpoints" to make setup easier. You can find the documentation for these here.

Next Steps

• Python client library - SweatStack has a Python client library that makes it easy to integrate with the SweatStack API. You can get started with it here.
• API documentation - The SweatStack API is documented here.

Got stuck? You can contact me at [email protected].

Happy building! 🚀