> ## Documentation Index
> Fetch the complete documentation index at: https://vastai-80aa3a82-rate-limit-change.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Permissions and Authorization

<script
  type="application/ld+json"
  dangerouslySetInnerHTML={{
__html: JSON.stringify({
"@context": "https://schema.org",
"@type": "HowTo",
"name": "How to Manage API Keys and Permissions on Vast.ai",
"description": "A guide to creating API keys with restricted permissions and managing access control for your Vast.ai account and teams.",
"step": [
  {
    "@type": "HowToStep",
    "name": "Understand Permission Categories",
    "text": "Every API Key has a list of permissions associated with it. Permission categories include: instance_read, instance_write, user_read, user_write, billing_read, billing_write, machine_read, machine_write, misc, team_read, and team_write. Each category controls access to specific API endpoints and operations."
  },
  {
    "@type": "HowToStep",
    "name": "Create Custom Roles",
    "text": "Custom roles can be created and managed through the CLI. Team roles can be managed on the Manage page by users with team_read level access. When creating a custom role, select from a wide range of permissions such as instance creation, billing access, monitoring, etc. This allows for precise control over what each role can and cannot do."
  },
  {
    "@type": "HowToStep",
    "name": "Define Permission JSON",
    "text": "Create a JSON file defining the permissions. For example, to allow instance creation and billing access: {\"api\": {\"misc\": {}, \"user_read\":{}, \"instance_read\": {}, \"instance_write\": {}, \"billing_read\": {}, \"billing_write\": {}}}. For restricted access without billing: {\"api\": {\"misc\": {}, \"user_read\":{}, \"instance_read\": {}, \"instance_write\": {}}}."
  },
  {
    "@type": "HowToStep",
    "name": "Add Constraints (Optional)",
    "text": "Constraints can be added at different levels to enforce certain parameters. You can use wildcards to represent placeholder values. For example, to restrict access to specific instance IDs, add constraints in the permission JSON with operators like eq, lte, gte."
  },
  {
    "@type": "HowToStep",
    "name": "Assign Custom Roles",
    "text": "Once a custom role is created, it can be assigned to team members through the team management interface or CLI commands."
  }
]
})
}}
/>

# API Endpoints and Permission Categories

This document outlines the various API endpoints and their associated permission categories, providing a clear reference for understanding the access control within our system.

<Note>
  **Note:** In the early days we are going to describe these concepts as things like 'instance\_read' or 'instance\_write', We realize these are confusing. Any questions about what permissions are attributed to what actions should be asked via our support channels.
</Note>

Every API Key has a list of permissions associated with it. Every user has the ability to create keys with restricted permissions on their own account. Users can also create restricted keys in team environments using the team-centric endpoints.

### Creating Custom Roles

* **Accessing Role Management**: Custom roles can be created and managed through the CLI. Team roles can be managed on the 'Manage' page by users with team\_read level access.
* **Defining Permissions**: When creating a custom role, anyone can select from a wide range of permissions, such as instance creation, billing access, monitoring, etc. This allows for precise control over what each role can and cannot do.
* **Assigning Custom Roles**: Once a custom role is created, it can be assigned to team members through the team management interface.

### Important Elements

* **constraints**: Constraints can be added at different levels to enforce certain parameters of the body to be specific values
* **params**: You can use wildcards to represent placeholder values. (Useful if you want to generate many keys all doing similar operations)

### Examples

The following json would create a user that has access to the specified categories. In this instance, someone with these permissions would be able to create an instance as well as access billing information

```text Text theme={null}
{
    "api": {
        "misc": {},
        "user_read":{},
        "instance_read": {},
        "instance_write": {},
		"billing_read": {},
		"billing_write": {}
    }
}
```

The following json would create restricted access to only the presented categories. In this example, someone with these permissions would be able to create an instance, but they would not be able to access billing information

```text Text theme={null}
{
    "api": {
        "misc": {},
        "user_read":{},
        "instance_read": {},
        "instance_write": {}
    }
}
```

You can see a full list of permission types as well as the endpoints attached to that permission below

## Permission Categories

### instance\_read

* [List Volumes](https://docs.vast.ai/api-reference/volumes/list-volumes)
* [Show Deposit](https://docs.vast.ai/api-reference/billing/show-deposit)
* [Show Instance](https://docs.vast.ai/api-reference/instances/show-instance)
* [Show Instances](https://docs.vast.ai/api-reference/instances/show-instances)
* [Show Logs](https://docs.vast.ai/api-reference/instances/show-logs)
* [Show SSH Keys](https://docs.vast.ai/api-reference/instances/show-ssh-keys)

The following permissions would allow a user to read the instance logs of instance id 1227 only

```text Text theme={null}
{
    "api": {
        "misc": {},
        "user_read":{},
        "instance_read": {},
        "instance_write": {},
        "billing_read": {
            "api.instance.request_logs": {
                "constraints": {
                    "id": {
                        "eq": 1227
                    }
                }
            }
        }
    }
}
```

The following permissions would allow a user to read the instance logs of instance id from $1 to $2. Apikeys using this feature have to be created using the CLI call [create api-key](/cli/commands)

```text Text theme={null}
{
    "api": {
        "instance_read": {
            "api.instance.request_logs": {
                "constraints": {
                    "id": {
                        "lte": $1,
                        "gte": $2
                    }
                }
            }
        }
    }
}
```

### instance\_write

```text theme={null}
{
	"api": {
        "instance_write": {}
    }
}
```

* [Attach SSH Key](https://docs.vast.ai/api-reference/instances/attach-ssh-key)
* [Cancel Copy](https://docs.vast.ai/api-reference/instances/cancel-copy)
* [Cancel Sync](https://docs.vast.ai/api-reference/instances/cancel-sync)
* [Change Bid](https://docs.vast.ai/api-reference/instances/change-bid)
* [Cloud Copy](https://docs.vast.ai/api-reference/instances/cloud-copy)
* [Copy](https://docs.vast.ai/api-reference/instances/copy)
* [Create Instance](https://docs.vast.ai/api-reference/instances/create-instance)
* [Delete Volume](https://docs.vast.ai/api-reference/volumes/delete-volume)
* [Destroy Instance](https://docs.vast.ai/api-reference/instances/destroy-instance)
* [Detach SSH Key](https://docs.vast.ai/api-reference/instances/detach-ssh-key)
* [Execute](https://docs.vast.ai/api-reference/instances/execute)
* [Manage Instance](https://docs.vast.ai/api-reference/instances/manage-instance)
* [Prepay Instance](https://docs.vast.ai/api-reference/instances/prepay-instance)
* [Reboot Instance](https://docs.vast.ai/api-reference/instances/reboot-instance)
* [Recycle Instance](https://docs.vast.ai/api-reference/instances/recycle-instance)
* [Rent Volume](https://docs.vast.ai/api-reference/volumes/rent-volume)

### user\_read

```text Text theme={null}
{
	"api": {
        "user_read": {}
    }
}
```

* [Show Api Keys](https://docs.vast.ai/api-reference/accounts/show-api-keys)

{/* - [Bitbucket Auth](https://docs.vast.ai/api-reference/accounts/bitbucket-auth) */}

{/* - [Show Hubspot Newsletters](https://docs.vast.ai/api-reference/accounts/show-hubspot-newsletters) */}

{/* - [Jira Auth](https://docs.vast.ai/api-reference/accounts/jira-auth) */}

{/* - [Oauth Bitbucket Login](https://docs.vast.ai/api-reference/accounts/oauth-bitbucket-login) */}

{/* - [Oauth Jira Callback](https://docs.vast.ai/api-reference/accounts/oauth-jira-callback) */}

{/* - [Show Oauth Services](https://docs.vast.ai/api-reference/accounts/show-oauth-services) */}

{/* - [Show Overlay](https://docs.vast.ai/api-reference/accounts/show-overlay) */}

* [Show Env Vars](https://docs.vast.ai/api-reference/accounts/show-env-vars)

{/* - [Show Serverless Workergroup Spend](https://docs.vast.ai/api-reference/serverless/show-serverless-workergroup-spend) */}

* [Show Ssh Keys](https://docs.vast.ai/api-reference/accounts/show-ssh-keys)

{/* - [Accept Team Invite](https://docs.vast.ai/api-reference/team/accept-team-invite) */}

* [Search Templates](https://docs.vast.ai/api-reference/search/search-templates)

{/* - [Show Template V1](https://docs.vast.ai/api-reference/templates/show-template-v1) */}

* [Show Connections](https://docs.vast.ai/api-reference/accounts/show-connections)

{/* - [Show Earnings Data](https://docs.vast.ai/api-reference/billing/show-earnings-data) */}

* [Show Ipaddrs](https://docs.vast.ai/api-reference/accounts/show-ipaddrs)

{/* - [Show Payment Methods](https://docs.vast.ai/api-reference/accounts/show-payment-methods) */}

{/* - [Save Context](https://docs.vast.ai/api-reference/accounts/save-context) */}

* [Show Subaccounts](https://docs.vast.ai/api-reference/accounts/show-subaccounts)

- [Show User](https://docs.vast.ai/api-reference/accounts/show-user)

### user\_write

```text Text theme={null}
{
	"api": {
        "user_write": {}
    }
}
```

* [Create Api Key](https://docs.vast.ai/api-reference/accounts/create-api-key)
* [Delete Api Key](https://docs.vast.ai/api-reference/accounts/delete-api-key)

{/* - [Update Api Key](https://docs.vast.ai/api-reference/accounts/update-api-key) */}

{/* - [Request Ssh Session](https://docs.vast.ai/api-reference/accounts/request-ssh-session) */}

{/* - [Update Cluster](https://docs.vast.ai/api-reference/accounts/update-cluster) */}

{/* - [Update Hubspot Marketing Subscriptions](https://docs.vast.ai/api-reference/accounts/update-hubspot-marketing-subscriptions) */}

{/* - [Disconnect Discord](https://docs.vast.ai/api-reference/accounts/disconnect-discord) */}

* [Create Env Var](https://docs.vast.ai/api-reference/accounts/create-env-var)
* [Delete Env Var](https://docs.vast.ai/api-reference/accounts/delete-env-var)
* [Update Env Var](https://docs.vast.ai/api-reference/accounts/update-env-var)
* [Create Ssh Key](https://docs.vast.ai/api-reference/accounts/create-ssh-key)
* [Delete Ssh Key](https://docs.vast.ai/api-reference/accounts/delete-ssh-key)
* [Create Template](https://docs.vast.ai/api-reference/templates/create-template)

{/* - [Update Template](https://docs.vast.ai/api-reference/templates/update-template) */}

{/* - [Delete Connection](https://docs.vast.ai/api-reference/accounts/delete-connection) */}

{/* - [Delete User](https://docs.vast.ai/api-reference/accounts/delete-user) */}

{/* - [Update Notification Prefs](https://docs.vast.ai/api-reference/accounts/update-notification-prefs) */}

{/* - [Reset Password](https://docs.vast.ai/api-reference/accounts/reset-password) */}

* [Create Subaccount](https://docs.vast.ai/api-reference/accounts/create-subaccount)

{/* - [Update Subaccount](https://docs.vast.ai/api-reference/accounts/update-subaccount) */}

{/* - [Update User By Token](https://docs.vast.ai/api-reference/accounts/update-user-by-token) */}

### billing\_read

```text Text theme={null}
{
	"api": {
        "billing_read": {}
    }
}
```

* [Search Invoices](https://docs.vast.ai/api-reference/billing/search-invoices)
* [Show Invoices](https://docs.vast.ai/api-reference/billing/show-invoices)
* [Show Earnings](https://docs.vast.ai/api-reference/billing/show-earnings)

### billing\_write

```text Text theme={null}
{
	"api": {
        "billing_write": {}
    }
}
```

* [Transfer Credit](https://docs.vast.ai/api-reference/accounts/transfer-credit)

### machine\_read

```text Text theme={null}
{
	"api": {
        "machine_read": {}
    }
}
```

* [Show Machines](https://docs.vast.ai/api-reference/machines/show-machines)
* [Show Reports](https://docs.vast.ai/api-reference/machines/show-reports)

### machine\_write

```text Text theme={null}
{
	"api": {
        "machine_write": {}
    }
}
```

* [Add Network Disk](https://docs.vast.ai/api-reference/network-volumes/add-network-disk)
* [Cancel Maint](https://docs.vast.ai/api-reference/machines/cancel-maint)
* [Cleanup](https://docs.vast.ai/api-reference/machines/cleanup)
* [List Machine](https://docs.vast.ai/api-reference/machines/list-machine)
* [Remove Defjob](https://docs.vast.ai/api-reference/machines/remove-defjob)
* [Schedule Maint](https://docs.vast.ai/api-reference/machines/schedule-maint)
* [Set Defjob](https://docs.vast.ai/api-reference/machines/set-defjob)
* [Set Min-Bid](https://docs.vast.ai/api-reference/machines/set-min-bid)
* [Unlist Machine](https://docs.vast.ai/api-reference/machines/unlist-machine)
* [Unlist Network Volume](https://docs.vast.ai/api-reference/network-volumes/unlist-network-volume)
* [Unlist Volume](https://docs.vast.ai/api-reference/volumes/unlist-volume)

### misc

```text Text theme={null}
{
	"api": {
        "misc": {}
    }
}
```

{/* - [Create Autoscaler](https://docs.vast.ai/api-reference/autoscalers/create-autoscaler) */}

{/* - [Delete Autoscaler](https://docs.vast.ai/api-reference/autoscalers/delete-autoscaler) */}

* [Search Offers](https://docs.vast.ai/api-reference/search/search-offers)

{/* - [Cancel Rsync](https://docs.vast.ai/api-reference/instances/cancel-rsync) */}

{/* - [Show Docker Hub Repo](https://docs.vast.ai/api-reference/search/show-docker-hub-repo) */}

{/* - [Show Docker Registry Auth](https://docs.vast.ai/api-reference/accounts/show-docker-registry-auth) */}

### team\_read

```text Text theme={null}
{
	"api": {
        "team_read": {}
    }
}
```

* [Show Team Members](https://docs.vast.ai/api-reference/team/show-team-members)
* [Show Team Roles](https://docs.vast.ai/api-reference/team/show-team-roles)

### team\_write

```json JSON theme={null}
{
	"api": {
        "team_write": {}
    }
}
```

* [Create Team Role](https://docs.vast.ai/api-reference/team/create-team-role)
* [Create Team](https://docs.vast.ai/api-reference/team/create-team)
* [Destroy Team](https://docs.vast.ai/api-reference/team/destroy-team)
* [Invite Team Member](https://docs.vast.ai/api-reference/team/invite-team-member)
* [Remove Team Member](https://docs.vast.ai/api-reference/team/remove-team-member)
* [Remove Team Role](https://docs.vast.ai/api-reference/team/remove-team-role)
* [Update Team Role](https://docs.vast.ai/api-reference/team/update-team-role)