Authentication

Requests to the task and account endpoints carry an API key in the Authorization header:

Authorization: Bearer vk_...

A missing key gets 401 missing_api_key, and a wrong or revoked one gets 401 invalid_api_key. Listing models (GET /v1/models), pricing a request (POST /v1/quotes) and filing a report (POST /v1/reports) need no key.

Creating and revoking keys

Create keys on the API keys page of the console. Give each one a name that says where it’s used, such as production-backend, so you can revoke one without touching the others.

The secret is shown once, when the key is created. We store only a hash of it, so a lost key can’t be recovered: create a new one and revoke the old one. A revoked key stops working within about a minute.

Keep keys on your server

An API key spends your balance. Call VelvetAPI from your backend, and never put a key in a web page, a mobile app or anything else that runs on your users’ devices. The API doesn’t answer cross-origin browser requests from other websites, so browser code couldn’t use the key anyway, but anyone who found it could.

If a key leaks, revoke it in the console straight away and create a new one.

Monthly spending caps

When you create a key you can give it a monthly cap in US dollars. The cap counts what tasks created with that key cost in the current calendar month (UTC), including tasks that are still running and leaving out refunded ones. A task that would take the key over its cap is refused with 402 spend_cap_reached before it runs.

Caps are useful for keys that a single service, customer or environment uses. To change a cap, create a new key with the new cap and revoke the old one.

End users

The key identifies your account; the required user field on each task identifies your end user. Strikes and suspensions for policy violations apply per end user, so one abusive user doesn’t put your whole account at risk. See End users and strikes.

Console sessions

The console signs you in with Supabase Auth and calls the API’s /v1/console/* endpoints with your session token. Those endpoints are for the console only; use API keys from your own code.