API-referentie
Authenticeer bij de huidige Tungsto API
Begrijp het ondersteunde sessiecookie- en CSRF-contract voordat u integreert met account-, facturerings- en servereindpunten.
Op deze pagina
Voordat u begint
- Een bestaand account en toegang tot de actieve accountservice via HTTPS.
- Een client die sessiecookies tussen verzoeken bewaart.
- Voor wijzigingen, de CSRF-token die aan dezelfde actieve sessie is gekoppeld.
Gebruik de ondersteunde authenticatiemethode
Beveiligde API-routes gebruiken de accountsessie die bij het aanmelden is ingesteld. De sessiecookie heet __Host-tungsto-session en is gemarkeerd als Secure en HttpOnly. Een tweede cookie, __Host-tungsto-csrf, ondersteunt verzoekverificatie. Accountwijzigingen vereisen een x-csrf-token-header die overeenkomt met die sessie, naast de sessiecookie.
Het scherm SSH & API-sleutels maakt scoped sleutels aan, toont ze en trekt ze in. Stuur Authorization: Bearer gevolgd door de eenmalige sleutel. De read-scope staat GET /api/v1/servers, serverdetails en /api/v1/orders toe. De servers-scope staat servers, serverdetails en /api/v1/network toe. De billing-scope staat GET /api/v1/ledger. toe. Alle mutaties met API-sleutels worden geweigerd, zelfs als er ook een browsersessie aanwezig is. Een wachtwoordwijziging of accountherstel trekt bestaande sleutels in. Bouw geen onbeheerde productiehardware- of betalingsautomatisering rond deze lokale preview.
Een sessie tot stand brengen en verifiëren
Het bovenstaande verzoek toont alleen veldnamen. Lever inloggegevens veilig aan in uw eigen client; sla geen echt wachtwoord op in gedeelde voorbeelden of diagnostische uitvoer. Verzoeken vanuit een browser moeten op dezelfde site blijven. Een Origin-header die een andere oorsprong noemt, wordt afgewezen.
- Stuur een JSON POST naar /api/v1/auth/login met gebruikersnaam en wachtwoord. Bewaar de Set-Cookie-waarden die door een succesvolle respons worden geretourneerd in de beveiligde cookieopslag van de client.
- Bewaar de csrfToken die in de JSON-respons is geretourneerd bij die sessie. Meng geen token van de ene aanmelding met cookies van een andere.
- Roep GET /api/v1/me aan met de cookies om het account te verifiëren. De respons bevat username, balanceUsd en csrfToken.
- Voor een beveiligde wijziging stuur je de sessiecookies, Content-Type: application/json en x-csrf-token. Voeg een Idempotency-Key toe wanneer het endpoint dit vereist.
- Beëindig de sessie met POST /api/v1/auth/logout wanneer de client klaar is.
POST /api/v1/auth/login HTTP/1.1
Content-Type: application/json
{"username":"your-username","password":"your-password"}Behandel sessieverloop en verificatiefouten
Een succesvol accountherstel wijzigt het wachtwoord, trekt bestaande sessies in en geeft een vervangende herstelcode uit. Clients die eerdere cookies gebruiken, moeten zich opnieuw authenticeren. De dienst laat ook sessies verlopen, dus een eerder succesvolle verbinding is geen onbeperkte inloggegevens.
| Reactie | Betekenis | Volgende actie |
|---|---|---|
| 401 authentication_required | Geen geldige accountsessie gevonden. | Meld u opnieuw aan en behoud de nieuwe cookies. |
| 401 session_invalid | De sessie- en CSRF-cookie verifiëren niet samen. | Start een nieuwe aanmelding in plaats van gemengde cookies te hergebruiken. |
| 403 csrf_failed | Het wijzigingsverzoek mist het bijbehorende verificatietoken. | Herlaad de sessie-informatie en gebruik het huidige token. |
| 403 origin_rejected | De opgegeven Origin verschilt van de oorsprong van het verzoek. | Voer het verzoek uit vanuit de ondersteunde context op dezelfde site. |
| 429 rate_limited | Er zijn te veel authenticatiepogingen gedaan. | Wacht voordat u het opnieuw probeert; blijf niet continu opnieuw proberen. |
Houd de integratie binnen het huidige contract
Het scherm Beveiliging toont actieve sessies via GET /api/v1/sessions en trekt een eigen sessie in via DELETE /api/v1/sessions/:id.. Het scherm Sleutels toont en trekt API-sleutels in. Er is geen OAuth-flow. Registratie en herstel zijn interactieve accounttoegangsoperaties, geen vervanging voor een serviceaccountmechanisme. Vermijd het verspreiden van sessiecookies van één persoon over meerdere tools of gebruikers.
Het ontvangen van een authenticatiesucces bevestigt accounttoegang, niet dat elke externe bewerking beschikbaar is. Crypto-afwikkeling vereist een verbonden provider; fysieke serveracties vereisen dat de operator verzoeken in de wachtrij uitvoert. Lees de operationsgids voor eindpuntspecifieke resultaten en retry-gedrag voordat u een succesvolle respons interpreteert als een voltooide actie in de echte wereld.