Skip to main content
API keys authenticate your requests to Vast.ai. You’ll need a key for any programmatic access; the web console works without one. This page covers everything you need to create, use, scope, rotate, and revoke API keys.
By default, API keys have full access to your account. For shared tooling, CI/CD, or automation, create a scoped key with only the permissions that workload needs. See Scope a key below.

​
Create an API key

  1. Sign in to the Vast.ai console and open the Keys page.
  2. Find the API Keys section and click +New.
    New API key
  3. Give the key a descriptive name (e.g. ci-deploy, local-dev, prod-scaler). The name only helps you identify keys later; it isn’t sent in requests.
  4. Select the permissions for this key. Defaults to full access; restrict for scoped keys (see below).
    API key permissions
  5. Click Create. The new key is shown once. Copy it now.
Vast.ai shows the key value only at creation time. Treat it like a password: save it to your password manager, an environment variable, or a secret store. If you lose it, you’ll need to reset the key, which generates a new value.

​
Use your key

Once you’ve copied the key, choose how to authenticate based on which surface you’re using.
Configure the CLI once; subsequent commands pick the key up automatically:
The key is stored at ~/.config/vastai/vast_api_key. Override per-command with the --api-key flag if needed.

​
Scope a key

Default keys have full access to your account, including billing, instance creation, and key management. For automation that only needs a subset of those, create a scoped key. Scoped keys are configured at creation time in the console (step 4 above) or via the CLI:
Common scoping patterns: See the permissions reference for the full list of permission flags and their effects.

​
Reset a key

If a key is compromised, lost, or you want to rotate it on a schedule:
  1. Go to the Keys page.
  2. Find the key in the API Keys section and click Reset.
  3. A new value is generated and shown once. Copy it.
  4. Update wherever the old value was stored (env vars, secret managers, CI variables).
The old key stops working as soon as you reset; there’s no overlap window.

​
Delete a key

To permanently revoke a key:
  1. Go to the Keys page.
  2. Find the key in the API Keys section and click Delete.
Deletion is immediate. Any service still using the deleted key will start receiving 401 Unauthorized responses.

​
CLI reference

If you’d rather manage keys from the command line:

​
Security tips

  • Never commit keys to source control. Use environment variables, GitHub Actions secrets, or a secret manager.
  • Use a separate key per environment. Local dev, staging, and prod should each have their own key so you can revoke one without affecting the others.
  • Scope keys to the minimum permissions they need. A leaked scoped key is much less damaging than a leaked full-access key.
  • Rotate keys periodically. A 90-day rotation is a reasonable baseline for production keys.
  • Audit your keys. Review the API Keys section of the console occasionally and delete any keys you no longer use or recognize.