API keys

Create a key

Open API keys in the dashboard, give the key a name and create it. The key starts with cv_sk_ and is shown only once, so copy it then. The dashboard later shows only its last four characters.

Make one key for each place that uses it, such as your laptop, a server or an agent, so you can revoke one without the others.

Limit what a key can do

A key has every scope unless you take some away under Access when you create it. Each request needs one scope, and the API reference names it for each path.

files:read and jobs:read alone make a key that only reads, such as for a dashboard. A request outside the key's scopes fails with forbidden: HTTP 403 in the API, and exit code 5 in cv. cv needs every scope. The scopes of a key cannot change, so make a new key instead.

Use it

cv reads the key from CV_API_KEY, or from --key. The API takes it as a bearer token in the Authorization header.

A missing or wrong key fails with unauthorized: HTTP 401 in the API, and exit code 3 in cv.

Keep it secret

Anyone with a key that has every scope can run jobs that your balance pays for, and read the project's files while they are kept. Keep keys out of code and version control, and pass them through the environment.

If a key leaks, revoke it on the same page. A revoked key stops working within a minute, and the other keys keep working.

Projects and organizations

Keys, files, jobs and the webhook signing secret belong to a project. The balance and the plan limits belong to the organization that holds the project, so all its projects share them.

Make a project for each app or environment from the organization's page of the dashboard. Owners invite people from its Members page with a link that works for one email address for 7 days.

The Logs page of a project lists the requests made with its keys in the last 30 days, with the status and the error of each.