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

Open app.vidoc.dev or your custom deployment URL (the web app URL from your admin for on-premises installations)
Select your project
Navigate to Project switcher > 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.

Base URL

Select the API address of your deployment before you run an example. Set VIDOC_API_URL without a trailing slash or /v1:

Vidoc Cloud
Self-hosted

export VIDOC_API_URL="https://api.vidoc.dev"

Replace the example address with the API address from your admin:

export VIDOC_API_URL="https://api.example.com"

Use a key from this installation. Send it only to your installation’s API.

The REST examples use VIDOC_API_KEY for the key and pass it explicitly in the header. The CLI uses VIDOC_TOKEN. Keep these values in your shell or CI secret store. Every API route below starts with /v1.

Authentication Method

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

curl "${VIDOC_API_URL:?Set VIDOC_API_URL to your deployment URL}/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.

The MCP server uses a separate endpoint at /mcp. It requires Authorization: Bearer <key> and accepts only user API keys. Refer to MCP setup to connect your coding agent.

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/scans`, `GET /v1/codebase`, `GET /v1/codebase/:codebaseId`, `GET /v1/codebase/:codebaseId/files`	Every role
`issue:update_status`	`PATCH /v1/issues/:instanceId`, `PATCH /v1/issues`	`developer`, `security_engineer`, `admin`
`codebase:scan`	`POST /v1/scan-workflows/start`, `POST /v1/scans`	`developer`, `security_engineer`, `admin`
`org:manage_scans`	`POST /v1/scans` with `mode` `fresh` or `revalidate`	`admin`

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

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 /v1/scans answers 202, because the scan runs after the response. Other 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

Error bodies include statusCode, message, timestamp, and path. Authentication, permission, issue, and scan-list errors also provide a machine-readable code. Use code when it is present, rather than matching the message text. Some older routes provide error, the HTTP status text, without code.

{
  "statusCode": 404,
  "message": "Issue not found",
  "code": "issue_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,
  "code": "validation_failed",
  "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`	The key’s user lacks a permission or no longer has project access. `Status changes need a user API key` means a status update used a system, GitHub, or legacy token. Check `code` for the reason.
`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

The issue and scan-list query schemas reject unknown parameters with 400 and code: unknown_parameter. Other validation errors use validation_failed. Common codes are token_missing, token_invalid, permission_missing, project_access_denied, user_token_required, issue_not_found, and codebase_not_found.

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 apiUrl = process.env.VIDOC_API_URL;
if (!apiUrl) throw new Error('Set VIDOC_API_URL to your deployment URL');

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

if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const data = await response.json();

Python

import requests
import os

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

response.raise_for_status()
data = response.json()

cURL

curl "${VIDOC_API_URL:?Set VIDOC_API_URL to your deployment URL}/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

Deployment

Integrations

Pull request reviews

Web app

CLI

API reference

Reference

API Authentication

Getting an API Key

Base URL

Authentication Method

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

​Base URL

​Authentication Method

​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

Base URL

Authentication Method

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