JWT-аутентификация

Документация описывает работу с API для управления JWT-токенами доступа в системе Severcart.

Назначение

API JWT-аутентификации предоставляет конечные точки для:

• получения пары токенов (access и refresh) для авторизации пользователя;
• обновления access-токена с использованием refresh-токена;
• проверки валидности JWT-токена.

Механизм JWT (JSON Web Token) обеспечивает безопасную передачу данных между клиентом и сервером в виде подписанных токенов. Access-токен используется для доступа к защищённым ресурсам API, refresh-токен — для получения новой пары токенов после истечения срока действия access-токена.

Базовый URL API

Все запросы к API аутентификации отправляются по адресу:

/api/v1/accounts/token/

Полный URL формируется путём добавления пути к базовому адресу сервера. Например:

https://<your-server>/api/v1/accounts/token/

Конечные точки

POST /api/v1/accounts/token/

Получение пары JWT-токенов (access и refresh) на основе учётных данных пользователя.

Назначение

Используется на начальном этапе аутентификации для получения токенов доступа. После успешной аутентификации клиент сохраняет оба токена: access-токен для последующих запросов к API, refresh-токен — для обновления access-токена после его истечения.

HTTP-метод

POST

Параметры запроса

Тело запроса должно быть в формате JSON и содержать следующие поля:

Формат запроса

Content-Type: application/json

Коды состояния HTTP

Пример запроса (curl)

curl -X POST https://<your-server>/api/v1/accounts/token/ \
  -H "Content-Type: application/json" \
  -d '{
    "username": "ivanov",
    "password": "secure_password_123"
  }'

Пример успешного ответа

Код состояния: 200 OK

{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzQwMzEyMDAwLCJpYXQiOjE3NDAzMDg0MDAsImp0aSI6ImFiYzEyMzQ1Njc4OSIsInVzZXJfaWQiOjF9.signature",
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTc0MDM5NDgwMCwiaWF0IjoxNzQwMzA4NDAwLCJqdGkiOiJkZWY5ODc2NTQzMjEiLCJ1c2VyX2lkIjoxfQ.signature"
}

Пример ответа при ошибке аутентификации

Код состояния: 401 Unauthorized

{
  "detail": "No active account found with the given credentials"
}

Пример ответа при неверном формате запроса

Код состояния: 400 Bad Request

{
  "username": [
    "This field is required."
  ],
  "password": [
    "This field is required."
  ]
}

POST /api/v1/accounts/token/refresh/

Обновление access-токена с использованием refresh-токена.

Назначение

Access-токен имеет ограниченное время жизни (по умолчанию — 15 минут). После его истечения клиент должен использовать refresh-токен для получения новой пары токенов без необходимости повторной аутентификации с вводом логина и пароля.

HTTP-метод

POST

Параметры запроса

Тело запроса должно быть в формате JSON и содержать следующее поле:

Формат запроса

Content-Type: application/json

Коды состояния HTTP

Пример запроса (curl)

curl -X POST https://<your-server>/api/v1/accounts/token/refresh/ \
  -H "Content-Type: application/json" \
  -d '{
    "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTc0MDM5NDgwMCwiaWF0IjoxNzQwMzA4NDAwLCJqdGkiOiJkZWY5ODc2NTQzMjEiLCJ1c2VyX2lkIjoxfQ.signature"
  }'

Пример успешного ответа

Код состояния: 200 OK

{
  "access": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzQwMzEyODAwLCJpYXQiOjE3NDAzMDkyMDAsImp0aSI6Inh5ejk4NzY1NDMyMSIsInVzZXJfaWQiOjF9.signature",
  "refresh": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoicmVmcmVzaCIsImV4cCI6MTc0MDM5NDgwMCwiaWF0IjoxNzQwMzA4NDAwLCJqdGkiOiJkZWY5ODc2NTQzMjEiLCJ1c2VyX2lkIjoxfQ.signature"
}

Примечание: В ответе возвращается новая пара токенов. Рекомендуется сохранять оба токена, так как refresh-токен также может быть обновлён.

Пример ответа при недействительном токене

Код состояния: 401 Unauthorized

{
  "detail": "Token is invalid or expired",
  "code": "token_not_valid"
}

POST /api/v1/accounts/token/verify/

Проверка валидности JWT-токена.

Назначение

Используется для проверки того, что токен является действительным и не был отозван. Метод не возвращает содержимое токена, только подтверждает его валидность.

HTTP-метод

POST

Параметры запроса

Тело запроса должно быть в формате JSON и содержать следующее поле:

Формат запроса

Content-Type: application/json

Коды состояния HTTP

Пример запроса (curl)

curl -X POST https://<your-server>/api/v1/accounts/token/verify/ \
  -H "Content-Type: application/json" \
  -d '{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzQwMzEyMDAwLCJpYXQiOjE3NDAzMDg0MDAsImp0aSI6ImFiYzEyMzQ1Njc4OSIsInVzZXJfaWQiOjF9.signature"
  }'

Пример успешного ответа

Код состояния: 200 OK

{
  "token_type": "access",
  "exp": 1740312000,
  "iat": 1740308400,
  "jti": "abc123456789"
}

Пример ответа при недействительном токене

Код состояния: 401 Unauthorized

{
  "detail": "Token is invalid or expired",
  "code": "token_not_valid"
}

Сценарии использования

Первичная аутентификация

1. Клиент отправляет POST-запрос на /api/v1/accounts/token/ с логином и паролем.
2. Сервер возвращает пару токенов (access и refresh).
3. Клиент сохраняет токены в безопасном хранилище.
4. Клиент использует access-токен для доступа к защищённым ресурсам API.

Обновление токена

1. При получении ответа 401 Unauthorized от защищённого ресурса клиент проверяет срок действия access-токена.
2. Клиент отправляет POST-запрос на /api/v1/accounts/token/refresh/ с refresh-токеном.
3. Сервер возвращает новую пару токенов.
4. Клиент повторяет исходный запрос с новым access-токеном.

Проверка токена перед запросом

1. Перед отправкой запроса к защищённому ресурсу клиент может проверить валидность токена через /api/v1/accounts/token/verify/.
2. При получении ответа 200 OK клиент продолжает работу.
3. При получении ответа 401 Unauthorized клиент выполняет процедуру обновления токена.

Рекомендации по безопасности

Хранение токенов

• Access-токен следует хранить в оперативной памяти приложения. Избегайте сохранения в localStorage или sessionStorage браузера из-за риска XSS-атак.
• Refresh-токен требует особой защиты. Рекомендуется использовать httpOnly cookies или безопасное серверное хранилище.

Передача токенов

При запросах к защищённым ресурсам передавайте access-токен в заголовке Authorization:

curl -X GET https://<your-server>/api/v1/protected-resource/ \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Время жизни токенов

• Access-токен: короткое время жизни (рекомендуется 5–15 минут) для минимизации рисков при компрометации.
• Refresh-токен: длительное время жизни (часы, дни или недели) в зависимости от требований безопасности системы.

Отзыв токенов

В случае подозрения на компрометацию токенов рекомендуется:

• принудительно завершить сессию пользователя на сервере;
• потребовать повторную аутентификацию;
• реализовать механизм чёрных списков токенов (token blacklist).

Обработка ошибок

Типовые ошибки

Формат ответов об ошибках

Все ошибки возвращаются в едином формате:

{
  "detail": "Описание ошибки"
}

Для ошибок валидации полей:

{
  "field_name": [
    "Описание ошибки поля"
  ]
}