Skip to main content
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
  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 for detailed management.

​
Authentication Methods

Include the API key in the Authorization header: 
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: 
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

HeaderRequiredDescription
AuthorizationYesBearer your-api-key
Content-TypeYes (POST/PUT)application/json

​
Request Body

POST and PUT requests use JSON: 
{
  "codebaseId": "abc123",
  "branch": "main"
}

​
Response Format

​
Success Response

{
  "id": "scan-123",
  "status": "pending",
  "createdAt": "2024-01-15T10:30:00Z"
}

​
Error Response

{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}

​
Error Codes

CodeDescription
401Invalid or missing API key
403Key doesn’t have permission
404Resource not found
429Rate limit exceeded
500Server error

​
Rate Limits

OperationLimit
Start scan10 per minute
Get status100 per minute
List issues100 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

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

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

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

API Keys

Manage API keys

Scanning API

Start scans via API

Issues API

Access issues via API

CLI Authentication

CLI auth methods