Skip to content
RealHW

API keys

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

Section titled “Permissions”
PermissionAccess
runners:readList project runners in your account, limited to the selected project
consoles:readList your console sessions within the key’s account and project scope
consoles:writeReserve and close your console sessions
consoles:connectOpen a WebSocket connection to your console sessions

Keys cannot access platform administration, billing changes, or key management. Remote image submission is not enabled by creating a key; the image-workload path remains the local CLI described in Run an image workload.

Use a key

Section titled “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.

Terminal window
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:

Terminal window
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.