API keys

An API key is the credential you give a script, a CI job or your own tooling. It authenticates as a member of one organization and never expires on its own.

Create a key

In the console, open API Keys and choose Create key. Over the API:

curl -s -X POST "$SUPERHEAT_API/v1/api-keys" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-pipeline", "kind": "personal"}'

Field	Type	Notes
name	string, 1–64 characters	Required. How the key is labeled in the console.
kind	personal or team	Defaults to personal. team keys are admin-managed and require an admin session to create.

The response returns the key metadata and the secret:

{
  "key": {
    "id": "0f5a1c93-6d21-4e7c-a0b8-3c9f2e1d4a77",
    "name": "ci-pipeline",
    "kind": "personal",
    "prefix": "shk_9f3a21c4",
    "creator_email": "you@example.com",
    "created_at": "2026-07-24T11:02:44.318Z",
    "last_used_at": null
  },
  "secret": "shk_9f3a21c4e0b7d5628a1f3c47b9e0d2a6f81c53d0e7a4b962"
}

The secret is shk_ plus 48 hex characters. Only its first 12 characters are stored as prefix, so the console can show you which key is which.

The secret is shown once

secret appears in this one response and is never returned again. Copy it into your secret store before you close the dialog or discard the response body. If you lose it, revoke the key and create another.

Creating a key requires a signed-in session. A key cannot mint another key — that returns 403 ADMIN_REQUIRED.

What a key can do

A key acts as a member of the organization it was created in, regardless of the role of the person who created it.

Request	With an API key
GET /v1/offers, GET /v1/offers/{id}, GET /v1/catalog/status	Allowed
GET /v1/templates, GET /v1/templates/{id}, GET /v1/templates/by-hash/{hash_id}, POST /v1/templates/{id}/duplicate	Allowed
POST /v1/instances, stop, start, delete, logs	Allowed
GET /v1/billing/transactions, GET /v1/billing/spend-daily	Allowed
GET /v1/api-keys	Allowed
GET /v1/me, GET /v1/ssh-keys, POST /v1/ssh-keys	401 TOKEN_INVALID — account endpoints need a session
POST /v1/billing/checkout-session	403 ADMIN_REQUIRED — checkout is admin-only
Invites and member management under /v1/orgs/current	403 ADMIN_REQUIRED
POST /v1/api-keys, DELETE /v1/api-keys/{id}	403 ADMIN_REQUIRED
Any request carrying an X-Org-Id for another organization	403 ORG_MISMATCH

Two consequences worth planning around:

• A key cannot top up the balance. If the organization runs out of credits, deploys fail with 402 INSUFFICIENT_BALANCE until an admin adds credits in the console. See How billing works.
• A key cannot add SSH keys. Add yours in the console first, then pass its ssh_key_id when you deploy. The keys available to a key are the ones on the account of the person who created it. See Add a key.

List keys

curl -s "$SUPERHEAT_API/v1/api-keys" \
  -H "Authorization: Bearer $SUPERHEAT_KEY"

Returns {"items": [...]} of the organization's active keys, newest first, each with id, name, kind, prefix, creator_email, created_at and last_used_at. Revoked keys are not listed, and the secret never appears again. last_used_at is updated on every request the key makes, which is the fastest way to find a key nothing is using anymore.

Revoke a key

curl -s -X DELETE "$SUPERHEAT_API/v1/api-keys/0f5a1c93-6d21-4e7c-a0b8-3c9f2e1d4a77" \
  -H "Authorization: Bearer $SESSION_TOKEN"

Returns 204 No Content. The key stops working on the next request it makes.

Who	Can revoke
Admin	Any key in the organization
Member	Only their own personal keys
An API key	Nothing — 403 ADMIN_REQUIRED

Revoking an unknown, already-revoked, or other organization's key returns 404 API_KEY_NOT_FOUND. Revoking does not touch instances the key deployed; they keep running and keep billing until you stop or destroy them.