# 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`](/docs/guides/cli-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.

> [!NOTE]
> Creating, listing, rotating, and revoking keys needs a signed-in browser session. An API key can't manage keys: those routes answer `403 session_required`.

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

```sh tab="curl"
curl "$VMYARD_API_URL/v1/machines" \
  -H "Authorization: Bearer $VMYARD_API_KEY"
```

```sh tab="CLI"
export VMYARD_API_KEY=vmy_...   # always wins over a key stored by vy login
vy ls
```

```ts tab="TypeScript"
const vy = new VMYard({ apiKey: process.env.VMYARD_API_KEY });
```

```python tab="Python"
vy = VMYard(api_key=os.environ["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](/docs/guides/networking). |
| `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`.