# Step-by-Step Authentication Guide
Detailed, comprehensive guide to authenticating with Strava API step by step.
## Overview
This guide walks you through every step of the authentication process, with expected results and troubleshooting tips at each stage.
## Prerequisites Checklist
Before starting, ensure you have:
- ✅ Active Strava account
- ✅ Created Strava API application at [Strava API Settings](https://www.strava.com/settings/api)
- ✅ Set Authorization Callback Domain to `localhost`
- ✅ Copied Client ID and Client Secret
## Step 1: Check Current Authentication Status
**Purpose:** Determine what's already configured and what needs to be done.
**Prompt:**
```
Check my Strava authentication status
```
**Tool:**
```python
check_auth_status()
```
**Expected Results:**
**If not configured:**
```json
{
"is_configured": false,
"has_client_id": false,
"has_client_secret": false,
"has_refresh_token": false,
"message": "Authentication not configured. Please save credentials and complete authentication."
}
```
**If partially configured:**
```json
{
"is_configured": false,
"has_client_id": true,
"has_client_secret": true,
"has_refresh_token": false,
"message": "Credentials found but refresh token missing. Complete authentication to get refresh token."
}
```
**If fully configured:**
```json
{
"is_configured": true,
"has_client_id": true,
"has_client_secret": true,
"has_refresh_token": true,
"message": "Authentication is fully configured and ready to use!"
}
```
**What to do:**
- If `has_refresh_token: true`, you're done! Skip to Step 7.
- If credentials are missing, proceed to Step 2.
- If credentials exist but no refresh token, skip to Step 3.
---
## Step 2: Save Your Credentials
**Purpose:** Store your Client ID and Client Secret for future use.
**Prompt:**
```
Save my Strava credentials: client_id=YOUR_CLIENT_ID, client_secret=YOUR_CLIENT_SECRET
```
**Tool:**
```python
save_credentials(
client_id="YOUR_CLIENT_ID",
client_secret="YOUR_CLIENT_SECRET"
)
```
**Expected Result:**
```json
{
"status": "success",
"message": "Credentials saved successfully",
"client_id_preview": "12345...",
"env_file": ".env"
}
```
**What happens:**
- ✅ Client ID and Secret are saved to `.env` file
- ✅ Credentials are now available for future authentication steps
**Troubleshooting:**
- **Error: "Failed to save credentials"**: Check write permissions on `.env` file
- **Error: "Invalid client ID format"**: Verify your Client ID is numeric
---
## Step 3: Get Authorization URL
**Purpose:** Obtain the URL you need to visit to authorize the application.
**Prompt:**
```
Get the Strava authorization URL
```
**Tool:**
```python
get_auth_url()
```
**Expected Result:**
```
https://www.strava.com/oauth/authorize?client_id=YOUR_ID&redirect_uri=http://localhost&response_type=code&scope=read,activity:read,activity:read_all,profile:read_all
```
**What to do:**
1. Copy the entire URL from the response
2. Keep it ready for the next step
**Troubleshooting:**
- **Error: "Client ID not found"**: Make sure you completed Step 2 first
- **Error: "Invalid redirect URI"**: Verify your Strava app has `localhost` as callback domain
---
## Step 4: Visit URL and Authorize
**Purpose:** Grant the application permission to access your Strava data.
**Steps:**
1. **Open the authorization URL** from Step 3 in your web browser
2. **Log in** to Strava if you're not already logged in
3. **Review permissions** - the app will request:
- Read your profile information
- Read your activities
- Read all activity details
4. **Click "Authorize"** to grant permissions
5. **Wait for redirect** - you'll be redirected to a URL like:
```
http://localhost/?code=abc123xyz789def456&scope=read,activity:read,activity:read_all,profile:read_all
```
**Important Notes:**
- The redirect happens automatically
- You may see a "Page not found" error - this is normal! The important part is the URL in your browser's address bar
- The authorization code is in the `code` parameter
---
## Step 5: Copy Authorization Code
**Purpose:** Extract the authorization code from the redirect URL.
**Steps:**
1. **Look at your browser's address bar** after the redirect
2. **Find the `code` parameter** in the URL
3. **Copy only the code value** (everything after `code=` and before `&`)
**Example:**
- Redirect URL: `http://localhost/?code=abc123xyz789def456&scope=read,activity:read,activity:read_all,profile:read_all`
- Code to copy: `abc123xyz789def456`
**Important:**
- ⚠️ Authorization codes expire quickly (usually within 10 minutes)
- ⚠️ Copy the code immediately after authorization
- ⚠️ The code is long and case-sensitive - copy it exactly
**Troubleshooting:**
- **No code in URL**: Make sure you clicked "Authorize" and were redirected
- **Code looks incomplete**: Check if the URL was truncated - try copying from the address bar directly
---
## Step 6: Complete Authentication
**Purpose:** Exchange the authorization code for access and refresh tokens.
**Prompt:**
```
Complete Strava authentication with code: YOUR_CODE_HERE
```
**Tool:**
```python
complete_strava_auth(auth_code="YOUR_CODE_HERE")
```
**Replace `YOUR_CODE_HERE` with the code you copied in Step 5.**
**Expected Result:**
```json
{
"status": "success",
"message": "Strava authentication completed successfully!",
"refresh_token_preview": "b18579cb2...",
"env_file": ".env",
"next_steps": [
"Restart the MCP server to load the new credentials",
"Use check_auth_status() to verify the setup",
"Start using Strava API tools"
]
}
```
**What happens:**
- ✅ Authorization code is exchanged for access and refresh tokens
- ✅ Refresh token is saved to `.env` file
- ✅ Access token is saved (optional, expires quickly)
- ✅ Token expiration timestamp is saved (optional)
**Troubleshooting:**
**Error: "Invalid authorization code"**
- Code may have expired (they expire quickly)
- Make sure you copied the entire code value
- Try the authorization flow again (go back to Step 3)
**Error: "Error exchanging code for token"**
- Double-check your Client ID and Client Secret
- Verify the code is correct
- Make sure redirect URI matches Strava settings (`http://localhost`)
- Check that your Strava app is active and not revoked
**Error: "Failed to save refresh token"**
- Check write permissions on `.env` file
- Verify the server has write access to the directory
- Check server logs for detailed error messages
---
## Step 7: Restart Server
**Purpose:** Load the new refresh token into the running server.
**Steps:**
1. **Stop the current server** (if running):
```bash
# Find and kill the process
pkill -f "src/server.py"
# Or if running on a specific port:
lsof -ti:9186 | xargs kill
```
2. **Start the server again**:
```bash
uv run src/server.py --transport sse --port 9186
```
**What happens:**
- Server reads the new `.env` file
- Refresh token is loaded into memory
- Server is ready to make API calls
---
## Step 8: Verify Authentication
**Purpose:** Confirm that authentication is complete and working.
**Prompt:**
```
Check my Strava authentication status
```
**Tool:**
```python
check_auth_status()
```
**Expected Result:**
```json
{
"is_configured": true,
"has_client_id": true,
"has_client_secret": true,
"has_refresh_token": true,
"message": "Authentication is fully configured and ready to use!"
}
```
**If you see `has_refresh_token: true`, you're all set! 🎉**
**What to do next:**
- Try querying your activities: "What are my recent activities?"
- Test training analysis: "Analyze my weekly training"
- Explore all available tools from the README
---
## Quick Reference: All Steps
1. ✅ `Check my Strava authentication status`
2. ✅ `Save my Strava credentials: client_id=X, client_secret=Y`
3. ✅ `Get the Strava authorization URL`
4. ✅ [Visit URL, authorize, copy code]
5. ✅ `Complete Strava authentication with code: YOUR_CODE`
6. ✅ [Restart server]
7. ✅ `Check my Strava authentication status`
---
## Alternative: One-Step Method
If you prefer to do everything in one command:
**Tool:**
```python
get_strava_auth_token(
client_id="YOUR_CLIENT_ID",
client_secret="YOUR_CLIENT_SECRET",
auth_code="YOUR_AUTHORIZATION_CODE"
)
```
This combines Steps 2 and 6 into a single operation. You still need to:
1. Get the authorization URL (Step 3)
2. Visit and authorize (Step 4)
3. Copy the code (Step 5)
4. Use the one-step tool
5. Restart server (Step 7)
---
## Common Issues and Solutions
### Issue: "Page not found" after authorization
**Solution:** This is normal! The redirect goes to `localhost` which may not have a web server. Just copy the code from the URL.
### Issue: Code expired before I could use it
**Solution:** Authorization codes expire quickly. Complete Step 6 immediately after Step 5, or start over from Step 3.
### Issue: Server says "not configured" after restart
**Solution:**
- Verify `.env` file exists and contains `STRAVA_REFRESH_TOKEN`
- Check that the server is reading from the correct directory
- Try `check_auth_status()` to see what's missing
### Issue: "Invalid redirect URI" error
**Solution:** Make sure your Strava app has `localhost` (without `http://`) set as the Authorization Callback Domain.
---
## Next Steps
- Read [QUICK_START.md](QUICK_START.md) for a condensed version
- See [AUTHENTICATION.md](AUTHENTICATION.md) for authentication concepts
- Check [GET_REFRESH_TOKEN.md](GET_REFRESH_TOKEN.md) if you already have credentials
