Справочник API
Аутентифицируйтесь в текущем Tungsto API
Изучите поддерживаемый контракт session-cookie и CSRF перед интеграцией с конечными точками аккаунта, биллинга и серверов.
На этой странице
Перед началом
- Существующая учётная запись и доступ к работающему сервису учётных записей по HTTPS.
- Клиент, который сохраняет сессионные cookie между запросами.
- Для изменений — CSRF-токен, связанный с той же активной сессией.
Используйте поддерживаемый метод аутентификации
Защищённые маршруты API используют сессию аккаунта, установленную при входе. Cookie сессии называется __Host-tungsto-session и помечен как Secure и HttpOnly. Второй cookie, __Host-tungsto-csrf, поддерживает проверку запросов. Для изменений в аккаунте требуется заголовок x-csrf-token, соответствующий этой сессии, в дополнение к cookie сессии.
Экран ключей SSH и API создаёт, перечисляет и отзывает ключи с ограниченным доступом. Отправьте Authorization: Bearer, за которым следует одноразовый ключ. Область read позволяет GET /api/v1/servers, детали сервера и /api/v1/orders. Область servers позволяет серверы, детали сервера и /api/v1/network. Область billing позволяет GET /api/v1/ledger. Все изменения API-ключей запрещены, даже если также присутствует браузерная сессия. Смена пароля или восстановление аккаунта отзывает существующие ключи. Не стройте автоматизацию производственного оборудования или платежей без присмотра вокруг этого локального предпросмотра.
Установите и проверьте сессию
В запросе выше показаны только имена полей. Передавайте учетные данные безопасно в собственном клиенте; не сохраняйте реальный пароль в общих примерах или диагностическом выводе. Запросы из браузера должны оставаться на том же сайте. Заголовок Origin, указывающий на другой источник, отклоняется.
- Отправьте JSON POST на /api/v1/auth/login, содержащий username и password. Сохраните значения Set-Cookie, возвращённые успешным ответом, в защищённом хранилище куков клиента.
- Сохраняйте csrfToken, возвращённый в ответе JSON, вместе с этой сессией. Не смешивайте токен от одного входа с файлами cookie от другого.
- Вызовите GET /api/v1/me с куками, чтобы проверить аккаунт. Его ответ содержит 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 нет. Регистрация и восстановление — это интерактивные операции доступа к аккаунту, а не замена механизма сервисного аккаунта. Избегайте распространения сессионных куков одного человека среди нескольких инструментов или пользователей.
Получение успешной аутентификации подтверждает доступ к аккаунту, а не то, что каждая внешняя операция доступна. Расчёты в криптовалюте требуют подключённого провайдера; физические действия с сервером требуют, чтобы оператор выполнил запросы из очереди. Прочтите руководство по операциям для получения информации о результатах для конкретных конечных точек и поведении при повторных попытках, прежде чем интерпретировать успешный ответ как завершённое реальное действие.