Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vast.ai/llms.txt

Use this file to discover all available pages before exploring further.

Every API key has a set of permissions that control which endpoints it can access. This page is the comprehensive reference for permission categories, how they map to API routes, and how to build custom scoped keys. For an overview of API key creation and usage, see Authentication.

​
Permission Categories

Permissions are organized into categories. When you create a scoped API key, you include only the categories the key needs. The available categories are:
CategoryControls
instance_readViewing instances, logs, SSH keys, volumes, deposits
instance_writeCreating, managing, and destroying instances and volumes
user_readViewing account info, API keys, SSH keys, environment variables, templates
user_writeCreating/modifying API keys, SSH keys, environment variables, templates, teams
billing_readViewing invoices and earnings
billing_writeTransferring credit
machine_readViewing machines and reports (hosts)
machine_writeManaging machines, maintenance, listing/unlisting (hosts)
miscSearch offers, benchmarks, network volumes, serverless endpoints
team_readViewing team members and roles
team_writeInviting/removing team members, managing roles

​
Creating Scoped Keys

Define permissions as a JSON object and pass it when creating a key. The top-level key is always "api", containing the categories you want to grant. Example, Instance management with billing access: 
{
  "api": {
    "misc": {},
    "user_read": {},
    "instance_read": {},
    "instance_write": {},
    "billing_read": {},
    "billing_write": {}
  }
}
Example, Instance management without billing: 
{
  "api": {
    "misc": {},
    "user_read": {},
    "instance_read": {},
    "instance_write": {}
  }
}
You can create scoped keys using:

​
Custom Roles

Custom roles let you assign the same set of permissions to multiple team members.
  • Creating roles: Use the CLI or the Manage page in the web console (requires team_write access).
  • Defining permissions: Select from any combination of the categories listed above.
  • Assigning roles: Assign created roles to team members through the team management interface or CLI.

​
Constraints

Constraints narrow a permission category to specific parameter values. This lets you create keys that can only operate on certain resources. Example, Read logs for a single instance only: 
{
  "api": {
    "instance_read": {
      "api.instance.request_logs": {
        "constraints": {
          "id": {
            "eq": 1227
          }
        }
      }
    }
  }
}
Example, Read logs for a range of instance IDs: 
{
  "api": {
    "instance_read": {
      "api.instance.request_logs": {
        "constraints": {
          "id": {
            "lte": 2,
            "gte": 1
          }
        }
      }
    }
  }
}
Supported constraint operators: eq, lte, gte.
API keys using constraints must be created via the CLI (vastai create api-key) or the API (Create API Key).
You can also use wildcards in params to represent placeholder values, useful when generating many keys that perform similar operations.

​
Endpoint Reference by Category

Below is the complete mapping of which endpoints each permission category controls.

​
instance_read

​
instance_write

​
user_read

​
user_write

​
billing_read

​
billing_write

​
machine_read

​
machine_write

​
misc

​
team_read

​
team_write