Skip to main content
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.

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.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.
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.The Create API key sheet with the Name field, the Expiration select set to 90 days, and the Workspace, Sandboxes, and Snapshots scopes.
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.
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.
The API also accepts the key in the x-api-key header. See your first API request.

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.

Troubleshooting

You have the Member role. Ask an owner or an admin to create the key. See Members.
The API returns status 401. Send the full key, with the vms_ prefix. If somebody revoked the key, create a new key.
The API returns status 401. Create a new key, and give it a longer expiration if the program needs it.
The API returns status 403. A key keeps its scopes. Create a new key with the scope, then revoke the old key.
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.