Guides
API keys and presets
Create organization API keys, choose a preset that limits what each key can do, and rotate or revoke keys.
API keys let programs call VMYard without a browser. A key belongs to one organization, has a preset that limits which routes it reaches, and acts with its creator's current role.
Create a key
In the console, open API keys and choose Create key. Give it a name (1–64 characters), a preset, and a lifetime of 1 to 365 days (90 by default). The secret is shown once; copy it then. You can also get a key from the CLI with vy login.
Secrets look like vmy_ followed by 43 characters. VMYard stores only a hash, the first 12 characters (prefix), and the last four, so it can show you which key is which but can never show the secret again.
Use a key
Send it as a bearer token. The key already names its organization, so X-Organization-ID is optional; if you send it, it must match (403 organization_mismatch otherwise). Bearer requests don't need a CSRF token.
curl "$VMYARD_API_URL/v1/machines" \
-H "Authorization: Bearer $VMYARD_API_KEY"Keep keys out of source control and command lines. The CLI accepts keys only on stdin or from the device flow.
Presets
Each preset includes everything in the presets above it.
| Preset | Adds |
|---|---|
read_only | Reads: machines, operations, the catalog, /v1/me, billing, limits, usage, port lists, and environments (without values). |
use_existing | Using machines that exist: start, stop, restart, settings, commands and background commands, file reads and writes, ports, port tokens, SSH keys, and environment upgrades. |
create_and_use | Creating and deleting machines, and choosing or changing a machine's internet access. |
full_access | Webhooks, environment changes and reveals, and billing management (spend cap, checkout, payment portal). |
A key with too small a preset gets 403 insufficient_scope. A read_only key gets it on every route that reaches inside a machine, including file reads and command status.
Roles still apply
A key never does more than its creator could. If the creator is a Viewer, the key can only read, whatever its preset; webhooks and environment changes also need the creator to be an Owner or Admin. If the creator leaves the organization, the key stops working.
Rotate and revoke
The key's creator, an Owner, or an Admin can:
- Rotate a key: VMYard issues a new secret with the same name, preset, and lifetime and revokes the old one at once. The person who rotates becomes the new key's creator.
- Revoke a key: it stops working at once. Revoking twice is harmless.
Owners and Admins see every key in the organization; other members see the keys they created.
A key that is malformed, unknown, expired, or revoked gets 401 invalid_api_key.