Skip to content

Self-hosting

API keys and scopes

Create, use and revoke the API keys that let agents and scripts use a network-mode server.

Last updated:

You will learn#

  • what a key is, and which scopes it can have;
  • how to create one, use it from the CLI, MCP and HTTP, and revoke it;
  • how the rate limits apply.

The idea#

In network mode an agent or a script uses an API key that a signed-in user creates. The key has a secret of the form vvk_<id>.<secret>; only a hash is stored, and the secret is shown once, at creation. Its actor in the audit trail is key:<key id>.

ScopeAllows
readread projects, view frames, lint, read jobs
editapply edit batches, undo and redo, create projects
mediaimport media, remove assets, start transcription
renderstart exports
adminadminister users, keys and the trash

Scopes are independent: none implies another, admin included. The effective scopes of a request are the scopes of the key intersected with the present role of its owner, so demoting a user narrows their keys at once. A key can be limited to one project (not with admin). Rules of creation:

  • name of 1 to 60 characters, and scopes, a non-empty subset of the creator's scopes;
  • expires_in_days from 1 to 365, default 90 (1 to 30 when the key has admin);
  • at most 10 creations per hour per user and 50 unrevoked keys per user;
  • only a signed-in session can create a key: a key can never create a key.

Quick start#

Sign in to get a session, create a key with it and use the key. The Origin header is required on an unsafe request that uses the session cookie; use your APP_URL.

Terminal
APP=http://localhost:7878
curl -fsS -c jar.txt -H "Content-Type: application/json" -H "Origin: $APP" \
  -d '{"email": "admin@example.com", "password": "choose-a-long-password"}' "$APP/auth/login"
curl -fsS -b jar.txt -H "Content-Type: application/json" -H "Origin: $APP" \
  -d '{"name": "claude-code", "scopes": ["read", "edit", "media", "render"]}' "$APP/api/v1/keys"

The second answer holds the secret. Store it in a file only you can read, and point the client at the server:

Terminal
export VUKEM_VIDEO_URL=https://video.example.com
vukem-video project:list --key-file ~/.vukem-video-key

Or set VUKEM_VIDEO_KEY in the environment. There is no --key flag, because other users can see command-line arguments. The same variables make the stdio MCP server (vukem-video mcp) talk to the remote server.

Rate limits#

A key is limited to 300 requests per minute with a burst of 60 (VUKEM_VIDEO_RATE_LIMIT_PER_MINUTE); a browser session to 1,800 (VUKEM_VIDEO_RATE_LIMIT_SESSION_PER_MINUTE). Starting a job and importing media or a template (job_start, media_import, template:import) are limited to 10 per minute per actor (VUKEM_VIDEO_RATE_LIMIT_HEAVY_PER_MINUTE). Before authentication an address has 600 requests per minute, and 20 failed authentications per minute, after which it is refused before any key or login is checked. Behind a proxy, set TRUSTED_PROXIES, or every client shares one address.

The answer to a limit is HTTP 429 with Retry-After and E_RATE_LIMITED, which is retryable.

Common mistakes#

  • Putting a key in a URL, a command-line argument or a repository. The prefix vvk_ lets secret scanners find leaks; if one leaks, revoke it.
  • Asking for a scope your own role lacks: the creation is refused.
  • A key that expired: create a new one before the date.

Next steps#