Claves de API

Una clave de API es la credencial que le entrega a un script, a un trabajo de CI o a sus propias herramientas. Se autentica como miembro de una sola organización y nunca caduca por sí sola.

Crear una clave

En la consola, abra Claves de API y elija Crear clave. A través de la 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"}'

Campo	Tipo	Notas
name	cadena, de 1 a 64 caracteres	Obligatorio. Es la etiqueta con la que se identifica la clave en la consola.
kind	personal o team	Su valor predeterminado es personal. Las claves team las gestionan los administradores y requieren una sesión de administrador para crearse.

La respuesta devuelve los metadatos de la clave y el secreto:

{
  "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"
}

El secreto es shk_ más 48 caracteres hexadecimales. Solo se almacenan sus primeros 12 caracteres como prefix, para que la consola pueda mostrarle cuál clave es cuál.

El secreto se muestra una sola vez

secret aparece en esta única respuesta y no se devuelve nunca más. Cópielo a su almacén de secretos antes de cerrar el diálogo o de descartar el cuerpo de la respuesta. Si lo pierde, revoque la clave y cree otra.

Crear una clave requiere una sesión iniciada. Una clave no puede acuñar otra clave: eso devuelve 403 ADMIN_REQUIRED.

Qué puede hacer una clave

Una clave actúa como miembro de la organización en la que se creó, sin importar el rol de la persona que la creó.

Solicitud	Con una clave de API
GET /v1/offers, GET /v1/offers/{id}, GET /v1/catalog/status	Permitido
GET /v1/templates, GET /v1/templates/{id}, GET /v1/templates/by-hash/{hash_id}, POST /v1/templates/{id}/duplicate	Permitido
POST /v1/instances, detener, iniciar, eliminar, logs	Permitido
GET /v1/billing/transactions, GET /v1/billing/spend-daily	Permitido
GET /v1/api-keys	Permitido
GET /v1/me, GET /v1/ssh-keys, POST /v1/ssh-keys	401 TOKEN_INVALID — los endpoints de cuenta necesitan una sesión
POST /v1/billing/checkout-session	403 ADMIN_REQUIRED — el proceso de pago es exclusivo de administradores
Invitaciones y gestión de miembros bajo /v1/orgs/current	403 ADMIN_REQUIRED
POST /v1/api-keys, DELETE /v1/api-keys/{id}	403 ADMIN_REQUIRED
Cualquier solicitud que lleve un X-Org-Id de otra organización	403 ORG_MISMATCH

Dos consecuencias que conviene prever:

• Una clave no puede recargar el saldo. Si la organización se queda sin créditos, los despliegues fallan con 402 INSUFFICIENT_BALANCE hasta que un administrador agregue créditos en la consola. Consulte Cómo funciona la facturación.
• Una clave no puede agregar claves SSH. Agregue la suya primero en la consola y luego pase su ssh_key_id al desplegar. Las claves disponibles para una clave de API son las que están en la cuenta de la persona que la creó. Consulte Agregar una clave.

Listar claves

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

Devuelve {"items": [...]} con las claves activas de la organización, de la más nueva a la más antigua, cada una con id, name, kind, prefix, creator_email, created_at y last_used_at. Las claves revocadas no aparecen en la lista, y el secreto no vuelve a mostrarse nunca. last_used_at se actualiza en cada solicitud que hace la clave, que es la forma más rápida de encontrar una clave que ya nadie usa.

Revocar una clave

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

Devuelve 204 No Content. La clave deja de funcionar en la siguiente solicitud que haga.

Quién	Puede revocar
Administrador	Cualquier clave de la organización
Miembro	Solo sus propias claves personal
Una clave de API	Nada — 403 ADMIN_REQUIRED

Revocar una clave desconocida, ya revocada o de otra organización devuelve 404 API_KEY_NOT_FOUND. Revocar no toca las instancias que la clave desplegó; siguen ejecutándose y siguen facturando hasta que las detenga o las destruya.