API Authentication

The Vidoc REST API authenticates every request with an API key. The key names one project: every route reads and writes that project only.

Getting an API Key

Go to app.vidoc.dev
Select your project
Navigate to Settings → API Keys
Click “Create new key”, enter a name and pick an expiry
Copy the key and store it securely

API keys expire. The default expiry is 1 month. For automation, pick 6 months or 1 year. An expired key answers 401 Invalid or expired token and nothing else warns you.

See API Keys for detailed management.

Authentication Method

Send the key in the x-vidoc-token header. This is the only header the REST API reads.

curl "https://api.vidoc.dev/v1/issues?limit=1" \
  -H "x-vidoc-token: $VIDOC_API_KEY"

The REST API does not read Authorization: Bearer <key> or X-API-Key. A request that sends the key in one of those headers gets 401 Token is missing.

Base URL

All API requests use:

https://api.vidoc.dev

Every route lives under the /v1 prefix, for example https://api.vidoc.dev/v1/issues.

Permissions

An API key carries the role of the user who created it. Each route requires one permission:

Permission	Routes	Roles that have it
`issue:view`	`GET /v1/issues`, `GET /v1/issues/:instanceId`, `GET /v1/issues/:instanceId/fix-prompt`, `GET /v1/scan-workflows/:scanId/status`, `GET /v1/codebase`	Every role
`issue:update_status`	`PATCH /v1/issues/:instanceId`, `PATCH /v1/issues`	`developer`, `security_engineer`, `admin`
`codebase:scan`	`POST /v1/scan-workflows/start`	`developer`, `security_engineer`, `admin`

A read_only member cannot create API keys, so every key created in the dashboard has at least the developer role. Status changes also need a key that belongs to a user, because the change records its author. Keys created in the dashboard are user keys. System, GitHub and legacy tokens have no user and get 403 Status changes need a user API key.

Request Format

Headers

Header	Required	Description
`x-vidoc-token`	Yes	Your API key
`Content-Type`	Yes (POST/PATCH)	`application/json`

Request Body

POST and PATCH requests use JSON:

{
  "codebaseId": "019f8a1b-0c2d-73e4-a5f6-7b8c9d0e1f2a",
  "branch": "main"
}

Response Format

Success Response

POST routes answer 201, every other route answers 200, always with a JSON body. For example, POST /v1/scan-workflows/start returns:

{
  "id": "019f8a10-9e8d-7c6b-a5f4-3e2d1c0b9a87"
}

Error Response

Every error has one body shape. statusCode and message say what happened; timestamp and path are always present, and most errors also carry error, the HTTP status text.

{
  "statusCode": 404,
  "message": "Issue not found",
  "error": "Not Found",
  "timestamp": "2026-09-18T16:17:11.702Z",
  "path": "/v1/issues/019f8a2c-4b1e-7d3a-9c5e-2f1a6b8d4e70"
}

A validation error (400) has the message Validation failed and an errors array. Each item names the field (path) and the reason (message):

{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": [
    {
      "code": "too_big",
      "path": ["limit"],
      "message": "Number must be less than or equal to 100"
    }
  ],
  "timestamp": "2026-09-18T16:17:11.702Z",
  "path": "/v1/issues?limit=101"
}

Error Codes

Code	Description
`400`	The body or the query fails validation. Read the `errors` array
`401`	`Token is missing`: no `x-vidoc-token` header. `Invalid or expired token`: the key is unknown, expired, or its project was deleted
`403`	`Missing required permission(s): ...`: the key’s role lacks the permission. `Status changes need a user API key`: a `PATCH` with a system, GitHub or legacy token
`404`	`Issue not found`, `Codebase not found` or `Scan not found`. The resource does not exist, or it belongs to another project
`500`	Server error. The body says `Internal server error` and carries no detail

Rate Limits

The API does not rate-limit requests today, so there are no 429 answers and no X-RateLimit-* headers. Rate limiting is planned. Until then:

Keep bulk status updates at 100 items or fewer per request, and do not run many bulk requests at the same time
Poll a scan status every few seconds, not in a tight loop

Code Examples

JavaScript/Node.js

const response = await fetch(
  'https://api.vidoc.dev/v1/issues?status=open&severity=critical,high',
  {
    headers: {
      'x-vidoc-token': process.env.VIDOC_API_KEY,
    },
  },
);

const data = await response.json();

Python

import requests
import os

response = requests.get(
    'https://api.vidoc.dev/v1/issues',
    headers={'x-vidoc-token': os.environ['VIDOC_API_KEY']},
    params={'status': 'open', 'severity': 'critical,high'},
)

data = response.json()

cURL

curl "https://api.vidoc.dev/v1/issues?status=open&severity=critical,high" \
  -H "x-vidoc-token: $VIDOC_API_KEY"

Security Best Practices

Never commit API keys - Use environment variables
Pick the shortest expiry that fits the job - Keys expire at the chosen preset; plan the rotation before that date
Use separate keys - One per environment/purpose
Create keys from the right account - A key carries the role of its creator; create automation keys from an account with the smallest role that has the needed permission
Delete 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

Get Started

Dashboard

GitHub Integration

CLI

Security Categories

Settings

API Reference

Other Integrations

API Authentication

Getting an API Key

Authentication Method

Base URL

Permissions

Request Format

Headers

Request Body

Response Format

Success Response

Error Response

Error Codes

Rate Limits

Code Examples

JavaScript/Node.js

Python

cURL

Security Best Practices

API Keys

Scanning API

Issues API

CLI Authentication

​Getting an API Key

​Authentication Method

​Base URL

​Permissions

​Request Format

​Headers

​Request Body

​Response Format

​Success Response

​Error Response

​Error Codes

​Rate Limits

​Code Examples

​JavaScript/Node.js

​Python

​cURL

​Security Best Practices

​Related Pages

API Keys

Scanning API

Issues API

CLI Authentication

Getting an API Key

Authentication Method

Base URL

Permissions

Request Format

Headers

Request Body

Response Format

Success Response

Error Response

Error Codes

Rate Limits

Code Examples

JavaScript/Node.js

Python

cURL

Security Best Practices

Related Pages