# Authentication Guide
Complete guide to authenticating with the Strava API and setting up your refresh token.
## Overview
The Strava MCP Server uses OAuth 2.0 to authenticate with the Strava API. The authentication process involves:
1. Getting your Strava API credentials (Client ID and Client Secret)
2. Obtaining an authorization code from Strava
3. Exchanging the authorization code for access and refresh tokens
4. Saving the refresh token for future use
## Prerequisites
1. **Strava Account**: You need an active Strava account
2. **API Application**: Create an application at [Strava API Settings](https://www.strava.com/settings/api)
3. **Callback Domain**: Set Authorization Callback Domain to `localhost`
## Getting Your API Credentials
1. Visit [Strava API Settings](https://www.strava.com/settings/api)
2. Click "Create App" or select an existing application
3. Fill in the required information:
- **Application Name**: Any name (e.g., "My MCP Server")
- **Category**: Choose any category
- **Website**: Optional
- **Authorization Callback Domain**: `localhost` (important!)
4. Click "Create"
5. Copy your **Client ID** and **Client Secret**
## Authentication Methods
### Method 1: One-Step Authentication (Recommended)
This method completes authentication in a single step:
**Tool:**
```python
get_strava_auth_token(
client_id="YOUR_CLIENT_ID",
client_secret="YOUR_CLIENT_SECRET",
auth_code="AUTHORIZATION_CODE"
)
```
**Steps:**
1. Get the authorization URL (see Method 2, Step 2)
2. Visit the URL and authorize
3. Copy the authorization code from the redirect URL
4. Call `get_strava_auth_token()` with all three values
**What it does:**
- ✅ Saves Client ID and Secret to `.env`
- ✅ Exchanges authorization code for tokens
- ✅ Saves refresh token to `.env`
- ✅ Returns confirmation
### Method 2: Step-by-Step Authentication
This method breaks the process into separate steps:
#### Step 1: Save Credentials
**Tool:**
```python
save_credentials(
client_id="YOUR_CLIENT_ID",
client_secret="YOUR_CLIENT_SECRET"
)
```
This saves your credentials to `.env` for future use.
#### Step 2: Get Authorization URL
**Tool:**
```python
get_auth_url(redirect_uri="http://localhost")
```
This returns a URL like:
```
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
```
#### Step 3: Authorize the Application
1. Copy the authorization URL from Step 2
2. Paste it in your browser
3. Log in to Strava if prompted
4. Click "Authorize" to grant permissions
5. You'll be redirected to a URL like:
```
http://localhost/?code=abc123xyz789&scope=read,activity:read,activity:read_all,profile:read_all
```
#### Step 4: Copy Authorization Code
From the redirect URL, copy the `code` parameter value:
- Example URL: `http://localhost/?code=abc123xyz789&scope=...`
- Copy: `abc123xyz789`
**Important:** Authorization codes expire quickly (usually within 10 minutes), so copy it immediately.
#### Step 5: Complete Authentication
**Tool:**
```python
complete_strava_auth(auth_code="abc123xyz789")
```
This will:
- ✅ Exchange the authorization code for access and refresh tokens
- ✅ Save the refresh token to `.env`
- ✅ Return confirmation
#### Step 6: Restart Server
After successful authentication, restart the MCP server to load the new credentials:
```bash
# Kill existing server (if running)
pkill -f "src/server.py"
# Start server again
uv run src/server.py --transport sse --port 9186
```
## Verifying Authentication
Check if authentication is set up correctly:
**Tool:**
```python
check_auth_status()
```
**Expected Response:**
```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!"
}
```
## Environment Variables
After authentication, your `.env` file will contain:
```env
STRAVA_CLIENT_ID=your_client_id
STRAVA_CLIENT_SECRET=your_client_secret
STRAVA_REFRESH_TOKEN=your_refresh_token_here
STRAVA_ACCESS_TOKEN=access_token_here
STRAVA_EXPIRES_AT=timestamp_here
```
**Important:** The refresh token is the most critical value - it's used to automatically obtain new access tokens when they expire.
## Remote Server Support
✅ **Authentication works with remote servers via SSE!**
The OAuth redirect goes to `http://localhost` (on YOUR machine), not the server. So you can:
- Run the server remotely (via SSE)
- Get the auth URL from the remote server
- Visit it in your browser (on your local machine)
- Get redirected to your localhost
- Copy the code and send it back to the remote server
The `.env` file is saved on the **server side**, so make sure the server has write permissions.
## Troubleshooting
### "Client ID not found"
- Make sure you've saved credentials using `save_credentials()` or set environment variables
- Check that `.env` file exists and contains `STRAVA_CLIENT_ID`
### "Invalid authorization code"
- Authorization codes expire quickly (usually within 10 minutes)
- Make sure you're using a fresh code from the redirect URL
- Try the authorization flow again
### "Error exchanging code for token"
- Double-check your Client ID and Client Secret
- Verify the authorization code is correct
- Make sure redirect URI matches Strava settings (`http://localhost`)
- Ensure your Strava application has the correct callback domain set
### "Refresh token not found after authentication"
- Check that `.env` file has write permissions
- Verify the server has write access to the directory
- Check server logs for any errors during token exchange
## Security Best Practices
1. **Never commit `.env` file**: Add it to `.gitignore`
2. **Keep credentials secure**: Don't share your Client Secret or refresh token
3. **Use environment variables**: For production, use environment variables instead of `.env` file
4. **Rotate tokens**: If compromised, revoke access in Strava settings and re-authenticate
## Next Steps
- See [QUICK_START.md](QUICK_START.md) for a quick overview
- See [STEP_BY_STEP_AUTH.md](STEP_BY_STEP_AUTH.md) for detailed step-by-step instructions
- See [GET_REFRESH_TOKEN.md](GET_REFRESH_TOKEN.md) if you already have credentials set
