Довідник API
Автентифікуйтеся в поточному Tungsto API
Зрозумійте підтримуваний контракт сесійних cookie та CSRF перед інтеграцією з кінцевими точками облікового запису, білінгу та серверів.
На цій сторінці
Перш ніж почати
- Наявний обліковий запис та доступ до робочої служби облікових записів через HTTPS.
- Клієнт, який зберігає сесійні файли cookie між запитами.
- Для змін — CSRF-токен, пов'язаний з тією самою активною сесією.
Використовуйте підтримуваний метод автентифікації
Захищені маршрути API використовують сесію облікового запису, встановлену під час входу. Файл cookie сесії називається __Host-tungsto-session і позначений як Secure та HttpOnly. Другий файл cookie, __Host-tungsto-csrf, підтримує перевірку запитів. Зміни облікового запису вимагають заголовка x-csrf-token, що відповідає цій сесії, на додаток до файлу cookie сесії.
Екран ключів SSH і API створює, перелічує та відкликає ключі з обмеженим доступом. Надсилайте Authorization: Bearer, а потім одноразовий ключ. Область читання дозволяє GET /api/v1/servers, деталі сервера та /api/v1/orders. Область серверів дозволяє сервери, деталі сервера та /api/v1/network. Область білінгу дозволяє GET /api/v1/ledger. Усі зміни API-ключів заборонені, навіть якщо також присутня браузерна сесія. Зміна пароля або відновлення облікового запису відкликає наявні ключі. Не будуйте безперервну виробничу апаратну або платіжну автоматизацію навколо цього локального попереднього перегляду.
Встановіть і перевірте сесію
Наведений вище запит показує лише назви полів. Надавайте облікові дані безпечно у власному клієнті; не зберігайте реальний пароль у спільних прикладах або діагностичному виводі. Запити з браузера повинні залишатися на тому самому сайті. Заголовок Origin, що вказує на інше джерело, відхиляється.
- Надішліть JSON POST на /api/v1/auth/login, що містить username і password. Зберігайте значення Set-Cookie, повернуті успішною відповіддю, у захищеному сховищі файлів cookie клієнта.
- Зберігайте csrfToken, повернутий у відповіді JSON, разом із цією сесією. Не змішуйте токен з одного входу з файлами cookie з іншого.
- Викличте GET /api/v1/me з файлами cookie, щоб перевірити обліковий запис. Його відповідь містить username, balanceUsd і csrfToken.
- Для захищеної зміни надішліть сесійні cookie, Content-Type: application/json та x-csrf-token. Включіть Idempotency-Key, коли кінцева точка цього вимагає.
- Завершіть сесію за допомогою POST /api/v1/auth/logout, коли клієнт закінчив роботу.
POST /api/v1/auth/login HTTP/1.1
Content-Type: application/json
{"username":"your-username","password":"your-password"}Обробляйте закінчення сеансу та помилки перевірки
Успішне відновлення облікового запису змінює пароль, відкликає наявні сеанси та видає замінний код відновлення. Клієнти, які використовують попередні файли cookie, повинні автентифікуватися знову. Служба також завершує сеанси, тому попереднє успішне з'єднання не є необмеженим обліковим записом.
| Відповідь | Значення | Наступна дія |
|---|---|---|
| 401 authentication_required | Дійсного сеансу облікового запису не знайдено. | Увійдіть знову та збережіть нові файли cookie. |
| 401 session_invalid | Сеансовий та CSRF-кукі не перевіряються разом. | Почніть новий вхід замість повторного використання змішаних файлів cookie. |
| 403 csrf_failed | Запит на зміну не містить відповідного токена підтвердження. | Перезавантажте інформацію про сеанс і використовуйте його поточний токен. |
| 403 origin_rejected | Наданий Origin відрізняється від походження запиту. | Виконайте запит із підтримуваного контексту того самого сайту. |
| 429 rate_limited | Було зроблено занадто багато спроб автентифікації. | Зачекайте перед повторною спробою; не повторюйте безперервно. |
Тримайте інтеграцію в межах поточного контракту
Екран безпеки перелічує активні сесії через GET /api/v1/sessions і відкликає власну сесію через DELETE /api/v1/sessions/:id. Екран ключів перелічує та відкликає API ключі. Потоку OAuth немає. Реєстрація та відновлення — це інтерактивні операції доступу до облікового запису, а не замінники механізму службового облікового запису. Уникайте розповсюдження файлів cookie сесії однієї особи серед кількох інструментів або користувачів.
Отримання успішної автентифікації підтверджує доступ до облікового запису, а не те, що кожна зовнішня операція доступна. Розрахунок у криптовалюті потребує підключеного провайдера; фізичні дії з сервером потребують виконання оператором запитів у черзі. Прочитайте посібник з операцій для результатів, специфічних для кінцевої точки, і поведінки повторних спроб, перш ніж інтерпретувати успішну відповідь як завершену реальну дію.