SweatStack bridge

Beta

Self-hosted integrations are in beta and are subject to breaking changes. If you plan to use them in production, email [email protected] before you integrate, so we can tell you about changes in advance and help you migrate.

This page describes the SweatStack bridge: what it is, what it implements of the self-hosted integration contract, and how you deploy and run it.

The SweatStack bridge is SweatStack's reference implementation of the self-hosted integration contract. It is a small service that you deploy in your own Cloudflare account, on your own platform keys. It works with Garmin Connect.

Garmin Connect  ──►  Bridge, in your Cloudflare account  ──►  SweatStack  ──►  Your app

• Your name. Athletes see your app on the platform's consent screen.
• Your keys. The platform's client secret and every athlete's platform tokens stay in your Cloudflare account. SweatStack never holds them.
• No guarantees. It is a reference implementation with no guarantees. You run it and you are responsible for it. SweatStack does not operate, monitor or update your deployment.
• MIT license. You can run it as it is, change your copy, or read it as an example for your own integration.

SweatStack depends only on the contract, so you can replace the bridge with your own code at any time.

What it does

Part of the contract	The bridge
Sign-in	Lets athletes sign in to your app with their Garmin account
Data	Relays new activities as they arrive, and requests activity history when an athlete connects
Connection state	Keeps the account status and the Portal correct when an athlete connects, changes permissions or disconnects
Disconnect	Gives the Portal a working Disconnect button

Not available yet: dailies and workouts.

The bridge stores the athletes' Garmin tokens in your Cloudflare account. Files pass through it, and it keeps no copy. If it cannot deliver a file, it tries again for up to 3 days. For how it works internally, see DEVELOPING.md.

Before you start

You need:

1. A live app on SweatStack, with write ticked for Activities under Data your app uses. Without it, SweatStack refuses every file.
2. Keys from the platform. For Garmin Connect, see Get your keys. Request them early, because the platform decides how long this takes.
3. A Cloudflare account on the Workers Paid plan, USD 5 a month. The CPU limit of the free plan is too low for the bridge.
4. An understanding of what changes for your users: your sign-in screen loses its email sign-up, and one person can be two users of your app.

If your app already has athletes on Garmin Connect through SweatStack, email [email protected] before you deploy. We help you move them, and keep their history.

Deploy it

With an approved Garmin app, a deploy takes about 10 minutes. The runbook has every step. In short:

1. Select Deploy to Cloudflare in the repository.
2. Create a client secret for the bridge on your app's OAuth tab, and set it in the bridge.
3. Set the platform's keys, and paste the bridge's URLs into the platform's developer settings. For Garmin Connect, see Paste the URLs.
4. On your app's Data sources tab, choose Self-hosted on the platform's card, and paste the bridge's issuer URL.
5. Test a sign-in. See Check the setup.

Choose the bridge's address before step 3. If you move it later, you paste the URLs again. Do not delete the bridge's database: without it, every athlete has to connect again and comes back as a new user.

Run it

Nobody at SweatStack monitors your bridge. If you need help, email [email protected]. Two commands in your copy of the repository:

• npm run status shows the version, what is missing, whether the bridge and SweatStack answer, how many athletes are connected, and which jobs wait or failed. It prints no secrets.
• npm run update moves your copy to the latest release, and keeps your own changes. Review the result, then commit and push to deploy.

To hear about releases, select Watch, Custom, Releases on the repository. The changelog lists what each release changes.