Skip to main content
API keys authenticate the Vidoc CLI, REST API, and MCP connections. Each key is scoped to one project and carries the role of the user who created it.

​
Creating an API Key

  1. Open app.vidoc.dev or your custom deployment URL, then select your project
  2. Navigate to Project switcher > API keys
  3. Click “Create new key”
  4. Enter a name (e.g., “CI pipeline”, “Local Development”)
  5. Pick an expiry: 1 day, 1 week, 1 month (default), 6 months or 1 year
  6. Confirm and copy the key
Keys expire at the chosen preset, and the default is only 1 month. For CI/CD and other automation, pick 6 months or 1 year. An expired key answers 401 Invalid or expired token; nothing else warns you.
The list shows each key masked. Reveal shows the value, and the copy button copies it, so you can read a key again later.

​
API Key Properties

​
Using API Keys

​
CLI Authentication

The CLI reads VIDOC_TOKEN by default. To use a different variable, set token_env in a CLI profile.
Self-hosted: set VIDOC_API_URL to your own API address before you run the CLI. For interactive login, use vidoc login --url https://api.example.com with your installation address. Refer to Install and log in.

​
API Authentication

First, select your deployment API address and set VIDOC_API_URL. Send the key in the x-vidoc-token header:
The REST API does not read Authorization: Bearer. See API Authentication for the routes and the error contract.

​
MCP Authentication

The MCP server accepts user API keys in the Authorization: Bearer <key> header at /mcp. System, GitHub, and legacy tokens cannot connect. Each connection has access to the project of the key. Refer to MCP setup for Claude Code, Cursor, and MCP Inspector configuration.

​
Managing API Keys

​
View Keys

  1. Go to Project switcher > API keys
  2. My API Keys lists the keys you created in this project, with their expiry and creation dates
  3. Legacy Tokens lists older tokens without an owner (type legacy) and tokens the platform created (system, github). You see your own; admins see all

​
Delete a Key

  1. Find the key in the list
  2. Click “Delete”
  3. Confirm
Deleting needs the permission api_key:delete (roles security_engineer and admin). A developer can create keys but not delete them.
Deleting a key immediately invalidates it. CI/CD pipelines using the key will fail.

​
Rotate Keys

To rotate a key before it expires:
  1. Create a new key
  2. Update your CI/CD pipelines with the new key
  3. Verify scans work with the new key
  4. Delete the old key

​
Best Practices

​
Use Descriptive Names

Name keys by their purpose:
  • github-actions-prod
  • gitlab-ci-staging
  • local-dev-alice

​
One Key Per Purpose

Create separate keys for:
  • Each CI/CD pipeline
  • Each developer (for local development)
  • Each environment
This allows granular revocation if a key is compromised.

​
Secure Storage

​
Plan for Expiry

Every key has an expiry date:
  • Pick 6 months or 1 year for production pipelines and note the date
  • Rotate before the expiry date, after a team member departs, and after any suspected compromise
  • Use 1 day or 1 week for one-off scripts

​
Permissions

A key acts with the role of the user who created it. The REST API checks one permission per route: A read_only member cannot create keys, so every key created in the dashboard has at least the developer role. Status changes and scan starts with POST /v1/scans also need a key with an owner: keys from My API Keys qualify; legacy, system and GitHub tokens do not. Roles are managed through Team Members.

​
Rate Limits

The API does not rate-limit requests today. Rate limiting is planned; until then, keep bulk requests at 100 items or fewer and avoid tight polling loops.

​
Troubleshooting

​
”Token is missing”

The request has no x-vidoc-token header. The REST API does not read Authorization: Bearer or X-API-Key.

​
”Invalid or expired token”

  1. Verify the key was copied correctly, with no extra whitespace
  2. Check the Expires date in the list; create a new key if it has passed
  3. Ensure the key hasn’t been deleted
  4. Verify you’re using a key of the right project; a key of a deleted project is also invalid

​
”Missing required permission(s): …”

The role of the key’s creator lacks the permission for that route. Use a key created by a developer, security_engineer or admin.

​
”Status changes need a user API key”

The key has no owner (a legacy, system or GitHub token). Create a key from My API Keys in the dashboard.

CLI Authentication

CLI login methods

CI/CD Integration

Pipeline setup

Team Members

Manage access

API Reference

API documentation