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

# API Authentication

> Authenticate requests to the Vidoc REST API

The Vidoc API uses API keys for authentication. All requests must include a valid API key.

## Getting an API Key

1. Go to [app.vidocsecurity.com](https://app.vidocsecurity.com)
2. Select your project
3. Navigate to **Settings** → **API Keys**
4. Click **"Create API Key"**
5. Copy and store the key securely

See [API Keys](/settings/api-keys) for detailed management.

## Authentication Methods

### Bearer Token (Recommended)

Include the API key in the `Authorization` header:

```bash theme={null}
curl -X POST https://api.vidocsecurity.com/v1/scan-workflows/start \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"codebaseId": "...", "branch": "main"}'
```

### Header Token

Alternatively, use the `X-API-Key` header:

```bash theme={null}
curl -X POST https://api.vidocsecurity.com/v1/scan-workflows/start \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"codebaseId": "...", "branch": "main"}'
```

## Base URL

All API requests use:

```
https://api.vidocsecurity.com/v1
```

## Request Format

### Headers

| Header          | Required       | Description           |
| --------------- | -------------- | --------------------- |
| `Authorization` | Yes            | `Bearer your-api-key` |
| `Content-Type`  | Yes (POST/PUT) | `application/json`    |

### Request Body

POST and PUT requests use JSON:

```json theme={null}
{
  "codebaseId": "abc123",
  "branch": "main"
}
```

## Response Format

### Success Response

```json theme={null}
{
  "id": "scan-123",
  "status": "pending",
  "createdAt": "2024-01-15T10:30:00Z"
}
```

### Error Response

```json theme={null}
{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}
```

## Error Codes

| Code  | Description                 |
| ----- | --------------------------- |
| `401` | Invalid or missing API key  |
| `403` | Key doesn't have permission |
| `404` | Resource not found          |
| `429` | Rate limit exceeded         |
| `500` | Server error                |

## Rate Limits

| Operation   | Limit          |
| ----------- | -------------- |
| Start scan  | 10 per minute  |
| Get status  | 100 per minute |
| List issues | 100 per minute |

Rate limit headers are included in responses:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705315200
```

## Code Examples

### JavaScript/Node.js

```javascript theme={null}
const response = await fetch('https://api.vidocsecurity.com/v1/scan-workflows/start', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.VIDOC_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    codebaseId: 'abc123',
    branch: 'main',
  }),
});

const data = await response.json();
```

### Python

```python theme={null}
import requests
import os

response = requests.post(
    'https://api.vidocsecurity.com/v1/scan-workflows/start',
    headers={
        'Authorization': f'Bearer {os.environ["VIDOC_API_KEY"]}',
        'Content-Type': 'application/json',
    },
    json={
        'codebaseId': 'abc123',
        'branch': 'main',
    }
)

data = response.json()
```

### cURL

```bash theme={null}
curl -X POST https://api.vidocsecurity.com/v1/scan-workflows/start \
  -H "Authorization: Bearer $VIDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"codebaseId": "abc123", "branch": "main"}'
```

## Security Best Practices

1. **Never commit API keys** - Use environment variables
2. **Rotate keys regularly** - Create new keys every 90 days
3. **Use separate keys** - One per environment/purpose
4. **Monitor usage** - Check last used timestamps
5. **Revoke compromised keys** - Immediately if exposed

## Related Pages

<CardGroup cols={2}>
  <Card title="API Keys" icon="key" href="/settings/api-keys">
    Manage API keys
  </Card>

  <Card title="Scanning API" icon="magnifying-glass" href="/api/scanning">
    Start scans via API
  </Card>

  <Card title="Issues API" icon="bug" href="/api/issues">
    Access issues via API
  </Card>

  <Card title="CLI Authentication" icon="terminal" href="/cli/authentication">
    CLI auth methods
  </Card>
</CardGroup>