Authentication

Every request to the Vast.ai API must include an API key. This page covers how to create keys, how to include them in requests, and key lifecycle details.

Create an API Key

Generate a key from the Keys page in the web console:

Click +New.
Give the key a name (optional but recommended, e.g. “CI pipeline” or “notebook”).
Copy the key immediately, you’ll only see it once.

You can also create keys programmatically via the API (Create API Key), CLI (vastai create api-key), or SDK (vast.create_api_key()).

Use an API Key

Include your key as a Bearer token in the Authorization header:

curl -s -H "Authorization: Bearer $VAST_API_KEY" \
  "https://console.vast.ai/api/v0/users/current/"

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['VAST_API_KEY']}"}
resp = requests.get("https://console.vast.ai/api/v0/users/current/", headers=headers)
print(resp.json())

A common pattern is to store your key in an environment variable:

export VAST_API_KEY="your-api-key-here"

This keeps the key out of your code and makes it easy to rotate.

If you get a 401 Unauthorized or 403 Forbidden response, double-check your API key. The most common causes are a typo, an expired key, or a scoped key that lacks the required permission for the endpoint you’re calling.

Verify Your Key

A quick way to confirm your key works is to fetch your account info:

curl -s -H "Authorization: Bearer $VAST_API_KEY" \
  "https://console.vast.ai/api/v0/users/current/"

A successful response includes your user ID, email, balance, and SSH key:

{
  "id": 123456,
  "email": "you@example.com",
  "credit": 25.00,
  "ssh_key": "ssh-rsa AAAAB3..."
}

Scoped Keys and Permissions

By default, the web console creates a full-access key. For CI/CD pipelines, shared tooling, or team environments, you should create scoped keys that restrict access to only the permissions you need. For example, a key that can only read and manage instances (but cannot access billing):

{
  "api": {
    "misc": {},
    "user_read": {},
    "instance_read": {},
    "instance_write": {}
  }
}

See the Permissions page for the full list of permission categories, endpoint mappings, constraint syntax, and advanced examples.

Key Expiration

API keys do not expire by default. You can revoke a key at any time from the Keys page or by calling the Delete API Key endpoint.

Treat your API key like a password. Do not commit keys to version control or share them in plaintext. If a key is compromised, revoke it immediately and create a new one.

Overview

Common workflows

Endpoints

Create an API Key

Use an API Key

Verify Your Key

Scoped Keys and Permissions

Key Expiration

​Create an API Key

​Use an API Key

​Verify Your Key

​Scoped Keys and Permissions

​Key Expiration

Create an API Key

Use an API Key

Verify Your Key

Scoped Keys and Permissions

Key Expiration