> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcprank.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API authentication methods

# Authentication

MCP Rank uses API keys for authentication.

## API Keys

Include your API key in the `X-API-Key` header:

```bash theme={null}
curl https://api.mcprank.com/v1/search \
  -H "X-API-Key: sk_mcp_rank_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "send email"}'
```

### Getting an API Key

1. Sign up at [mcprank.com](https://mcprank.com/sign-up)
2. Go to [Dashboard > API Keys](https://mcprank.com/dashboard/api-keys)
3. Click "Create New Key"
4. Copy and store the key securely

<Warning>
  API keys are only shown once when created. Store them securely.
</Warning>

### Key Format

API keys follow this format:

```
sk_mcp_rank_[32 hex characters]
```

Example: `sk_mcp_rank_a1b2c3d4e5f6789012345678abcdef01`

## MCP Identity Tokens

For proxy requests, you also need an MCP Identity token (JWT) in the `Authorization` header:

```bash theme={null}
curl https://api.mcprank.com/v1/proxy/google/gmail/v1/users/me/profile \
  -H "X-API-Key: sk_mcp_rank_..." \
  -H "Authorization: Bearer eyJ..."
```

### Token Structure

MCP Identity tokens are JWTs with these claims:

```json theme={null}
{
  "iss": "https://mcprank.com",
  "sub": "user_123",
  "aud": "mcp-servers",
  "exp": 1704067200,
  "iat": 1704063600,
  "jti": "tok_abc123",
  "api_key_id": "key_def456",
  "connected_services": ["google"]
}
```

### Getting Tokens

Tokens are returned when a user completes the OAuth flow:

```
GET /v1/auth/google/initiate?redirect_uri=https://yourapp.com/callback
-> Redirects to Google
-> Returns to: https://yourapp.com/callback?access_token=eyJ...&refresh_token=...
```

### Refreshing Tokens

Access tokens expire after 1 hour. Use the refresh token to get new ones:

```bash theme={null}
curl -X POST https://api.mcprank.com/v1/auth/token \
  -H "X-API-Key: sk_mcp_rank_..." \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token&refresh_token=..."
```

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Keep Keys Secret" icon="lock">
    Never commit API keys to version control or expose them in client-side code.
  </Card>

  <Card title="Use Environment Variables" icon="terminal">
    Store keys in environment variables, not in code.
  </Card>

  <Card title="Rotate Keys Regularly" icon="rotate">
    Rotate API keys periodically, especially if compromised.
  </Card>

  <Card title="Use Minimal Scopes" icon="shield">
    Only request the permissions your app needs.
  </Card>
</CardGroup>