Permissions

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:

Category	Controls
`instance_read`	Viewing instances, logs, SSH keys, volumes, deposits
`instance_write`	Creating, managing, and destroying instances and volumes
`user_read`	Viewing account info, API keys, SSH keys, environment variables, templates
`user_write`	Creating/modifying API keys, SSH keys, environment variables, templates, teams
`billing_read`	Viewing invoices and earnings
`billing_write`	Transferring credit
`machine_read`	Viewing machines and reports (hosts)
`machine_write`	Managing machines, maintenance, listing/unlisting (hosts)
`misc`	Search offers, benchmarks, network volumes, serverless endpoints
`team_read`	Viewing team members and roles
`team_write`	Inviting/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

Transfer Credit

machine_read

Show Machines
Show Reports
SLA Backtest — API-only (hosts): replay historical earnings through SLA math. Requires machine_read. See SLA Backtester. Console hosts should use Set Pricing → SLA preview instead.

machine_write

Host SLA scoped-key recipe (minimum): Create via Create API Key. See Creating Scoped Keys for the required api wrapper.

{
  "api": {
    "machine_read": {},
    "machine_write": {},
    "billing_read": {}
  }
}

Task	Permission	Console fallback
List/update SLA via `create_asks`	`machine_write`	Set Pricing → SLA → LIST
SLA backtester	`machine_read`	Console SLA preview
Schedule / cancel maintenance	`machine_write`	None (CLI/REST only)
Monitor `sla_earn`	`billing_read`	Host → Billing / Earnings

misc

Client SLA search → REST rent (minimum): Create via Create API Key with the api wrapper below (misc covers bundles search).

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

Published OpenAPI charge type values for GET /api/v0/charges/ are gpu, disk, bwd, and bwu. Prefer Account → Billing in the console for SLA settlement credit reconciliation until client charge schemas document SLA line items.

Overview

Common workflows

Endpoints

Permission Categories

Creating Scoped Keys

Custom Roles

Constraints

Endpoint Reference by Category

instance_read

instance_write

user_read

user_write

billing_read

billing_write

machine_read

machine_write

misc

team_read

team_write

​Permission Categories

​Creating Scoped Keys

​Custom Roles

​Constraints

​Endpoint Reference by Category

​instance_read

​instance_write

​user_read

​user_write

​billing_read

​billing_write

​machine_read

​machine_write

​misc

​team_read

​team_write

Permission Categories

Creating Scoped Keys

Custom Roles

Constraints

Endpoint Reference by Category

instance_read

instance_write

user_read

user_write

billing_read

billing_write

machine_read

machine_write

misc

team_read

team_write