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 has no expiry date, although a personal key stops working if its creator leaves the organization.

Create a key

In the console, open API Keys and choose Create key. The same page's API endpoint card shows the base URL to send requests to, and an example command that lists the organization's instances — it reads the key from $SUPERHEAT_API_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": "local-scripts", "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.

Choose the kind by who should own the credential. A personal key is tied to you: you can revoke it yourself, and it is revoked automatically if you are removed from the organization. A team key belongs to the organization and survives whoever created it leaving. Put CI pipelines and other shared automation on a team key, or they stop working the day their creator is removed. See Roles and permissions.

The response returns the key metadata and the secret:

{
  "key": {
    "id": "0f5a1c93-6d21-4e7c-a0b8-3c9f2e1d4a77",
    "name": "local-scripts",
    "kind": "personal",
    "prefix": "shk_9f3a21c4",
    "creator_email": "you@example.com",
    "creator_id": "7c2e9a41-5b0d-4f3e-8a16-d94b2c07e5f1",
    "created_at": "2026-07-24T11:02:44.318Z",
    "last_used_at": null,
    "creator_is_member": true
  },
  "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. When the balance cannot cover one hour of the organization's burn with the instance added, deploying or starting it fails 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. A personal key can attach only the SSH keys of the person who created it. A team key acts for the organization: it can attach the SSH key of anyone who is a member now, and of no one who has left — its own creator included. 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, creator_id, created_at, last_used_at and creator_is_member. 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.

creator_is_member is false once the person who created the key has left the organization, and the API Keys page marks the key creator left. A personal key stops working at that point, so revoke it to tidy up. A team key keeps working — it is the organization's — but whoever left was shown its secret once and may still hold a copy, so the page tells you to revoke it and create a new one.

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. In the console, the trash icon next to a key asks first, naming the key and whether it is a personal or a team key; Revoke key confirms.

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.

Create a key​

What a key can do​

List keys​

Revoke a key​

Create a key

What a key can do

List keys

Revoke a key