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 no tiene fecha de caducidad, aunque una clave personal deja de funcionar si quien la creó sale de la organización.

Crear una clave

En la consola, abra Claves de API y elija Crear clave. La tarjeta Endpoint de la API de esa misma página muestra la URL base a la que enviar las solicitudes, y un comando de ejemplo que lista las instancias de la organización; lee la clave de $SUPERHEAT_API_KEY. 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": "local-scripts", "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.

Elija el tipo según a quién deba pertenecer la credencial. Una clave personal está ligada a usted: puede revocarla usted mismo, y se revoca automáticamente si lo eliminan de la organización. Una clave team pertenece a la organización y sobrevive a que se vaya quien la creó. Ponga los pipelines de CI y el resto de la automatización compartida en una clave de equipo, o dejarán de funcionar el día en que se elimine a su creador. Consulte Roles y permisos.

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

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

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. Cuando el saldo no cubre una hora del consumo de la organización con la instancia añadida, desplegarla o iniciarla falla 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. Una clave personal solo puede adjuntar las claves SSH de la persona que la creó. Una clave team actúa en nombre de la organización: puede adjuntar la clave SSH de cualquier persona que sea miembro ahora, y la de nadie que se haya ido, incluido su propio creador. 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, creator_id, created_at, last_used_at y creator_is_member. 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.

creator_is_member es false en cuanto la persona que creó la clave deja la organización, y la página Claves de API marca la clave con su creador salió. Una clave personal deja de funcionar en ese momento, así que revóquela para ordenar. Una clave team sigue funcionando —es de la organización—, pero quien se fue vio su secreto una vez y puede conservar una copia, así que la página le indica que la revoque y cree una nueva.

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. En la consola, el icono de la papelera junto a una clave pregunta primero, nombrando la clave y si es una clave personal o de equipo; Revocar clave lo confirma.

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.