Authentication Tools

Three tools for managing WHOOP OAuth authentication. These are primarily used in the self-hosted CLI version.

Cloud Users

If you're using the cloud version at app.wellpipe.io, authentication is handled automatically through the dashboard. You don't need to use these tools directly.

---

authenticate-whoop

Initiate the OAuth flow to authenticate with WHOOP. Returns an authorization URL that must be opened in a browser.

Parameters

Parameter	Type	Required	Default	Description
port	number	No	3000	Local port for OAuth callback

Example Questions

• "I need to connect my WHOOP account"
• "Authenticate with WHOOP"

Response

{
  "status": "ready",
  "message": "Open the following URL in your browser to authorize with WHOOP:",
  "authUrl": "https://api.prod.whoop.com/oauth/oauth2/auth?...",
  "callbackUrl": "http://localhost:3000/callback",
  "nextStep": "After authorizing in the browser, call complete-whoop-auth to capture the tokens."
}

Workflow

1. Call authenticate-whoop to get the auth URL
2. Open the URL in your browser
3. Authorize access on WHOOP's website
4. Call complete-whoop-auth to capture the tokens

---

complete-whoop-auth

Complete the OAuth flow after the user has authorized in the browser. Starts a local server to capture the callback and exchanges the authorization code for tokens.

Parameters

Parameter	Type	Required	Default	Description
port	number	No	3000	Must match the port used in authenticate-whoop
timeout	number	No	300	Seconds to wait for callback

Response

{
  "status": "success",
  "message": "Successfully authenticated with WHOOP!",
  "expiresIn": 3600,
  "scopes": ["read:profile", "read:sleep", "read:recovery", "offline"],
  "note": "Tokens are now active. You can use other WHOOP tools to access your data."
}

Troubleshooting

Issue	Solution
Timeout	Make sure you completed authorization in browser within 5 minutes
Port in use	Choose a different port number
Connection refused	Check firewall settings

---

check-auth-status

Verify the current authentication state with the WHOOP API. Useful for debugging connection issues.

Parameters

None

Example Questions

• "Is my WHOOP connection working?"
• "Check if my token is still valid"
• "Why can't I access my data?"

Response

{
  "configured": true,
  "hasRefreshToken": true,
  "tokenExpired": false,
  "expiresAt": "2024-12-17T12:00:00.000Z",
  "apiStatus": "valid"
}

API Status Values

Value	Meaning
valid	Token works, API is accessible
invalid or expired	Token rejected by WHOOP (401)
error: <code>	Other API error (e.g., rate limit)
connection error	Network or connection issue
not configured	No tokens in environment

---

OAuth Scopes

When authenticating, these scopes are requested:

Scope	Access
read:profile	User profile and body measurements
read:sleep	Sleep sessions and scores
read:recovery	Recovery scores and HRV
read:workout	Workout activities
read:cycles	Daily physiological cycles
offline	Refresh token for automatic renewal

All scopes are read-only. Wellpipe cannot modify your WHOOP data.

---

Token Lifecycle

Access Tokens

• Expire after 1 hour
• Automatically refreshed using the refresh token
• Used for all API requests

Refresh Tokens

• Last for 7 days (or until revoked)
• Used to get new access tokens
• Stored encrypted in the cloud version

Token Expiry

If your tokens expire and cannot be refreshed:

1. Cloud: Return to dashboard and click "Reconnect"
2. CLI: Run wellpipe auth whoop to re-authenticate