The SweatStack Portal

Beta

The Portal is in beta. We can release breaking changes to it with little notice. If you plan to use it in production, email [email protected] before you integrate. We'll then tell you before a breaking change is released and help you migrate.

Sometimes a user's data isn't flowing and the fix is in their SweatStack account: a source to connect, a permission to grant, a stale connection to replace. You could build those screens yourself. The Portal exists so you don't have to.

It's a SweatStack-hosted page that does that one job and nothing else. It carries your branding, and when your users are done, it sends them back to you.

Try the live demo

Your users always come back

This is the part worth reading twice, because it's the thing you're trusting us with.

Every Portal page carries a link back to your app. When there's nothing left to do, that link is the page's primary button, so the user is never left to find their own way out.

You choose where it goes, when you create the link:

What you do	What your user gets
Pass return_url	Back to {your app}, pointing exactly there
Omit return_url	"You can close this page and return to {your app}"

There is no default. SweatStack never guesses where your app lives, because your app's public URL is often a website, not the page the user came from.

return_url follows the same rule as an OAuth redirect_uri: it must equal or sit under one of your registered redirect URIs. If your redirect URIs are only OAuth callbacks, such as https://example.com/auth/callback, register a URI that covers the pages you want users back on, such as https://example.com/.

If your app is native, omit return_url. A custom-scheme return URL must equal a registered redirect URI exactly, and that URI is an OAuth callback, which shows an error when it opens outside a sign-in. The app is almost always still running behind the browser, so telling the user to close the page is both true and what works.

And when we can't build a link back, we say so instead of saying nothing. A user who can't be helped at all is offered SweatStack support instead of being left in a loop.

The one case that needs your help

If some of your users run your app as an installed PWA, a link can't bring those users back. On iOS, opening a URL inside an installed app's scope opens a new browser tab instead of reopening the app.

We can't detect this. The Portal runs in the browser, not inside your app, so no amount of user-agent sniffing on our side would tell us. You know, and it's one line:

const standalone = window.matchMedia('(display-mode: standalone)').matches
                || window.navigator.standalone;              // iOS Safari

const { url } = await fetch('https://app.sweatstack.no/api/v1/portal/sessions', {
  method: 'POST',
  headers: { authorization: `Bearer ${accessToken}`, 'content-type': 'application/json' },
  body: JSON.stringify({
    destination: user.issue.destination,
    // Omitted on purpose when standalone. The Portal then tells the user to close the
    // page, which is what actually works when a link can't reopen your app.
    ...(standalone ? {} : { return_url: location.href }),
  }),
}).then(r => r.json());
location.assign(url);

No backend needed: CORS permits the call from the browser. If all your users are in a normal browser, ignore the standalone check and always pass return_url.

How it works

1. Your app notices something is wrong, usually from the issue field on userinfo. When the user can fix it, issue.destination is set.
2. When the user clicks your button, you create a Portal link for that destination and send them there.
3. They arrive on a SweatStack page with your logo, showing everything outstanding on their account.
4. They fix it and press Back to your app.

Step 3 is deliberate. The Portal doesn't show only the one issue your app was told about. It shows everything outstanding. A user sent to fix one thing can come back having fixed three, and they never bounce in and out resolving them one at a time.

The fastest way to understand these four steps is to walk them with your own account. The live demo signs you in, renders issue and capabilities the way this documentation prescribes, creates a session from the browser, and opens the real Portal, so you can come back through its link and see what changed.

Try the live demo

What your user sees

Nothing connected yet

The most common arrival by a wide margin. About a quarter of accounts have no activities at all, and most of those have connected nothing. For most users this is a connect page, not a manage page.

Something needs their attention

Leads with one action. The rest stay reachable below it.

Data is still arriving

No button, because there's nothing to do.

A permanent limit

Some things can't be fixed by anyone. An account whose activities reach us through Intervals.icu from Strava will never have history. The Portal explains these once, quietly, and never as a prompt.

Everything is fine

Including when your link is stale and the user already fixed it. This reads as reassurance, never as an error.

Every case, and where it lands

The code and message are exactly what your app receives from userinfo or GET /api/v1/profile/status. {source} is the connection's name, for example "Garmin Connect".

code	status	The message your app receives	Where the user lands
no_source_connected	action_required	No data source is connected yet.	Connect
activities_not_granted	action_required	{source} isn't sharing activities.	Needs attention
activity_history_not_granted	action_required	{source} isn't sharing past activities.	Needs attention
dailies_not_granted	action_required	{source} isn't sharing daily health data.	Needs attention
workouts_not_granted	action_required	{source} isn't accepting workouts.	Needs attention
sync_pending	syncing	{source} data is still arriving.	Still arriving
activity_history_unavailable	unavailable	{source} can't provide activities from before it was connected.	Worth knowing
dailies_unavailable	unavailable	No connected source provides daily health data.	Worth knowing
workouts_unavailable	unavailable	No connected source accepts workouts.	Worth knowing
(none)		issue is null	All set

Every message is one short sentence, so it fits a banner without wrapping. A code reads as its capability plus its status: <capability>_not_granted when the user can fix it, <capability>_unavailable when nobody can.

Two more the Portal handles on its own

These describe this visit rather than the account, so they never appear in issue. You may still see them in a screenshot or a support conversation.

Already connected elsewhereAlready has an account

The provider account belongs to a different SweatStack account.

The provider's email address already has a SweatStack account.

Creating a Portal session

POST /api/v1/portal/sessions creates a Portal link, branded for your app, and returns the URL to send the user to. It is the only way to get a Portal URL.

PythoncURL

from sweatstack import Client

client = Client()  # holds the user's access token
session = client.portal.sessions.create(
    "manage-integrations", return_url="https://example.com/app/settings"
)
print(session.url)

curl -X POST https://app.sweatstack.no/api/v1/portal/sessions \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"destination": "manage-integrations", "return_url": "https://example.com/app/settings"}'

Authenticate with the user's access token, the one your app got from the OAuth flow. The token tells SweatStack which app the link is for, so the body names neither your app nor its secret.

Body fields:

• destination (required): the Portal page to open. Pass issue.destination as it is. manage-integrations opens the user's data connections. manage-teams opens a coach's teams.
• return_url (optional): where Back to {your app} sends the user, at most 2048 characters. It must equal or sit under one of your registered redirect URIs, the same rule as an OAuth redirect_uri. A query string and a fragment are allowed. If you omit it, the Portal tells the user to close the page; see Your users always come back.

The API returns the URL:

{ "url": "https://app.sweatstack.no/portal/integrations?app=01JMYRA...&return_url=..." }

Create the link when the user acts, and send them straight there. Don't store or reuse it.

Errors:

• 400 with "return_url must equal or sit under one of the application's registered redirect URIs": register a redirect URI that covers the page, or pass a different return_url.
• 400 with "Portal links are created by applications": the token was not issued to an app. Use an access token from your app's OAuth flow, not an API key.
• 401: no access token, or an expired one. Refresh the token and try again.
• 403: a delegated token (a coach viewing an athlete). A Portal link opens the account of whoever is signed in, so only the user can fix their own account. On these tokens issue.destination is always null.

Don't build Portal URLs yourself

The URL in the response is not a stable contract. Its shape will change, and we can replace the query parameters with opaque tokens without notice.

Create every link through this endpoint. It always produces a working URL. Anything you assemble by hand will break.