API keys

API keys let the CLI, CI jobs, and your own scripts use the velixir API.

Create one

In the dashboard, open API keys and create a key. You choose:

  • Permission - Read (view apps, releases, and deployments), Write (create, deploy, and change things), or Read + Write. Deploying needs Write or Read + Write.
  • Scope - Account (every project and app in the team), Project (one project and its apps), or App (a single app). Give CI the narrowest scope that works.
  • Who uses it - An AI agent (an agent key, see below) or A person, script or CI (a standard key).
  • Expiry - optional.

The key is shown once, so store it straight away, in your CI's secrets or a password manager.

velixir login makes a key for you after you approve the sign-in in your browser, so you only need to create one by hand for CI or scripts.

Use it

Send the key in the X-Api-Key header:

curl -H "X-Api-Key: $VELIXIR_API_KEY" https://velixir.net/api/v1/apps

The CLI reads it from the VELIXIR_API_KEY environment variable, or from ~/.velixir/config.json after velixir login. Every endpoint is in the API reference.

Keys belong to one team

A key works against the team it was created in, whatever team you have selected in the dashboard. Working with two teams means a key for each.

Agent keys

Give an AI agent an agent key, not a standard one. It can do everything its permission allows that you'd be happy for it to do unsupervised: deploy, set env vars, read logs, run replays, make rewind previews and forks. Anything that deletes or overwrites doesn't run. Instead:

  1. The API answers 202 with "approvalRequired": true, an approvalUrl and a short summary of what was asked. Nothing has changed.
  2. The key's owner gets an email, and the request is listed on the Approvals tab of the API keys page, which shows a count in the sidebar while anything is waiting.
  3. Someone with write access to the project opens the link and approves or denies it. Approving runs the action, as them. Requests expire after 24 hours.

The agent can check on it with GET /api/v1/approvals/{id}. The MCP server and the CLI understand this: the agent is told to send you the link, and the CLI says the action needs approval instead of reporting it done.

What needs approval with an agent key: deleting an app, database, cache, volume or custom domain; restoring a volume over its current files; applying or undoing a rewind; discarding a copy. Agent keys also can't create or revoke API keys, so an agent can't give itself a key without approvals.

Even with a standard key, deleting a database or cache keeps its backups for your plan's retention window, so it can be restored from Recently deleted. See Databases and Caches.

Revoke a key

Click Revoke next to the key on the API keys page. Anything still using it stops working straight away.