Autenticación
Todos los endpoints documentados en esta sección, salvo GET /v1/health, requieren un bearer token:
Authorization: Bearer <token>
Dos tipos de credencial
El mismo encabezado acepta dos tipos de credencial, y no tienen el mismo alcance.
| Token de sesión | Clave de API | |
|---|---|---|
| Cómo se ve | Un JWT emitido al iniciar sesión en la consola | shk_ seguido de 48 caracteres hexadecimales |
| De dónde viene | La sesión del navegador, refrescada automáticamente | Se crea una sola vez en Claves de API, en la consola |
| Vida útil | De corta duración; caduca y se refresca | Hasta que usted la revoque |
| Rol con el que actúa | Su rol real en la organización, admin o member | Siempre member |
| Organización | La que usted seleccione | Solo la organización en la que se creó la clave |
Endpoints de cuenta (/v1/me, /v1/ssh-keys) | Permitidos | Rechazados con 401 TOKEN_INVALID |
| Acciones de administrador, incluida la facturación | Permitidas si es administrador | Rechazadas con 403 ADMIN_REQUIRED |
Use una clave de API para todo lo que se ejecute sin supervisión. Los tokens de sesión caducan, así que un script que lleve uno deja de funcionar sin aviso. Consulte Claves de API para saber cómo crearlas y revocarlas.
curl -s "$SUPERHEAT_API/v1/instances" \
-H "Authorization: Bearer $SUPERHEAT_KEY"
Elegir la organización
Las instancias, las plantillas, los saldos y las claves pertenecen a una organización. El encabezado X-Org-Id elige contra cuál se ejecuta una solicitud:
| Encabezado | Token de sesión | Clave de API |
|---|---|---|
| Ausente | Su organización personal | La organización propia de la clave |
| Con una organización a la que pertenece | Esa organización, con el rol que tiene allí | Permitido solo si coincide con la organización de la clave |
| Con una organización a la que no pertenece | 403 NOT_A_MEMBER | 403 ORG_MISMATCH |
| Con un id no válido | 400 INVALID_ORG_ID | 403 ORG_MISMATCH — una clave compara el encabezado con el id de su propia organización antes de validarlo |
curl -s "$SUPERHEAT_API/v1/instances" \
-H "Authorization: Bearer $SUPERHEAT_KEY" \
-H "X-Org-Id: 9c1b7d4e-3a52-4a1f-8c6d-b0e9f2a71c48"
Liste las organizaciones en las que puede actuar con GET /v1/orgs, que devuelve de cada una su id, su name, el indicador personal, su role y el saldo. Esa llamada necesita un token de sesión.
Modos de fallo
| Estado | Código | Significado |
|---|---|---|
| 401 | TOKEN_INVALID | Falta el encabezado, el token está mal formado, la clave de API es desconocida o fue revocada, o se envió una clave de API a un endpoint de cuenta |
| 401 | TOKEN_EXPIRED | El token de sesión pasó su fecha de expiración — inicie sesión de nuevo |
| 403 | NOT_A_MEMBER | La organización de X-Org-Id no es una de las suyas |
| 403 | ORG_MISMATCH | La clave de API pertenece a una organización distinta de la de X-Org-Id |
| 403 | ADMIN_REQUIRED | La acción es exclusiva de administradores, o la intentó con una clave de API |
| 400 | INVALID_ORG_ID | X-Org-Id no es un id válido en una solicitud con token de sesión |
Las formas completas de las respuestas están en Errores.
Cualquiera que tenga una clave shk_ puede desplegar instancias que gasten el saldo de su organización. Mantenga las claves fuera del control de versiones y revoque cualquier clave que haya pegado en un lugar que no pueda controlar.