Riferimento API
Autenticati all'attuale Tungsto API
Comprendere il contratto supportato per cookie di sessione e CSRF prima di integrarsi con endpoint di account, fatturazione e server.
In questa pagina
Prima di iniziare
- Un account esistente e accesso al servizio account in esecuzione su HTTPS.
- Un client che conserva i cookie di sessione tra le richieste.
- Per le modifiche, il token CSRF associato alla stessa sessione attiva.
Usa il metodo di autenticazione supportato
Le route protette API usano la sessione dell'account stabilita all'accesso. Il cookie di sessione si chiama __Host-tungsto-session ed è contrassegnato Secure e HttpOnly. Un secondo cookie, __Host-tungsto-csrf, supporta la verifica delle richieste. Le modifiche all'account richiedono un'intestazione x-csrf-token corrispondente a quella sessione, oltre al cookie di sessione.
La schermata delle chiavi SSH e API crea, elenca e revoca chiavi con ambito limitato. Invia Authorization: Bearer seguito dalla chiave monouso. L'ambito di lettura consente GET /api/v1/servers, i dettagli del server e /api/v1/orders. L'ambito dei server consente i server, i dettagli del server e /api/v1/network. L'ambito di fatturazione consente GET /api/v1/ledger.. Tutte le mutazioni delle chiavi API sono negate, anche se è presente anche una sessione del browser. Un cambio di password o il recupero dell'account revoca le chiavi esistenti. Non costruire automazioni hardware o di pagamento di produzione non presidiate attorno a questa anteprima locale.
Stabilire e verificare una sessione
La richiesta sopra mostra solo i nomi dei campi. Fornisci le credenziali in modo sicuro nel tuo client; non salvare una password reale in esempi condivisi o output diagnostici. Le richieste da un browser devono rimanere sullo stesso sito. Un header Origin che indica un'altra origine viene rifiutato.
- Invia una POST JSON a /api/v1/auth/login contenente username e password. Conserva i valori Set-Cookie restituiti da una risposta riuscita nell'archivio cookie protetto del client.
- Conserva il csrfToken restituito nella risposta JSON con quella sessione. Non mescolare un token di un accesso con i cookie di un altro.
- Chiama GET /api/v1/me con i cookie per verificare l'account. La risposta contiene username, balanceUsd e csrfToken.
- Per una modifica protetta, invia i cookie di sessione, Content-Type: application/json e x-csrf-token. Includi un Idempotency-Key quando l'endpoint lo richiede.
- Termina la sessione utilizzando POST /api/v1/auth/logout quando il client ha finito.
POST /api/v1/auth/login HTTP/1.1
Content-Type: application/json
{"username":"your-username","password":"your-password"}Gestisci la scadenza della sessione e gli errori di verifica
Un recupero account riuscito cambia la password, revoca le sessioni esistenti ed emette un codice di recupero sostitutivo. I client che utilizzano cookie precedenti devono autenticarsi di nuovo. Il servizio fa anche scadere le sessioni, quindi una connessione precedentemente riuscita non è una credenziale illimitata.
| Risposta | Significato | Azione successiva |
|---|---|---|
| 401 authentication_required | Nessuna sessione account valida trovata. | Accedi di nuovo e conserva i nuovi cookie. |
| 401 session_invalid | Il cookie di sessione e quello CSRF non vengono verificati insieme. | Avvia un nuovo accesso invece di riutilizzare cookie misti. |
| 403 csrf_failed | La richiesta di modifica non contiene il token di verifica corrispondente. | Ricarica le informazioni della sessione e usa il suo token corrente. |
| 403 origin_rejected | L'Origine fornita è diversa dall'origine della richiesta. | Eseguire la richiesta dal contesto supportato dello stesso sito. |
| 429 rate_limited | Sono stati effettuati troppi tentativi di autenticazione. | Attendi prima di riprovare; non ritentare continuamente. |
Mantieni l'integrazione entro il contratto attuale
La schermata Sicurezza elenca le sessioni attive tramite GET /api/v1/sessions e revoca una sessione di proprietà tramite DELETE /api/v1/sessions/:id.. La schermata delle chiavi elenca e revoca le chiavi API. Non esiste un flusso OAuth. La registrazione e il recupero sono operazioni interattive di accesso all'account, non sostituti di un meccanismo di account di servizio. Evita di distribuire i cookie di sessione di una persona tra più strumenti o utenti.
Ricevere un successo di autenticazione conferma l'accesso all'account, non che ogni operazione esterna sia disponibile. Il regolamento in criptovaluta richiede un provider collegato; le azioni fisiche sul server richiedono che l'operatore esegua le richieste in coda. Leggi la guida alle operazioni per i risultati specifici degli endpoint e il comportamento di retry prima di interpretare una risposta riuscita come un'azione reale completata.