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:

• API: Create API Key
• CLI: vastai create api-key
• SDK: vast.create_api_key()

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

• Show Instance
• Show Instances
• Show Logs
• Show SSH Keys
• Show Volumes
• Show Deposit

instance_write

• Attach SSH Key
• Copy
• Cancel Copy
• Cloud Copy
• Cancel Sync
• Change Bid
• Create Instance
• Manage Instance
• Delete Instance
• Detach SSH Key
• Execute
• Prepay Instance
• Reboot Instance
• Recycle Instance
• Create Volume
• Delete Volume

user_read

• Show API Keys
• Show Connections
• Show Environment Variables
• Show IP Addresses
• Show SSH Keys
• Show Subaccounts
• Show User
• Search Templates

user_write

• Create API Key
• Delete API Key
• Create Environment Variable
• Update Environment Variable
• Delete Environment Variable
• Create SSH Key
• Update SSH Key
• Delete SSH Key
• Create Subaccount
• Set User
• Create Team
• Delete Team
• Create Template
• Edit Template
• Delete Template

billing_read

• Search Invoices
• Show Invoices
• Show Earnings

billing_write

• Transfer Credit

machine_read

• Show Machines
• Show Reports

machine_write

• Cancel Maintenance
• Cleanup Machine
• List Machine
• Remove Default Job
• Schedule Maintenance
• Set Default Job
• Set Minimum Bid
• Unlist Machine
• Add Network Disk
• Unlist Network Volume
• Unlist Volume

misc

• Search Network Volumes
• Show Workergroups
• Create Workergroup
• Update Workergroup
• Delete Workergroup
• Show Endpoints
• Create Endpoint
• Delete Endpoint
• Search Benchmarks
• Search Offers
• Search Volumes

team_read

• Show Team Members
• Show Team Role
• Show Team Roles

team_write

• Invite Team Member
• Remove Team Member
• Create Team Role
• Update Team Role
• Remove Team Role