> ## 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.

# SDK Permissions

Every API key has a set of permissions that control which endpoints it can access. This page covers permission categories, how to build scoped keys, and how to manage team roles through the SDK.

For an overview of API key creation and setup, see [Authentication](/sdk/python/authentication).

## Permission Categories

Permissions are organized into categories. When you create a scoped API key, you include only the categories the key needs:

| 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                                 |

For the complete mapping of which specific endpoints each category controls, see [Permissions (API)](/api-reference/permissions#endpoint-reference-by-category).

## Creating Scoped Keys

Define permissions as a JSON file. The top-level key is always `"api"`, containing the categories you want to grant:

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

Save this as `perms.json`, then pass it to the SDK:

```python theme={null}
from vastai import VastAI

vast = VastAI(api_key="your-api-key")

result = vast.create_api_key(
    name="ci-deploy-key",
    permission_file="perms.json"
)
print(result)
```

## Constraints

Constraints narrow a permission category to specific parameter values. This lets you create keys that can only operate on certain resources.

### Constrain by Exact ID

This permissions file allows reading logs for instance 1227 only:

```json theme={null}
{
    "api": {
        "instance_read": {
            "api.instance.request_logs": {
                "constraints": {
                    "id": {
                        "eq": 1227
                    }
                }
            }
        }
    }
}
```

### Constrain by Range

You can combine `gte` (greater than or equal) and `lte` (less than or equal) operators to define a range:

```json theme={null}
{
    "api": {
        "instance_read": {
            "api.instance.request_logs": {
                "constraints": {
                    "id": {
                        "gte": 1,
                        "lte": 100
                    }
                }
            }
        }
    }
}
```

Available constraint operators: `eq`, `gte`, `lte`.

<Warning>
  Keys with constraints must be created through the SDK, CLI, or API. The web console only creates full-access keys.
</Warning>

## Managing Team Roles

Team roles use the same permission model as API keys. You define permissions in a JSON file and pass its path to the SDK methods.

### Create a Role

```python theme={null}
vast.create_team_role(
    name="developer",
    permissions="perms.json"
)
```

### View Roles

List all roles for your team:

```python theme={null}
roles = vast.show_team_roles()
print(roles)
```

View a specific role by name:

```python theme={null}
role = vast.show_team_role(NAME="developer")
print(role)
```

### Update a Role

```python theme={null}
vast.update_team_role(
    id=5,
    name="senior-dev",
    permissions="updated-perms.json"
)
```

### Remove a Role

```python theme={null}
vast.remove_team_role(NAME="developer")
```

### Invite a Team Member

Assign a role when inviting a new member:

```python theme={null}
vast.invite_member(
    email="teammate@example.com",
    role="developer"
)
```

### View Team Members

```python theme={null}
members = vast.show_members()
print(members)
```

## Examples

### Read-Only Key

A key that can view instances and account info but cannot create, modify, or destroy anything:

```json theme={null}
{
    "api": {
        "instance_read": {},
        "user_read": {}
    }
}
```

```python theme={null}
result = vast.create_api_key(
    name="monitoring",
    permission_file="readonly.json"
)
print(result)
```

### Instance Management Without Billing

A key that can create and manage instances but has no access to billing or credit transfers:

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

```python theme={null}
result = vast.create_api_key(
    name="ci-deploy",
    permission_file="deploy.json"
)
print(result)
```

### Constrained Key for a Specific Instance

A key that can only manage a single instance (view, reboot, destroy) and nothing else:

```json theme={null}
{
    "api": {
        "instance_read": {
            "api.instance.show": {
                "constraints": {
                    "id": { "eq": 1227 }
                }
            }
        },
        "instance_write": {
            "api.instance.destroy": {
                "constraints": {
                    "id": { "eq": 1227 }
                }
            },
            "api.instance.reboot": {
                "constraints": {
                    "id": { "eq": 1227 }
                }
            }
        }
    }
}
```

```python theme={null}
result = vast.create_api_key(
    name="instance-1227-only",
    permission_file="constrained.json"
)
print(result)
```