# API keys

> Authenticate scripts with scoped RealHW credentials.

Source: https://docs.realhw.dev/guides/api-keys/
Documentation index: https://docs.realhw.dev/llms.txt

Use **Settings → API keys** to create a personal key for a script or client.
Choose a name, permissions, an optional project restriction, and an expiry.
Save the secret when it is shown: RealHW cannot display it again.

Keys belong to your user and account. A project restriction narrows access further.
You can view each key’s prefix, permissions, expiration and last-used time, and
revoke it from Settings. Revocation blocks new authenticated requests; it does
not terminate existing workloads or an already-open console connection.

## Permissions

| Permission | Access |
| --- | --- |
| `runners:read` | List project runners in your account, limited to the selected project |
| `consoles:read` | List your console sessions within the key’s account and project scope |
| `consoles:write` | Reserve and close your console sessions |
| `consoles:connect` | Open a WebSocket connection to your console sessions |
| `workloads:read` | Read workload status, logs and artifacts (preview) |
| `workloads:write` | Upload inputs, submit and cancel workloads (preview) |

Keys cannot access platform administration, billing changes, or key management.
OAuth device approval directly issues a scoped token; that token cannot create
additional tokens. Request new permissions through a new browser approval.
For remote execution, verify the deployed operations with `realhw capabilities
--json` and follow [Run an image workload](https://docs.realhw.dev/guides/run-image-workload/).

## Use a key

Store the secret in your shell’s environment or your secret manager as
`REALHW_API_KEY`. Supply your account ID as `REALHW_ACCOUNT_ID`.

```sh
curl --fail-with-body \
  -H "Authorization: Bearer $REALHW_API_KEY" \
  "https://realhw.dev/api/v1/accounts/$REALHW_ACCOUNT_ID/virtual-runners"
```

Reserve a console with `consoles:write` using your RealHW account and project UUIDs:

```sh
curl --fail-with-body -X POST \
  -H "Authorization: Bearer $REALHW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "YOUR_ACCOUNT_UUID",
    "project_id": "YOUR_PROJECT_UUID",
    "protocol": "shell",
    "required_labels": ["arch:x86_64"],
    "image": "alpine:3.20",
    "ttl_seconds": 3600
  }' \
  https://realhw.dev/api/v1/console/sessions
```

List sessions with `GET /api/v1/console/sessions`. Close one with
`DELETE /api/v1/console/sessions/{id}` and a JSON body such as
`{"reason":"finished"}`. A WebSocket client can connect to
`/api/v1/console/sessions/{id}/ws` with the same Authorization header and
`consoles:connect` permission. Browser consoles continue to use your sign-in session.

Expired, revoked, or invalid keys return `401`. An operation outside the key’s
permissions returns `403`; inaccessible individual sessions may return `404`.