Referencia de API
Autentícate en el Tungsto API actual
Comprenda el contrato admitido de cookies de sesión y CSRF antes de integrarse con los endpoints de cuenta, facturación y servidor.
En esta página
Antes de empezar
- Una cuenta existente y acceso al servicio de cuenta en ejecución a través de HTTPS.
- Un cliente que conserva las cookies de sesión entre solicitudes.
- Para cambios, el token CSRF asociado a la misma sesión activa.
Utilice el método de autenticación compatible
Las rutas protegidas API utilizan la sesión de cuenta establecida al iniciar sesión. La cookie de sesión se llama __Host-tungsto-session y está marcada como Secure y HttpOnly. Una segunda cookie, __Host-tungsto-csrf, admite la verificación de solicitudes. Los cambios en la cuenta requieren una cabecera x-csrf-token que coincida con esa sesión, además de la cookie de sesión.
La pantalla de claves SSH y API crea, lista y revoca claves con ámbito. Envíe Authorization: Bearer seguido de la clave de un solo uso. El ámbito de lectura permite GET /api/v1/servers, detalle del servidor y /api/v1/orders. El ámbito de servidores permite servidores, detalle del servidor y /api/v1/network. El ámbito de facturación permite GET /api/v1/ledger.. Todas las mutaciones de claves API están denegadas, incluso si también hay una sesión de navegador presente. Un cambio de contraseña o una recuperación de cuenta revoca las claves existentes. No construya automatización de hardware de producción o de pagos desatendida en torno a esta vista previa local.
Establecer y verificar una sesión
La solicitud anterior muestra solo nombres de campos. Proporcione las credenciales de forma segura en su propio cliente; no guarde una contraseña real en ejemplos compartidos o salidas de diagnóstico. Las solicitudes desde un navegador deben permanecer en el mismo sitio. Se rechaza una cabecera Origin que nombre otro origen.
- Envíe un POST JSON a /api/v1/auth/login que contenga nombre de usuario y contraseña. Guarde los valores Set-Cookie devueltos por una respuesta exitosa en el almacén de cookies protegido del cliente.
- Conserve el csrfToken devuelto en la respuesta JSON con esa sesión. No mezcle un token de un inicio de sesión con cookies de otro.
- Llame a GET /api/v1/me con las cookies para verificar la cuenta. Su respuesta contiene username, balanceUsd y csrfToken.
- Para un cambio protegido, envíe las cookies de sesión, Content-Type: application/json y x-csrf-token. Incluya una Idempotency-Key cuando el endpoint lo requiera.
- Finalice la sesión usando POST /api/v1/auth/logout cuando el cliente haya terminado.
POST /api/v1/auth/login HTTP/1.1
Content-Type: application/json
{"username":"your-username","password":"your-password"}Gestionar la caducidad de la sesión y los errores de verificación
Una recuperación de cuenta exitosa cambia la contraseña, revoca las sesiones existentes y emite un código de recuperación de reemplazo. Los clientes que utilicen cookies anteriores deben autenticarse de nuevo. El servicio también caduca las sesiones, por lo que una conexión previamente exitosa no es una credencial ilimitada.
| Respuesta | Significado | Próxima acción |
|---|---|---|
| 401 authentication_required | No se encontró una sesión de cuenta válida. | Inicie sesión de nuevo y conserve las nuevas cookies. |
| 401 session_invalid | La cookie de sesión y la CSRF no se verifican juntas. | Inicie un nuevo inicio de sesión en lugar de reutilizar cookies mezcladas. |
| 403 csrf_failed | La solicitud de cambio carece del token de verificación correspondiente. | Recargue la información de la sesión y use su token actual. |
| 403 origin_rejected | El Origin suministrado es diferente del origen de la solicitud. | Ejecute la solicitud desde el contexto compatible del mismo sitio. |
| 429 rate_limited | Se realizaron demasiados intentos de autenticación. | Espere antes de intentarlo de nuevo; no reintente continuamente. |
Mantenga la integración dentro del contrato actual
La pantalla de seguridad enumera las sesiones activas a través de GET /api/v1/sessions y revoca una sesión propia a través de DELETE /api/v1/sessions/:id.. La pantalla de claves enumera y revoca las claves API. No hay flujo OAuth. El registro y la recuperación son operaciones interactivas de acceso a la cuenta, no sustitutos de un mecanismo de cuenta de servicio. Evite distribuir las cookies de sesión de una persona entre múltiples herramientas o usuarios.
Recibir éxito de autenticación confirma el acceso a la cuenta, no que todas las operaciones externas estén disponibles. La liquidación de criptomonedas necesita un proveedor conectado; las acciones físicas del servidor necesitan que el operador ejecute solicitudes en cola. Lea la guía de operaciones para conocer los resultados específicos del endpoint y el comportamiento de reintento antes de interpretar una respuesta exitosa como una acción completada en el mundo real.