Bring your own keys¶
With your own Garmin keys registered, the Garmin button on your app's sign-in screen runs on them. Garmin's consent screen shows your app's name, and whoever signs in that way becomes a user of your app. SweatStack still receives Garmin's pushes, runs the backfill and sends workouts to the watch, all with your keys. Every other sign-in option on your screen stays SweatStack's. For how this compares to the other two layers, see Choosing how athletes connect.
Bring your own keys is available for Garmin. Other platforms stay hosted.
Before you start¶
Make sure your Garmin agreement allows SweatStack to use your keys and receive the data on your behalf. Garmin's developer agreement does not let you share your consumer key with another company, or send Garmin data to an endpoint you do not control, without Garmin's written permission. In practice:
- Get Garmin's written permission for your app to use SweatStack this way.
- Name SweatStack as your service provider in your Garmin application, or tell Garmin before you switch.
- Include SweatStack's screens that show Garmin data or Garmin's brand in the display notice Garmin requires 30 days before you show them: the Garmin button on the sign-in screen, and the Portal's integrations page.
Arranging this is your responsibility, as Part B of the developer terms says. SweatStack does not check it.
You also need:
- A Garmin consumer key that uses OAuth 1.0. SweatStack does not support keys on Garmin's OAuth 2.0 yet; if Garmin converted your app, wait for that support before you switch your keys on.
- An app that is live (see Going live).
- The developer terms and the Data Processing Agreement accepted for it on its Consent screen tab. The users your keys create belong to your app, and SweatStack processes their data for you under the Data Processing Agreement.
Register your keys¶
- Open your app's settings and go to the Data sources tab. It lists every platform your sign-in screen offers: Hosted platforms run on SweatStack's keys, Your keys platforms on yours.
- In the Garmin Connect card, turn on Own keys. The card opens the setup.
- Enter your Garmin consumer key and consumer secret.
- Select Save keys.
Garmin Connect then shows Your keys, and the Garmin button on your sign-in screen runs on them. If it also shows Not in use yet, your app is not live, or the developer terms are not accepted for it on the Consent screen tab. Open Keys and Garmin Connect settings at the foot of the card to change the keys or find the URLs again.
SweatStack stores the secret encrypted and never shows it again; the tab shows its last four characters. You can replace the secret at any time. You cannot change the consumer key while athletes are connected on it: their Garmin authorizations belong to that key.
The tab takes a key and a secret and nothing else. Garmin's addresses are fixed in SweatStack.
Go back to SweatStack's keys¶
In the Garmin Connect card, turn Own keys off and confirm. SweatStack deletes your keys, and the Garmin button goes back to SweatStack's keys.
If athletes are connected on your keys, the confirmation says how many. Their Garmin connection stops: SweatStack removes each one at Garmin with your keys. The athletes stay users of your app, and have to connect Garmin again. Through the API, DELETE /api/v1/applications/{client_id}/integration-providers/garmin_connect answers 409 in that case unless you add ?disconnect_athletes=true.
Point your key at SweatStack¶
In Garmin's endpoint configuration, signed in with your consumer key and secret, enable these settings with the URLs from the Garmin Connect card of the Data sources tab (under Garmin Connect portal settings), and leave every other setting disabled. Where your Garmin app's settings in the developer portal ask for an OAuth 2 redirect URL, enter the card's Redirect URL: https://app.sweatstack.no/api/v1/tenants/{client_id}/integration-providers/garmin_connect/oauth2-authorization-callback. The notification URLs have this form, with your app's client ID in them:
| Garmin setting | URL |
|---|---|
| Activity: Activity Files (ping) | https://app.sweatstack.no/api/v1/tenants/{client_id}/integration-providers/garmin_connect/activity-ping |
| Health: Dailies (push) | .../garmin_connect/health-push |
| Health: Sleeps (push) | .../garmin_connect/health-push |
| Health: Body Compositions (push) | .../garmin_connect/health-push |
| Health: HRV (push) | .../garmin_connect/health-push |
| Common: Deregistrations | .../garmin_connect/deregister |
| Common: User Permissions Change | .../garmin_connect/user-permissions |
Garmin allows one URL per setting. After this change, your own server receives nothing from Garmin for this key. Your app gets SweatStack's webhooks instead. If your app needs Garmin's raw pushes itself, use Bring your own data instead: your app keeps the Garmin connection and sends SweatStack the files.
The tab also shows when an athlete last signed in on your keys and when Garmin last called these URLs. If Garmin never calls them, the URLs are not set in Garmin's portal.
What the athlete sees¶
A new athlete who signs in with Garmin at your app sees the same screens as with SweatStack's keys, with two differences:
- Garmin's consent screen names your app instead of SweatStack.
- There is no SweatStack consent screen. Your app holds the account, so SweatStack asks only for the athlete's email, with the line "Your data is held by {your app} and processed by SweatStack". The athlete then gets an email and opens its link to continue. If you send
login_hint, it fills in the field.
After that, the flow is the one you know: your redirect_uri receives a code, and you exchange it at the token endpoint. The token, userinfo (with email), the data endpoints, webhooks, the account status and Portal links are the same as for any athlete.
A returning athlete goes straight back to your app, as with SweatStack's keys: SweatStack remembers the athlete in the browser for your app only. To let an athlete choose another account, send prompt=login or prompt=select_account; the sign-in screen is then shown.
On your sign-in screen, "Continue with email" signs in your app's user with that email, if there is one. Email never creates a user of your app. To offer only Garmin, send integration=garmin_connect (see Authorization request parameters).
Athletes who already use your app¶
An athlete who already connected Garmin to their SweatStack account and authorized your app keeps that account. When such an athlete signs in with Garmin on your keys, SweatStack recognises them: it signs them in to their SweatStack account, removes the connection your key just made, and your app gets a code for the same sub as before, with the scopes it already had. A request for more scopes shows the consent screen, as always.
What this means for the athlete:
- Garmin Connect lists SweatStack, not your app, under their connected apps.
- A permission they change for SweatStack in Garmin Connect applies to every app they use through SweatStack.
- If they gave your key a permission that their SweatStack connection does not have, the account status reports it, and the Portal shows them how to fix it.
The same happens at the email step: if the address belongs to a SweatStack account that authorized your app, or to another user of your app, the email offers a sign-in to that account. The screen is the same for every address, so it never tells anyone whose address it is.
Remove a connection¶
SweatStack tells Garmin when a connection on your keys ends: when the athlete disconnects Garmin in the Portal, when you delete the user with the management API, when SweatStack recognises an athlete who already uses your app, when you go back to SweatStack's keys, and when you delete your app.
If Garmin cannot be reached when you delete a user, or when SweatStack recognises an athlete, SweatStack tries again after 10 minutes, 1 hour and 6 hours. Data that Garmin sends in the meantime reaches no account. After the last attempt, the Data sources tab counts the connection and offers Try again now. When you go back to SweatStack's keys or delete your app, SweatStack tells Garmin once; Garmin data that still arrives after that reaches no account.