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

# Create and revoke API keys

> Create an API key with scopes, so that a program can call the API for your workspace. Revoke a key when you do not need it.

Create an API key so that a program, a script, or a CI pipeline can call the API for one workspace. Revoke the key when you no longer need it.

Plan the API keys for my integration.

Ask what my program must do with the API.
Use the API key scopes reference to suggest only the scopes it needs.
Explain how to create a key from Settings > API keys.
Remind me to store the key in a secret manager. Do not ask me to share it.

## Before you start

* You need the **Owner** or **Admin** role to see, create, or revoke API keys.
* Choose a secure place to store the key. You can see the full key only one time.
* The key acts for the workspace, not for you. Its scopes limit what it can read and change.

## Create an API key

**1. Open API keys**

In the rail, choose **Settings**, then **API keys**. Choose **Create API key**.

![The API keys page with the Create API key button, and a table with the key CI pipeline, the first characters of the key, the last use, and the expiration date.](https://mintcdn.com/vms-c6f4e5ac/ik-PVuE4l6A-0My2/images/workspace/api-keys/00-api-keys-page-light.png?fit=max\&auto=format\&n=ik-PVuE4l6A-0My2\&q=85\&s=145949169b56b7ef5e9befd201a17b37)

**2. Choose the name, the expiration, and the scopes**

1. Type a **Name**.
2. Choose an **Expiration**: **30 days**, **90 days**, **1 year**, or **No expiration**.
3. In **Scopes**, choose the access for each area. For **Sandboxes**, you can also choose **Run commands**, **Read and write files**, **Connect with SSH**, and **Open the desktop**.
4. Choose **Create key**.

![The Create API key sheet with the Name field, the Expiration select set to 90 days, and the Workspace, Sandboxes, and Snapshots scopes.](https://mintcdn.com/vms-c6f4e5ac/kvsBm-leIVQYZQAw/images/workspace/api-keys/01-create-api-key-light.png?fit=max\&auto=format\&n=kvsBm-leIVQYZQAw\&q=85\&s=524e2fdb6dad87d3c48f1574614ca536)

**3. Copy the key**

In **Copy your API key now**, choose **Copy**. Store the key in a secret manager, then choose **I copied the key**.

> [!WARNING]
>
> You can see the key only one time. Only a hash of the key and its first characters are stored. If you lose the key, revoke it and create a new key.

The new key shows in the table, with its first characters, its last use, and its expiration date.

To see the scopes of a key, choose its row, or open its menu (**...**) and choose **View access**. To change the scopes, create a new key, then revoke the old key.

## Use the key

Send the key in the `Authorization` header of each request. Replace `<your-api-key>` with the key.

```typescript TypeScript theme={null}
const response = await fetch("https://vms.dev/api/v1/workspace", {
  headers: { Authorization: "Bearer <your-api-key>" },
});
```

```bash cURL theme={null}
curl https://vms.dev/api/v1/workspace \
  -H "Authorization: Bearer <your-api-key>"
```

The API also accepts the key in the `x-api-key` header. See [your first API request](https://vms.dev/docs/api-reference/first-request.md).

## Revoke an API key

1. Open the menu (**...**) of the key and choose **Revoke key**.
2. In **Revoke the API key?**, choose **Revoke key**.

Programs that use the key stop working at once. Commands and file calls can work for up to 10 more seconds. You cannot undo this.

To revoke more than one key, select the check box of each key, choose **Actions**, then **Revoke keys**.

## Keys of the CLI

`vms login` makes a key with the name `vms CLI on <computer name>`. It is in the list with the other keys. Revoke it to sign out that computer. See [CLI reference](https://vms.dev/docs/reference/cli.md#sign-in).

## Troubleshooting

> [accordion] Only owners and admins can see API keys
>
> You have the **Member** role. Ask an owner or an admin to create the key. See [Members](https://vms.dev/docs/workspace/members.md).

> [accordion] The API key is not correct, or somebody revoked it.
>
> The API returns status 401. Send the full key, with the `vms_` prefix. If somebody revoked the key, create a new key.

> [accordion] The API key expired. Create a new API key in the settings.
>
> The API returns status 401. Create a new key, and give it a longer expiration if the program needs it.

> [accordion] This API key does not have the workspace:read scope.
>
> The API returns status 403. A key keeps its scopes. Create a new key with the scope, then revoke the old key.

> [accordion] This API key sent too many requests. Wait one minute, then try again.
>
> The API returns status 429. Each key can send 1,200 requests in one minute. Each edge server counts the command and file requests of a key apart from the other edge servers.

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


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