> ## Documentation Index
> Fetch the complete documentation index at: https://vms.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace access reference

> The roles of a workspace, their permissions, and the scopes and limits of API keys.

This reference gives the permissions of each role and the rules of API keys.

Check who can do an action.

Ask which action I want to do.
Tell me which role or API key scope can do it.

## Roles

Each member has one role in each workspace. The person who creates a workspace is its owner.

| Action | Owner | Admin | Member |
| - | - | - | - |
| Open the workspace | Yes | Yes | Yes |
| Change the name, the URL, and the default language | Yes | Yes | No |
| Delete the workspace | Yes | No | No |
| Invite people and cancel invitations | Yes | Yes | No |
| Give the **Owner** role | Yes | No | No |
| Change the role of a member, or remove a member | Yes | Yes, except an owner | No |
| See, create, and revoke API keys | Yes | Yes | No |
| See, create, and delete sandboxes. Run commands, use files, and connect with SSH. | Yes | Yes | Yes |
| See, save, rename, share, and delete templates | Yes | Yes | Yes |
| See and download the saved files of snapshots | Yes | Yes | Yes |
| See webhook endpoints | Yes | Yes | Yes |
| Add, change, and remove webhook endpoints | Yes | Yes | No |
| See the plan, the billing info, the cards, the invoices, and the charges | Yes | Yes | Yes |
| Choose a plan, change the plan, start the trial, or open the billing portal | Yes | Yes | No |
| Change your own profile | Yes | Yes | Yes |

## API key scopes

A scope gives an API key access to one area. You can give a key only the scopes that your role has.

| Scope | Gives access to |
| - | - |
| `workspace:read` | `GET /v1/workspace`: the ID, the name, the company website, the URL, and the default language of the workspace. `GET /v1/workspace-changes`: the changes of the workspace. |
| `sandboxes:read` | `GET /v1/sandboxes`: the list of sandboxes. `GET /v1/sandboxes/{id}`: one sandbox. `GET /v1/operations/{id}`: one operation on a sandbox. `GET /v1/limits`: the limits of the plan and their use. |
| `sandboxes:write` | Each endpoint of `sandboxes:read`, and `POST /v1/sandboxes`, `PATCH /v1/sandboxes/{id}`, `DELETE /v1/sandboxes/{id}`, `POST /v1/sandboxes/create-many`, and `POST /v1/sandboxes/delete-many`: create, change, and delete sandboxes. See [Create, get, and delete a sandbox](https://vms.dev/docs/sandboxes/create-and-delete.md) and [List, find, and label sandboxes](https://vms.dev/docs/sandboxes/list-and-label.md). |
| `sandboxes:exec` | Run, list, read, and kill commands in sandboxes, and send stdin. See [Run commands](https://vms.dev/docs/sandboxes/run-commands.md). |
| `sandboxes:files` | `GET`, `PUT`, and `DELETE /v1/sandboxes/{id}/files`, and `POST /v1/sandboxes/{id}/files/tar`: read, write, and delete files and folders in sandboxes, and upload a tar. See [Use files](https://vms.dev/docs/sandboxes/files.md). |
| `sandboxes:ssh` | `GET` and `POST /v1/sandboxes/{id}/ssh-keys`, `POST /v1/sandboxes/{id}/ssh-keys/create-many`, `POST /v1/sandboxes/{id}/ssh-keys/delete-many`, and `DELETE /v1/sandboxes/{id}/ssh-keys/{keyId}`: list, add, and delete the SSH keys of sandboxes. See [Connect with SSH](https://vms.dev/docs/sandboxes/ssh.md). |
| `sandboxes:desktop` | `POST /v1/sandboxes/{id}/desktop-sessions`: open the desktop of sandboxes in a browser. See [See the desktop of a sandbox](https://vms.dev/docs/sandboxes/desktop.md). |
| `snapshots:read` | `GET /v1/snapshots/{id}/tree`, `GET /v1/snapshots/{id}/files`, and `GET /v1/snapshots/{id}/download`: list and download the saved files of a snapshot, also of a deleted sandbox. See [Read the files of a snapshot](https://vms.dev/docs/sandboxes/snapshot-files.md). |
| `templates:read` | `GET /v1/templates`, `GET /v1/templates/{id}`, and `GET /v1/templates/{id}/share-codes`: see the [templates](https://vms.dev/docs/sandboxes/templates.md). |
| `templates:write` | Each endpoint of `templates:read`, and save, rename, and delete templates, also many in one request. Make and revoke share codes. A save (`POST /v1/templates` and `create-many`) also needs `snapshots:read`, because a template copies the files of the sandbox. |
| `webhooks:read` | `GET /v1/webhooks` and `GET /v1/webhooks/{id}`: see the [webhook endpoints](https://vms.dev/docs/sandboxes/webhooks.md), without their secrets. |
| `webhooks:write` | Each endpoint of `webhooks:read`, and add, change, and remove webhook endpoints, also many in one request. |
| `billing:read` | Read the usage, the credit, and the balance with `GET /v1/usage`. |

In the **Create API key** sheet, choose **None**, **Read**, or **Read and write** for each area. For **Sandboxes**, also choose **Run commands**, **Read and write files**, or **Connect with SSH**. These three scopes do not include `sandboxes:read`.

## API key rules

| Rule | Value |
| - | - |
| Prefix | `vms_` |
| Shown in the table | The first 10 characters |
| Stored | A hash of the key. You can see the full key only when you create it. |
| Expiration | 30 days, 90 days, 1 year, or no expiration |
| Rate limit | 120 requests in one minute for each key |
| Header | `Authorization: Bearer <key>` or `x-api-key: <key>` |
| Name | Up to 64 characters |

Read the [changelog.](https://vms.dev/docs/changelog.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.