OAuth authorization

Partner apps use the OAuth Authorization Code flow with PKCE, following OAuth 2.1 security practices. The app is a confidential client: use PKCE for every authorization and authenticate token and revocation requests with HTTP Basic. The authorization server is https://oauth.subtotal.com. Its current endpoints and capabilities are published at:

https://oauth.subtotal.com/.well-known/oauth-authorization-server

Purpose	Endpoint	Authentication
Start authorization	`GET /oauth/authorize`	Top-level browser navigation; no HTTP credentials
Exchange or refresh tokens	`POST /oauth/token`	HTTP Basic with the Client ID and client secret
Identify an installation	`GET /oauth/me`	Bearer access token
Revoke an installation	`POST /oauth/revoke`	HTTP Basic with the Client ID and client secret

1. Request authorization

Generate a high-entropy state value and an RFC 7636 PKCE verifier for each attempt. Save both in a short-lived, server-side install session.

import { createHash, randomBytes } from "node:crypto";

const base64url = (value) =>
  value.toString("base64url");

const state = base64url(randomBytes(32));
const codeVerifier = base64url(randomBytes(64));
const codeChallenge = base64url(
  createHash("sha256").update(codeVerifier).digest()
);

Redirect the user agent with a top-level browser navigation. Do not embed Subtotal authorization in an iframe.

GET https://oauth.subtotal.com/oauth/authorize
  ?response_type=code
  &client_id=YOUR_OAUTH_CLIENT_ID
  &redirect_uri=https%3A%2F%2Fconnect.example.com%2Foauth%2Fsubtotal%2Fcallback
  &resource=https%3A%2F%2Fapi.subtotal.com
  &scope=connections%3Aread%20retailers%3Aread%20purchases%3Abrand_products
  &state=YOUR_RANDOM_STATE
  &code_challenge=YOUR_S256_CHALLENGE
  &code_challenge_method=S256

Query parameter	Required value or purpose
`response_type`	Required. Use `code`.
`client_id`	Required. The Client ID shown in Created Apps.
`redirect_uri`	Required. One of the app’s allow-listed redirect URIs. Matching is exact.
`resource`	Required. Use `https://api.subtotal.com` so the access token is valid for the Subtotal API.
`scope`	Optional. Omit to request the full set, or send `connections:read retailers:read purchases:brand_products` in any order, each exactly once.
`state`	Required. A high-entropy value unique to this authorization attempt. Validate it on return.
`code_challenge`	Required. The base64url-encoded SHA-256 digest of the PKCE verifier.
`code_challenge_method`	Required. Use `S256`.

If a user belongs to multiple dashboard teams, Subtotal asks them to choose which team will grant access. The token response’s subtotal_client_id identifies the selected team. Partner apps do not negotiate permissions. Requests for a subset, an additional scope, or a duplicated scope value are rejected.

2. Handle the callback

Subtotal redirects the browser to the allow-listed URI after the brand approves, denies, or encounters an authorization error.

https://connect.example.com/oauth/subtotal/callback
  ?code=AUTHORIZATION_CODE
  &state=YOUR_RANDOM_STATE

Query parameter	When present
`code`	Approval. A temporary authorization code that expires after 10 minutes and can be exchanged only once.
`state`	Every redirect. The original value from the authorization request.
`error`	Denial or authorization failure. An OAuth error code is returned instead of `code`.

Before exchanging the code:

If error is present, stop the flow and show an appropriate message.
Compare state to the value in the install session using a constant-time comparison.
Reject missing, expired, or mismatched state.
Load the corresponding PKCE verifier and delete the install session after use.

3. Exchange the authorization code

Call the token endpoint from your server. Supply the Client ID and client secret from Created Apps with HTTP Basic, and send form-encoded parameters.

curl --request POST https://oauth.subtotal.com/oauth/token \
  --user "$SUBTOTAL_OAUTH_CLIENT_ID:$SUBTOTAL_OAUTH_CLIENT_SECRET" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode "code=$AUTHORIZATION_CODE" \
  --data-urlencode 'redirect_uri=https://connect.example.com/oauth/subtotal/callback' \
  --data-urlencode "code_verifier=$PKCE_CODE_VERIFIER"

Form parameter	Required value or purpose
`grant_type`	Required. Use `authorization_code`.
`code`	Required. The single-use authorization code returned to the callback.
`redirect_uri`	Required. The same redirect URI used in the authorization request.
`code_verifier`	Required. The original 43–128 character PKCE verifier.

The response has this shape:

{
  "access_token": "<JWT access token>",
  "token_type": "Bearer",
  "expires_in": 900,
  "refresh_token": "<opaque refresh token>",
  "refresh_token_expires_in": 2592000,
  "scope": "connections:read retailers:read purchases:brand_products",
  "subtotal_client_id": "<authorizing dashboard team ID>"
}

Response field	Meaning
`access_token`	Bearer token for authorized Subtotal API requests.
`token_type`	Always `Bearer`.
`expires_in`	Access-token lifetime in seconds. Currently `900`.
`refresh_token`	Opaque token used to obtain the next access token. Store it encrypted.
`refresh_token_expires_in`	Seconds until the returned refresh token expires. Currently up to `2592000` (30 days).
`scope`	The fixed permissions granted to the app.
`subtotal_client_id`	The dashboard team that authorized the installation.

A successful exchange activates the app installation for the selected dashboard team and starts configured webhook delivery.

Identify the app and installation

The authorization flow uses two identifiers with different sources:

Name	Source and meaning
`client_id`	The OAuth app’s Client ID, shown in Created Apps and sent by your app during authorization and token exchange
`subtotal_client_id`	The authorizing dashboard team’s ID, returned by Subtotal in the token response

Store subtotal_client_id with the installation. It identifies the dashboard team that granted access; do not infer that team from the person who completed consent. An installation is unique to one app and dashboard team. Reauthorizing the same pair updates the existing installation instead of creating another one. Each refresh-token rotation starts a new 30-day lifetime. Track expiry using the response values rather than hard-coded durations. Keep tokens encrypted on your server, out of browser storage, URLs, and logs.

4. Refresh access tokens

Use the current refresh token when the access token is near expiry. Authenticate the app with HTTP Basic and send form-encoded parameters.

curl --request POST https://oauth.subtotal.com/oauth/token \
  --user "$SUBTOTAL_OAUTH_CLIENT_ID:$SUBTOTAL_OAUTH_CLIENT_SECRET" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=refresh_token' \
  --data-urlencode "refresh_token=$SUBTOTAL_REFRESH_TOKEN"

Form parameter	Required value or purpose
`grant_type`	Required. Use `refresh_token`.
`refresh_token`	Required. The current refresh token for the installation.

A successful refresh preserves all three scopes and returns the same fields as the code exchange, with new tokens and expiry values. Refresh only once at a time per installation. Save all returned values in one atomic update before the next refresh, and always use the newest refresh token.

Retries and recovery

After a timeout, network failure, or temporary server error, retry promptly with the same refresh token. If the first request succeeded, retries return the same replacement refresh token and a fresh access token. The previous refresh token is retryable for 60 minutes from its rotation, or until its replacement is used for another refresh, whichever comes first. Retries do not extend this window or the replacement’s expiry. Reusing an older token or retrying after that window returns 400 invalid_grant, revokes the installation’s refresh tokens, and disconnects the app, stopping new webhook delivery. Expired or revoked refresh tokens also return invalid_grant. On this error, stop retrying, pause background work, and ask the brand to authorize the app again.

Upgrade an existing installation

Installations authorized before retailers:read was included need fresh consent. Existing access tokens keep their original permissions until expiry; refreshing does not add the new scope. Authorization codes and refresh tokens with the old two-scope grant return invalid_grant.

Have the brand click Install app again. Your Install URL must start a new authorization flow with all three scopes, or omit scope.
Have the brand select the same dashboard team and approve access.
Exchange the new code and replace the stored tokens for that installation.

This updates the existing installation. No uninstall is required. The new access token can call GET /retailers.

5. Recover installation identity

If the callback succeeds but your state-to-installation mapping is lost, call /oauth/me with the access token. This endpoint has no query or form parameters.

curl https://oauth.subtotal.com/oauth/me \
  --header "Authorization: Bearer $SUBTOTAL_ACCESS_TOKEN"

{
  "subtotal_client_id": "<authorizing dashboard team ID>",
  "client_id": "<your OAuth app Client ID>",
  "scope": "connections:read retailers:read purchases:brand_products"
}

6. Disconnect in Subtotal

A brand can open the installed app under Apps, select Disconnect, and type DISCONNECT to confirm. This removes the app’s access to that brand’s data and stops sending new events to the app.

Confirmation dialog for disconnecting Northstar Rewards Sync

Disconnecting revokes active refresh tokens and deactivates the installation. Already-issued access tokens remain valid until their 15-minute expiry. If a refresh fails with invalid_grant, stop background work and require reauthorization. To reconnect, send the brand through a new authorization flow.

7. Revoke from your service

If a brand uninstalls from your product, revoke its active refresh-token session. Authenticate with the app’s current Client ID and client secret.

curl --request POST https://oauth.subtotal.com/oauth/revoke \
  --user "$SUBTOTAL_OAUTH_CLIENT_ID:$SUBTOTAL_OAUTH_CLIENT_SECRET" \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode "token=$SUBTOTAL_REFRESH_TOKEN"

Form parameter	Required value or purpose
`token`	Required. The refresh token for the installation being revoked.

Revocation returns 200 for known and unknown tokens. For a known token, it revokes active refresh tokens for that app and dashboard team, deactivates the Subtotal installation, and stops webhook delivery. Already-issued access tokens are self-contained and remain valid until their 15-minute expiry.

Documentation

Platform

Integrations

Guides

1. Request authorization

2. Handle the callback

3. Exchange the authorization code

Identify the app and installation

4. Refresh access tokens

Retries and recovery

Upgrade an existing installation

5. Recover installation identity

6. Disconnect in Subtotal

7. Revoke from your service

​1. Request authorization

​2. Handle the callback

​3. Exchange the authorization code

​Identify the app and installation

​4. Refresh access tokens

​Retries and recovery

​Upgrade an existing installation

​5. Recover installation identity

​6. Disconnect in Subtotal

​7. Revoke from your service

1. Request authorization

2. Handle the callback

3. Exchange the authorization code

Identify the app and installation

4. Refresh access tokens

Retries and recovery

Upgrade an existing installation

5. Recover installation identity

6. Disconnect in Subtotal

7. Revoke from your service