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

# Authentication

> How to authenticate with the VecTrade API and manage API keys securely.

# Authentication

All VecTrade API requests require authentication with your VecTrade API key.

Use `X-API-Key` as the primary header for hosted/public API traffic.
Some direct deployments also accept `Authorization: Bearer vq_...`, but `X-API-Key` is the stable default.

## API Key Format

API keys follow the format `vq_` followed by a random string:

```
X-API-Key: vq_aaJFCQFZpv8BZU_RuLLAHlXP_Md3A55GhNeVtnn3Ykk
```

## Making Authenticated Requests

### cURL

```bash theme={null}
curl -H "X-API-Key: $VECTRADE_API_KEY" \
  https://api.vectrade.io/v1/vq/quotes/AAPL
```

Alternative header form (when supported by your deployment):

```bash theme={null}
curl -H "Authorization: Bearer $VECTRADE_API_KEY" \
  https://api.vectrade.io/v1/vq/quotes/AAPL
```

### Python SDK

```python theme={null}
from vectrade import VecTrade

# Reads VECTRADE_API_KEY from environment automatically
client = VecTrade()

# Or pass explicitly
client = VecTrade(api_key="vq_your_key_here")
```

### TypeScript SDK

```typescript theme={null}
import { VecTrade } from "@vectrade/sdk";

// Reads VECTRADE_API_KEY from environment
const client = new VecTrade();

// Or pass explicitly
const client = new VecTrade({ apiKey: "vq_your_key_here" });
```

<Warning>
  Never hardcode API keys in source code. Use environment variables or secret managers.
</Warning>

## Key Security Best Practices

1. **Rotate regularly** — Generate new keys and revoke old ones monthly
2. **Use scoped keys** — Create keys with minimum required permissions
3. **Separate environments** — Use different keys for dev/staging/production
4. **Monitor usage** — Check the dashboard for unexpected activity
5. **Use secrets managers** — Store keys in Vault, AWS Secrets Manager, etc.

## Key Permissions (Scopes)

| Scope               | Access                                       |
| ------------------- | -------------------------------------------- |
| `quotes:read`       | Real-time and historical quotes              |
| `fundamentals:read` | Company financials, profiles, and statements |
| `technicals:read`   | Technical indicators and scoring             |
| `news:read`         | Financial news articles                      |
| `analyst:read`      | Analyst consensus, price targets, ratings    |
| `earnings:read`     | Earnings history and calendar                |
| `insider:read`      | Insider trading activity                     |
| `options:read`      | Options chain data                           |
| `sentiment:read`    | Market sentiment data                        |
| `etf:read`          | ETF profiles and holdings                    |

## Error Responses

Missing or invalid keys return `401 Unauthorized`:

```json theme={null}
{
  "error": {
    "type": "authentication_error",
    "message": "Missing or invalid API key",
    "docs_url": "https://docs.vectrade.io/guides/authentication"
  }
}
```

Insufficient permissions return `403 Forbidden`:

```json theme={null}
{
  "error": {
    "type": "permission_error",
    "message": "API key does not have permission. Required scope: ai:read"
  }
}
```

## SDK Error Handling

```python theme={null}
from vectrade import VecTrade, AuthenticationError

try:
    client = VecTrade(api_key="invalid_key")
    client.quotes.get("AAPL")
except AuthenticationError as e:
    print(f"Auth failed: {e.message}")
    print(f"Request ID: {e.request_id}")
```