WHOOP Central

---

name: whoop description: WHOOP Central - OAuth + scripts to fetch WHOOP data (sleep, recovery, strain, workouts). Use when user asks about their sleep, recovery score, HRV, strain, or workout data. version: 1.0.2 metadata: clawdbot: emoji: "🏋️" requires: bins: ["node", "openssl"]

---

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. 5. 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

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. 5. 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

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.