WHOOP Central

Access sleep, recovery, strain, and workout data from WHOOP via the v2 API.

Quick Commands

# 1) One-time setup (writes ~/.clawdbot/whoop/credentials.json)
node src/setup.js

# 2) Recommended: Get tokens via Postman (see Auth section), then verify
node src/verify.js
node src/verify.js --refresh

# Prompt-friendly snapshot (includes last workout)
node src/today.js

# Daily summary (all metrics)
node src/summary.js

# Individual metrics
node src/recovery.js
node src/sleep.js
node src/strain.js
node src/workouts.js

# Bulk import to ~/clawd/health/logs/whoop/*
node src/import-historical.js

Data Available

| Metric | Data Points |

|--------|-------------|

| Recovery | Score (0-100%), HRV, resting HR, SpO2, skin temp |

| Sleep | Duration, stages (REM/deep/light), efficiency, performance |

| Strain | Daily strain (0-21), calories, avg/max HR |

| Workouts | Activity type, duration, strain, calories, HR |

Recovery Score Guide

• 💚 67-100% Green - Ready to perform
• 💛 34-66% Yellow - Moderate readiness
• ❤️ 0-33% Red - Focus on recovery

Setup

0. Requirements

• Node.js 18+ (this repo uses ESM)
• openssl (only needed for the optional auth.js flow when using https://localhost; Postman auth does not need it)

1. Create WHOOP Developer App

1. Go to https://developer.whoop.com/
2. Sign in with your WHOOP account
3. Create a new App
4. Add these Redirect URIs (exact match; no extra trailing slashes):

• Postman browser callback (recommended auth path):

https://oauth.pstmn.io/v1/browser-callback

• Optional local callback (only used by auth.js):

https://localhost:3000/callback

You can keep both registered at the same time.

1. Copy the Client ID and Client Secret

Team note: this skill does not ship any client credentials. Each user can create their own WHOOP app,

or (if you trust each other) a team can share one app's client_id/client_secret and let multiple WHOOP

accounts authorize it.

2. Save Credentials (recommended: interactive)

Run:

node src/setup.js

This writes ~/.clawdbot/whoop/credentials.json (and optionally token.json if you paste tokens).

3. Authenticate (Recommended: Postman)

Postman is the most reliable bootstrap for many accounts because WHOOP may block browser-like traffic

to the OAuth endpoints (or behave differently depending on headers).

Postman checklist (don’t skip these):

• WHOOP dashboard Redirect URIs include:
• https://oauth.pstmn.io/v1/browser-callback
• Postman OAuth settings:
• Scopes include offline (or you won’t get a refresh_token)
• Client Authentication is Send client credentials in body (client_secret_post)

1) In WHOOP dashboard, ensure you registered the Postman callback Redirect URI:

https://oauth.pstmn.io/v1/browser-callback

2) In Postman:

• Create an Environment and set variables:
• ClientId = your WHOOP client id
• ClientSecret = your WHOOP client secret
• Open the WHOOP API collection (or any request), then open the Authorization tab:
• Type: OAuth 2.0
• Add auth data to: Request Headers
• Grant Type: Authorization Code
• Callback URL: check Authorize using browser
• Auth URL:

https://api.prod.whoop.com/oauth/oauth2/auth

• Access Token URL:

https://api.prod.whoop.com/oauth/oauth2/token

• Client ID: {{ClientId}}
• Client Secret: {{ClientSecret}}
• Scope (space-delimited): include offline plus any read scopes you need, e.g.:

offline read:profile read:sleep read:recovery read:workout read:cycles read:body_measurement

• State: any 8+ chars (e.g. loomingState)
• Client Authentication: Send client credentials in body

3) Click "Get New Access Token", sign in to WHOOP, and click "Grant".

4) In Postman’s "Manage Access Tokens" modal:

• Click "Use Token" (so requests work)
• IMPORTANT: copy and save both:
• access_token
• refresh_token

Postman often does not retain the refresh token for you later.

5) Save tokens to ~/.clawdbot/whoop/token.json:

• Use token.example.json as a template
• Set:
• obtained_at to current time in milliseconds
• redirect_uri to:

https://oauth.pstmn.io/v1/browser-callback

6) Verify (and test refresh):

node src/verify.js
node src/verify.js --refresh

4. Optional: Authenticate via auth.js (may fail on some accounts)

If you prefer a fully local OAuth loop (and WHOOP allows it), you can use auth.js.

Pre-req: add this redirect URI in WHOOP dashboard:

https://localhost:3000/callback

Run:

WHOOP_REDIRECT_URI='https://localhost:3000/callback' node src/auth.js

If you need to do it from a phone/remote device:

WHOOP_REDIRECT_URI='https://localhost:3000/callback' node src/auth.js --manual

Note: for localhost HTTPS, the script generates a self-signed cert and your browser will show a TLS warning.

You must proceed past the warning so the redirect can complete.

4. Verify It Works

node src/verify.js
node src/summary.js

Troubleshooting

Browser shows NotAuthorizedException before the login page

This is a WHOOP-side block on browser User-Agents hitting api.prod.whoop.com OAuth endpoints.

• Use the updated node src/auth.js which bootstraps the login URL and sends your browser directly to id.whoop.com.
• If you still see it, try node src/auth.js --manual and open the printed URL.

"redirect_uri not whitelisted"

1. Go to https://developer.whoop.com/
2. Edit your app
3. Ensure this EXACT URI is in Redirect URIs:

https://oauth.pstmn.io/v1/browser-callback

If you're using auth.js locally, also add:

https://localhost:3000/callback

4. Save and try again

Token Expired

Tokens auto-refresh on demand (no cron needed). If issues persist:

rm ~/.clawdbot/whoop/token.json
node src/auth.js

"Authorization was not valid"

This usually means your access token is stale/invalidated (common if you re-auth or refresh tokens elsewhere; WHOOP refresh tokens rotate).

• Re-run node src/auth.js, or
• Copy the latest access_token + refresh_token from Postman into ~/.clawdbot/whoop/token.json and update obtained_at.

Auth from Phone/Remote Device

Use manual mode:

node src/auth.js --manual

Open the URL on any device, authorize, then copy the code from the callback URL.

error=request_forbidden / "The request is not allowed"

This is WHOOP rejecting the authorization request after login/consent. Common causes:

• Redirect URI policy (WHOOP docs only mention https:// or whoop:// redirect URIs)
• App/account restrictions (membership/approval/test-user restrictions)
• Scope restrictions (try requesting fewer scopes)

If you suspect redirect URI policy, use an HTTPS tunnel:

# 1) Get a public HTTPS URL that forwards to localhost:3000 (example)
ngrok http 3000

# 2) Add the ngrok HTTPS URL + /callback to WHOOP dashboard Redirect URIs, then run:
WHOOP_REDIRECT_URI=https://YOUR-NGROK-DOMAIN.ngrok-free.app/callback node src/auth.js

If you suspect scope restrictions, try a minimal scope set:

WHOOP_SCOPES="read:profile" node src/auth.js

If your WHOOP Redirect URL is https://localhost:3000/callback

This changes how the local callback server must run: it must be HTTPS (not HTTP).

The script supports this. Run:

WHOOP_REDIRECT_URI=https://localhost:3000/callback node src/auth.js

It will generate a self-signed cert locally and your browser will likely show a warning for https://localhost.

Proceed past the warning so the redirect can complete.

JSON Output (for tooling)

These commands support:

• --json (single JSON blob)
• --jsonl (one JSON object per line; useful for piping)
• --limit N (where supported)
• Time filters (where supported): --days N, --since 7d / 12h, --start ISO, --end ISO

node src/summary.js --json
node src/recovery.js --json --limit 1
node src/sleep.js --json --limit 1
node src/strain.js --json --limit 1
node src/workouts.js --json --limit 1

# Examples with filters
node src/sleep.js --json --days 7
node src/workouts.js --jsonl --since 30d
node src/recovery.js --json --start 2026-01-01T00:00:00Z --end 2026-02-01T00:00:00Z

API Notes

• Uses WHOOP Developer API v2
• OAuth 2.0 authentication with refresh tokens
• Scopes: offline, read:recovery, read:sleep, read:workout, read:cycles, read:profile
• Token auto-refreshes when expired