Garmin Personal API key
Garmy vault/Guides/Garmin Personal API key
Guides/garmin-personal-api-key.md

Garmin Personal API key: where to find it and what it can do

Properties
where
Garmin Connect, Settings, Personal API Key
lifetime
you choose it when you create the key
shown
once
token
24 hours, handled by Garmy
checked on
Garmy 1.1.2

A Personal API key is a long password that lets an app read your own Garmin data. You create it in Garmin Connect and choose how long it lives. Garmy needs one. This page says where to find it, what Garmy reads with it and what Garmin does not give out.

The Personal API Key page in the Garmin Connect settings, with an active key and a Delete button
Garmin Connect, Settings, Personal API Key.

1Open the Personal API Key page

Open Garmin Connect in your browser, then Settings›Personal API Key. The page is Garmin's, so Garmin can move it. If you cannot find it, search the Garmin Connect settings for the words "Personal API Key".

You need a Garmin Connect account. The same account your watch syncs to.

2Create the key

  1. Accept the terms.
  2. Create a key and pick its lifetime.
  3. Copy it. Garmin shows the key only once.

The page in the picture above tells you why: for your privacy an existing key is not displayed. To generate a new key you must first delete the current one, and after you generate a new key the previous key no longer works. So paste the key into Garmy right away.

3Paste it into Garmy

Install Garmy, run Garmy: Build a Garmin dashboard and paste the key into the first step. Check and continue asks Garmin whether the key works before the wizard moves on.

The first wizard step: a safe-storage note, three steps for getting a key, a picture of the Garmin Connect page and the key field
Step 1 of the wizard. The picture of Garmin's page is built into the plugin.

If something goes wrong, the wizard says one of three things:

  • Not acceptedGarmin did not accept the key. Check that it was copied whole and has not expired. The fix is to paste another key.
  • No connectionCannot reach Garmin. Check your connection and try again.
  • WaitGarmin asks to wait. Try again in a minute.

What Garmy reads with it

Garmy exchanges the key for a token that is valid for 24 hours, then calls four Garmin services. A year of history takes about 17 requests.

ServiceWhat Garmy takesWritten as
dailysummariesSteps, resting heart rate, average stress, the day's highest Body Batterysteps resting_hr stress body_battery
dailySleepSummariesByDateOverall sleep score, time asleepsleep_score sleep_duration
hrv/dailyLast night's average HRVhrv
activities/searchRuns, rides, swims and strength sessions: distance and duration, summed per dayrun_km run_min bike_km bike_min swim_km swim_min strength_min

All requests go to personal.connectapi.garmin.com, and nowhere else.

What it cannot do

  • Training Readiness. The Personal API does not provide it.
  • A VO2 max number. Same reason.
  • A full daily distance. The range endpoints report walking distance only, so Garmy does not write distance_km rather than show a wrong number.
  • Splitting a multi-sport activity into its sports.

How long it lasts

You choose the lifetime when you create the key. When Garmin rejects the key, Garmy says so once and settings show Replace key. Create a new key in Garmin Connect and paste it in the wizard. The 24 hour token cannot be refreshed, so Garmy asks for a new one after 23 hours.

Where the key is kept

It is kept in Obsidian's secure storage. It is never written to a note, to data.json or to a log, and error messages never contain it. Forget key in Garmy's settings removes it. The details are in SECURITY.md.

Read the terms

The terms are Garmin's

Garmin describes the Personal API as meant for individuals who want programmatic access to their own data, not for commercial applications serving multiple end users. Garmy has no server and no accounts: it runs on your computer with your own key. Read what you accept when you create a key.