> ## Documentation Index
> Fetch the complete documentation index at: https://vastai-80aa3a82-ltxv2-serverless.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

* [Get Instances](https://docs.vast.ai/api-reference/instances/show-instances)
* [Request Logs](https://docs.vast.ai/api-reference/instances/show-logs)

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": {}
    }
}
```

* [Create Instances](https://docs.vast.ai/api-reference/instances/create-instance)
* [Update Instances](https://docs.vast.ai/api-reference/instances/manage-instance)
* [Destroy Instances](https://docs.vast.ai/api-reference/instances/destroy-instance)
* [Reboot Instances](https://docs.vast.ai/api-reference/instances/reboot-instance)
* [Execute Command](https://docs.vast.ai/api-reference/instances/execute)
* [Change Bid Price](https://docs.vast.ai/api-reference/instances/change-bid)

### user\_read

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

* [Show User](https://docs.vast.ai/api-reference/accounts/show-user)
* [Show IP Addresses](https://docs.vast.ai/api-reference/accounts/show-ipaddrs)
* [Get Subaccount](https://docs.vast.ai/api-reference/accounts/show-subaccounts)

### user\_write

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

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

### billing\_read

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

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

### 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": {}
    }
}
```

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

### machine\_write

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

* [Set Minimum Bid](https://docs.vast.ai/api-reference/machines/set-min-bid)
* [Set Default Job](https://docs.vast.ai/api-reference/machines/set-defjob)
* [Remove Default Job](https://docs.vast.ai/api-reference/machines/remove-defjob)
* [Schedule Maintenance](https://docs.vast.ai/api-reference/machines/schedule-maint)
* [List Machine](https://docs.vast.ai/api-reference/machines/list-machine)
* [Unlist Machine](https://docs.vast.ai/api-reference/machines/unlist-machine)

### misc

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

* [Copy Data](https://docs.vast.ai/api-reference/instances/copy)
* [Cancel Copy](https://docs.vast.ai/api-reference/instances/cancel-sync)
* [Search GPUs](https://docs.vast.ai/api-reference/search/search-offers)
* [Search GPUs Advanced](https://docs.vast.ai/api-reference/search/search-offers)

### team\_read

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

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

### team\_write

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

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