Dokumentacja API
Uwierzytelnij się w bieżącym Tungsto API
Zapoznaj się z obsługiwanym kontraktem ciasteczek sesyjnych i CSRF przed integracją z punktami końcowymi konta, rozliczeń i serwerów.
Na tej stronie
Zanim zaczniesz
- Istniejące konto i dostęp do działającej usługi konta przez HTTPS.
- Klient, który zachowuje pliki cookie sesji między żądaniami.
- W przypadku zmian token CSRF powiązany z tą samą aktywną sesją.
Użyj obsługiwanej metody uwierzytelniania
Chronione trasy API korzystają z sesji konta ustanowionej podczas logowania. Plik cookie sesji nosi nazwę __Host-tungsto-session i jest oznaczony jako Secure i HttpOnly. Drugi plik cookie, __Host-tungsto-csrf, wspiera weryfikację żądań. Zmiany na koncie wymagają nagłówka x-csrf-token zgodnego z tą sesją, oprócz pliku cookie sesji.
Ekran kluczy SSH i API tworzy, wyświetla i unieważnia klucze o ograniczonym zakresie. Wyślij Authorization: Bearer, a po nim klucz jednorazowy. Zakres odczytu umożliwia GET /api/v1/servers, szczegóły serwera i /api/v1/orders. Zakres serwerów umożliwia serwery, szczegóły serwera i /api/v1/network. Zakres rozliczeń umożliwia GET /api/v1/ledger. Wszystkie mutacje kluczy API są odrzucane, nawet jeśli obecna jest również sesja przeglądarki. Zmiana hasła lub odzyskanie konta unieważnia istniejące klucze. Nie buduj bezobsługowego sprzętu produkcyjnego ani automatyzacji płatności wokół tego lokalnego podglądu.
Ustanów i zweryfikuj sesję
Powyższe żądanie pokazuje tylko nazwy pól. Poświadczenia podawaj bezpiecznie we własnym kliencie; nie zapisuj prawdziwego hasła we wspólnych przykładach ani w danych diagnostycznych. Żądania z przeglądarki muszą pozostać na tej samej witrynie. Nagłówek Origin wskazujący inne źródło jest odrzucany.
- Wyślij żądanie POST JSON do /api/v1/auth/login zawierające nazwę użytkownika i hasło. Przechowuj wartości Set-Cookie zwrócone przez pomyślną odpowiedź w chronionym magazynie plików cookie klienta.
- Zachowaj csrfToken zwrócony w odpowiedzi JSON z tą sesją. Nie mieszaj tokena z jednego logowania z plikami cookie z innego.
- Wywołaj GET /api/v1/me z plikami cookie, aby zweryfikować konto. Jego odpowiedź zawiera nazwę użytkownika, saldoUsd i csrfToken.
- W przypadku chronionej zmiany wyślij pliki cookie sesji, Content-Type: application/json i x-csrf-token. Dołącz Idempotency-Key, gdy punkt końcowy tego wymaga.
- Zakończ sesję za pomocą POST /api/v1/auth/logout, gdy klient zakończy pracę.
POST /api/v1/auth/login HTTP/1.1
Content-Type: application/json
{"username":"your-username","password":"your-password"}Obsługa wygaśnięcia sesji i błędów weryfikacji
Pomyślne odzyskanie konta zmienia hasło, unieważnia istniejące sesje i wydaje zastępczy kod odzyskiwania. Klienci używający wcześniejszych plików cookie muszą ponownie się uwierzytelnić. Usługa również wygasa sesje, więc wcześniej pomyślne połączenie nie jest nieograniczonym poświadczeniem.
| Odpowiedź | Znaczenie | Następna akcja |
|---|---|---|
| 401 authentication_required | Nie znaleziono prawidłowej sesji konta. | Zaloguj się ponownie i zachowaj nowe pliki cookie. |
| 401 session_invalid | Sesyjny i CSRF cookie nie weryfikują się razem. | Rozpocznij nowe logowanie zamiast ponownego używania mieszanych plików cookie. |
| 403 csrf_failed | Żądanie zmiany nie zawiera pasującego tokenu weryfikacyjnego. | Przeładuj informacje o sesji i użyj jej bieżącego tokena. |
| 403 origin_rejected | Podany Origin różni się od pochodzenia żądania. | Uruchom żądanie z obsługiwanego kontekstu tej samej lokalizacji. |
| 429 rate_limited | Wykonano zbyt wiele prób uwierzytelnienia. | Poczekaj przed ponowną próbą; nie ponawiaj ciągle. |
Utrzymuj integrację w ramach bieżącej umowy
Ekran bezpieczeństwa wyświetla aktywne sesje za pośrednictwem GET /api/v1/sessions i unieważnia posiadaną sesję za pośrednictwem DELETE /api/v1/sessions/:id. Ekran kluczy wyświetla i unieważnia klucze API. Nie ma przepływu OAuth. Rejestracja i odzyskiwanie to interaktywne operacje dostępu do konta, a nie substytuty mechanizmu konta usługi. Unikaj rozpowszechniania plików cookie sesji jednej osoby wśród wielu narzędzi lub użytkowników.
Otrzymanie sukcesu uwierzytelnienia potwierdza dostęp do konta, a nie że każda operacja zewnętrzna jest dostępna. Rozliczenia kryptowalutowe wymagają połączonego dostawcy; fizyczne działania na serwerze wymagają od operatora wykonania żądań z kolejki. Przeczytaj przewodnik operacji, aby poznać wyniki specyficzne dla punktu końcowego i zachowanie ponawiania, zanim zinterpretujesz pomyślną odpowiedź jako ukończone działanie w świecie rzeczywistym.