mop-skills/skills/garmin-auth/SKILL.md

name, description

name	description
garmin-auth	Manage Garmin Connect authentication, proactive OAuth token keepalives, and interactive 2-turn MFA login over Telegram. Use when Garmin authentication fails (HTTP 401, expired tokens) or when the user asks to log into Garmin.

🔐 Garmin Connect Authentication & MFA Manager

Headless authentication lifecycle manager for Garmin Connect, allowing OpenClaw to initiate logins, keep tokens perpetually fresh, and verify 6-digit MFA codes directly via Telegram.

🎯 When to Use

• Authentication Errors: Whenever a garmin MCP tool call fails with Garmin authentication failed, Tokens expired, 401 Unauthorized, or Failed to retrieve social profile.
• User Request: Whenever the user explicitly asks: "Logge dich bei Garmin ein", "Garmin MFA Code eingeben", "Garmin Re-Auth", "Verbinde Garmin".
• Keepalive / Watchdog: During morning briefings or background checks to ensure tokens are proactively refreshed before expiring.
• Status Checks: Whenever asked about Garmin token health or expiration: "Ist Garmin eingeloggt?", "Wie lange ist der Garmin-Token noch gültig?".

---

🕹️ Interactive Telegram MFA Login Flow (Protocol)

Because Garmin requires Multi-Factor Authentication (OTP sent via SMS/email), login operates in two conversation turns:

Turn 1: Request Code (Initiate Login)

1. Execute the request-code command:

   uv run /home/node/mop-skills/mop-skills/skills/garmin-auth/scripts/garmin_auth.py request-code
   

2. The command spawns a background authentication daemon and triggers Garmin to dispatch the 6-digit code to the user's email/SMS.
3. Immediately send a clear, friendly prompt to the user on Telegram:

   🔑 Garmin-Authentifizierung erforderlich Ich habe einen neuen Login bei Garmin gestartet. Garmin hat dir soeben einen 6-stelligen Sicherheitscode per SMS oder E-Mail gesendet.

   Bitte antworte mir einfach kurz mit dem 6-stelligen Code!

Turn 2: Verify Code (Complete Login)

1. When the user sends a 6-digit message (e.g. 538291, 538 291):
2. Execute the verify command:

   uv run /home/node/mop-skills/mop-skills/skills/garmin-auth/scripts/garmin_auth.py verify "<mfa_code>"
   

3. If successful:
   • The tokens are automatically dumped to /home/node/.openclaw/garmin_tokens/garmin_tokens.json and base64 exported.
   • Reply to the user:

     ✅ Garmin-Login erfolgreich! Angemeldet als Moritz Graf. Alle Garmin-Tools und Workouts sind wieder voll einsatzbereit.

4. If the code was incorrect:
   • The daemon remains alive for 5 minutes. Inform the user and allow them to retry:

     ⚠️ Der eingegebene Code war leider ungültig oder abgelaufen. Bitte prüfe den Code und sende ihn erneut.

---

🛠️ CLI Operations Reference

1. Check Token Health & Validity

uv run /home/node/mop-skills/mop-skills/skills/garmin-auth/scripts/garmin_auth.py status

Outputs JSON with valid, user, exp_utc, pending_mfa.

2. Proactive Keepalive (Refresh Token before Expiry)

uv run /home/node/mop-skills/mop-skills/skills/garmin-auth/scripts/garmin_auth.py keepalive

Touches the API, triggering python-garminconnect's automatic token refresh and persisting the newly rotated refresh token to /home/node/.openclaw/garmin_tokens/garmin_tokens.json.

---

🔒 Security & Environment

• Requires GARMIN_EMAIL and GARMIN_PASSWORD (already injected via openclaw-secrets).
• Persistent storage: /home/node/.openclaw/garmin_tokens/garmin_tokens.json (on PVC openclaw-data).
• Directory permissions are automatically set to 0700 and files to 0600.