Référence API
Authentifiez-vous auprès du Tungsto API actuel
Comprenez le contrat de cookie de session et de CSRF pris en charge avant d'intégrer les points de terminaison de compte, de facturation et de serveur.
Sur cette page
Avant de commencer
- Un compte existant et un accès au service de compte en cours d'exécution via HTTPS.
- Un client qui préserve les cookies de session entre les requêtes.
- Pour les modifications, le jeton CSRF associé à la même session active.
Utilisez la méthode d'authentification prise en charge
Les routes API protégées utilisent la session de compte établie par la connexion. Le cookie de session est nommé __Host-tungsto-session et est marqué Secure et HttpOnly. Un second cookie, __Host-tungsto-csrf, prend en charge la vérification des requêtes. Les modifications de compte nécessitent un en-tête x-csrf-token correspondant à cette session, en plus du cookie de session.
L'écran des clés SSH et API crée, répertorie et révoque des clés à portée limitée. Envoyez Authorization: Bearer suivi de la clé à usage unique. La portée de lecture autorise GET /api/v1/servers, le détail du serveur et /api/v1/orders. La portée des serveurs autorise les serveurs, le détail du serveur et /api/v1/network. La portée de facturation autorise GET /api/v1/ledger.. Toutes les mutations de clé API sont refusées, même si une session de navigateur est également présente. Un changement de mot de passe ou une récupération de compte révoque les clés existantes. Ne construisez pas d'automatisation de matériel de production ou de paiement sans surveillance autour de cet aperçu local.
Établir et vérifier une session
La requête ci-dessus montre uniquement les noms de champs. Fournissez les identifiants de manière sécurisée dans votre propre client ; n'enregistrez pas de vrai mot de passe dans des exemples partagés ou des sorties de diagnostic. Les requêtes provenant d'un navigateur doivent rester sur le même site. Un en-tête Origin nommant une autre origine est rejeté.
- Envoyez une requête POST JSON vers /api/v1/auth/login contenant le nom d'utilisateur et le mot de passe. Conservez les valeurs Set-Cookie renvoyées par une réponse réussie dans le magasin de cookies protégé du client.
- Conservez le csrfToken renvoyé dans la réponse JSON avec cette session. Ne mélangez pas un jeton d'une connexion avec les cookies d'une autre.
- Appelez GET /api/v1/me avec les cookies pour vérifier le compte. Sa réponse contient le nom d'utilisateur, balanceUsd et csrfToken.
- Pour une modification protégée, envoyez les cookies de session, Content-Type: application/json et x-csrf-token. Incluez un Idempotency-Key lorsque le point de terminaison l'exige.
- Terminez la session en utilisant POST /api/v1/auth/logout lorsque le client a terminé.
POST /api/v1/auth/login HTTP/1.1
Content-Type: application/json
{"username":"your-username","password":"your-password"}Gérer l'expiration de session et les erreurs de vérification
Une récupération de compte réussie modifie le mot de passe, révoque les sessions existantes et émet un code de récupération de remplacement. Les clients utilisant d'anciens cookies doivent se réauthentifier. Le service expire également les sessions, donc une connexion précédemment réussie n'est pas un identifiant illimité.
| Réponse | Signification | Action suivante |
|---|---|---|
| 401 authentication_required | Aucune session de compte valide n'a été trouvée. | Connectez-vous à nouveau et conservez les nouveaux cookies. |
| 401 session_invalid | Le cookie de session et le cookie CSRF ne se vérifient pas ensemble. | Commencez une nouvelle connexion au lieu de réutiliser des cookies mélangés. |
| 403 csrf_failed | La demande de modification ne contient pas le jeton de vérification correspondant. | Rechargez les informations de session et utilisez son jeton actuel. |
| 403 origin_rejected | L'origine fournie est différente de l'origine de la requête. | Exécutez la demande depuis le contexte pris en charge du même site. |
| 429 rate_limited | Trop de tentatives d'authentification ont été effectuées. | Attendez avant de réessayer ; ne réessayez pas continuellement. |
Gardez l'intégration dans le contrat actuel
L'écran Sécurité répertorie les sessions actives via GET /api/v1/sessions et révoque une session possédée via DELETE /api/v1/sessions/:id.. L'écran des clés répertorie et révoque les clés API. Il n'y a pas de flux OAuth. L'enregistrement et la récupération sont des opérations interactives d'accès au compte, pas des substituts à un mécanisme de compte de service. Évitez de distribuer les cookies de session d'une personne entre plusieurs outils ou utilisateurs.
Recevoir un succès d'authentification confirme l'accès au compte, pas que chaque opération externe est disponible. Le règlement en crypto nécessite un fournisseur connecté ; les actions physiques sur le serveur nécessitent que l'opérateur exécute les demandes en file d'attente. Lisez le guide des opérations pour connaître les résultats spécifiques aux points de terminaison et le comportement de nouvelle tentative avant d'interpréter une réponse réussie comme une action réelle terminée.