API Аутентификации

Общая информация

Базовый URL

/api/v1/auth

Заголовок аутентификации

Authorization: Bearer <access_token>

Формат ответа

Все ответы следуют стандартному формату:

// Успешный ответ
interface SuccessResponse<T> {
  success: true;
  data: T;
  meta?: {
    [key: string]: unknown;
  };
}

// Ответ с ошибкой
interface ErrorResponse {
  success: false;
  error: {
    code: string;
    message: string;
    details?: Record<string, string[]>;
  };
}

Ограничения запросов

Эндпоинт	Лимит
POST /register	5/мин
POST /login	5/мин
POST /forgot-password	3/час
POST /reset-password	3/час
Другие эндпоинты аутентификации	100/мин

Заголовки ограничения запросов

X-RateLimit-Limit: 5
X-RateLimit-Remaining: 4
X-RateLimit-Reset: 1705329600

---

Эндпоинты

POST /api/v1/auth/register

Регистрация нового пользователя.

Аутентификация: Публичный

Лимит запросов: 5 запросов в минуту

Тело запроса

interface RegisterRequest {
  email: string;           // Действительный email адрес
  password: string;        // Мин. 8 символов, 1 заглавная, 1 строчная, 1 цифра
  firstName: string;       // 2-100 символов
  lastName: string;        // 2-100 символов
  phone?: string;          // Опционально, формат E.164
  referralCode?: string;   // Опционально, реферальный код спонсора
  acceptTerms: boolean;    // Должно быть true
  acceptPrivacy: boolean;  // Должно быть true
}

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

Нет

Ответ (201 Created)

interface RegisterResponse {
  id: string;              // UUID
  email: string;
  status: 'PENDING_VERIFICATION';
  profile: {
    firstName: string;
    lastName: string;
  };
  createdAt: string;       // ISO 8601
}

Ответы с ошибками

Статус	Код	Описание
400	VALIDATION_ERROR	Неверные входные данные
409	EMAIL_ALREADY_EXISTS	Email уже зарегистрирован
409	PHONE_ALREADY_EXISTS	Номер телефона уже зарегистрирован
404	INVALID_REFERRAL_CODE	Реферальный код не существует
429	RATE_LIMIT_EXCEEDED	Слишком много попыток регистрации

Пример

Запрос:

curl -X POST https://api.iwm-platform.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123",
    "firstName": "John",
    "lastName": "Doe",
    "referralCode": "ABC123XY",
    "acceptTerms": true,
    "acceptPrivacy": true
  }'

Ответ:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "status": "PENDING_VERIFICATION",
    "profile": {
      "firstName": "John",
      "lastName": "Doe"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

---

POST /api/v1/auth/login

Аутентификация пользователя и получение токенов доступа.

Аутентификация: Публичный

Лимит запросов: 5 запросов в минуту

Тело запроса

interface LoginRequest {
  email: string;
  password: string;
  deviceFingerprint?: string;  // Для отслеживания сессий
  twoFactorCode?: string;      // Обязательно, если включена 2FA
}

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

Нет

Ответ (200 OK)

interface LoginResponse {
  accessToken: string;         // JWT, истекает через 15 минут
  refreshToken: string;        // Непрозрачный токен, истекает через 7 дней
  expiresIn: number;           // Секунды до истечения access token
  tokenType: 'Bearer';
  user: {
    id: string;
    email: string;
    status: string;
    profile: {
      firstName: string;
      lastName: string;
      avatarUrl: string | null;
    };
    roles: string[];
    requiresTwoFactor: boolean;
  };
}

Ответ (200 OK - Требуется 2FA)

interface TwoFactorRequiredResponse {
  requiresTwoFactor: true;
  tempToken: string;           // Временный токен для верификации 2FA
  methods: ('TOTP' | 'SMS' | 'EMAIL')[];
}

Ответы с ошибками

Статус	Код	Описание
400	VALIDATION_ERROR	Неверные входные данные
401	INVALID_CREDENTIALS	Неверный email или пароль
401	TWO_FACTOR_REQUIRED	Требуется код 2FA
401	INVALID_TWO_FACTOR_CODE	Неверный код 2FA
403	ACCOUNT_NOT_VERIFIED	Email не подтвержден
403	ACCOUNT_SUSPENDED	Аккаунт приостановлен
403	ACCOUNT_BANNED	Аккаунт заблокирован
429	RATE_LIMIT_EXCEEDED	Слишком много попыток входа

Пример

Запрос:

curl -X POST https://api.iwm-platform.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123"
  }'

Ответ:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
    "expiresIn": 900,
    "tokenType": "Bearer",
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "user@example.com",
      "status": "ACTIVE",
      "profile": {
        "firstName": "John",
        "lastName": "Doe",
        "avatarUrl": "https://cdn.iwm-platform.com/avatars/550e8400.jpg"
      },
      "roles": ["USER"],
      "requiresTwoFactor": false
    }
  }
}

---

POST /api/v1/auth/logout

Инвалидация текущей сессии и refresh токена.

Аутентификация: Обязательна

Лимит запросов: 100 запросов в минуту

Заголовки запроса

Authorization: Bearer <access_token>

Тело запроса

interface LogoutRequest {
  refreshToken: string;      // Refresh токен для инвалидации
  allDevices?: boolean;      // Если true, выход со всех устройств
}

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

Нет

Ответ (200 OK)

interface LogoutResponse {
  message: string;
  sessionsRevoked: number;
}

Ответы с ошибками

Статус	Код	Описание
401	UNAUTHORIZED	Недействительный или истекший access token
400	INVALID_REFRESH_TOKEN	Refresh токен недействителен или уже отозван

Пример

Запрос:

curl -X POST https://api.iwm-platform.com/api/v1/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4...",
    "allDevices": false
  }'

Ответ:

{
  "success": true,
  "data": {
    "message": "Successfully logged out",
    "sessionsRevoked": 1
  }
}

---

POST /api/v1/auth/refresh

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

Аутентификация: Публичный (использует refresh токен)

Лимит запросов: 100 запросов в минуту

Тело запроса

interface RefreshTokenRequest {
  refreshToken: string;
}

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

Нет

Ответ (200 OK)

interface RefreshTokenResponse {
  accessToken: string;
  refreshToken: string;        // Новый refresh токен (ротация)
  expiresIn: number;
  tokenType: 'Bearer';
}

Ответы с ошибками

Статус	Код	Описание
400	VALIDATION_ERROR	Refresh токен не предоставлен
401	INVALID_REFRESH_TOKEN	Refresh токен недействителен
401	REFRESH_TOKEN_EXPIRED	Refresh токен истек
401	SESSION_REVOKED	Сессия была отозвана

Пример

Запрос:

curl -X POST https://api.iwm-platform.com/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."
  }'

Ответ:

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "bmV3IHJlZnJlc2ggdG9rZW4...",
    "expiresIn": 900,
    "tokenType": "Bearer"
  }
}

---

POST /api/v1/auth/verify-email

Подтверждение email адреса пользователя с помощью токена верификации.

Аутентификация: Публичный

Лимит запросов: 100 запросов в минуту

Тело запроса

interface VerifyEmailRequest {
  token: string;              // Токен верификации email из письма
}

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

Нет

Ответ (200 OK)

interface VerifyEmailResponse {
  message: string;
  user: {
    id: string;
    email: string;
    status: 'ACTIVE';
    emailVerifiedAt: string;
  };
}

Ответы с ошибками

Статус	Код	Описание
400	VALIDATION_ERROR	Токен не предоставлен
400	INVALID_TOKEN	Токен верификации недействителен
400	TOKEN_EXPIRED	Токен верификации истек
409	ALREADY_VERIFIED	Email уже подтвержден

Пример

Запрос:

curl -X POST https://api.iwm-platform.com/api/v1/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Ответ:

{
  "success": true,
  "data": {
    "message": "Email successfully verified",
    "user": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "email": "user@example.com",
      "status": "ACTIVE",
      "emailVerifiedAt": "2024-01-15T10:35:00Z"
    }
  }
}

---

POST /api/v1/auth/resend-verification

Повторная отправка ссылки для подтверждения email.

Аутентификация: Публичный

Лимит запросов: 3 запроса в час

Тело запроса

interface ResendVerificationRequest {
  email: string;
}

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

Нет

Ответ (200 OK)

interface ResendVerificationResponse {
  message: string;
}

Ответы с ошибками

Статус	Код	Описание
400	VALIDATION_ERROR	Неверный формат email
404	USER_NOT_FOUND	Аккаунт с таким email не найден
409	ALREADY_VERIFIED	Email уже подтвержден
429	RATE_LIMIT_EXCEEDED	Слишком много попыток повторной отправки

Пример

Запрос:

curl -X POST https://api.iwm-platform.com/api/v1/auth/resend-verification \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'

Ответ:

{
  "success": true,
  "data": {
    "message": "Verification email sent if account exists"
  }
}

---

POST /api/v1/auth/forgot-password

Запрос ссылки для сброса пароля.

Аутентификация: Публичный

Лимит запросов: 3 запроса в час

Тело запроса

interface ForgotPasswordRequest {
  email: string;
}

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

Нет

Ответ (200 OK)

interface ForgotPasswordResponse {
  message: string;
}

Ответы с ошибками

Статус	Код	Описание
400	VALIDATION_ERROR	Неверный формат email
429	RATE_LIMIT_EXCEEDED	Слишком много попыток сброса

Примечание: В целях безопасности этот эндпоинт всегда возвращает успех, даже если email не существует.

Пример

Запрос:

curl -X POST https://api.iwm-platform.com/api/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'

Ответ:

{
  "success": true,
  "data": {
    "message": "Password reset email sent if account exists"
  }
}

---

POST /api/v1/auth/reset-password

Сброс пароля с использованием токена сброса.

Аутентификация: Публичный

Лимит запросов: 3 запроса в час

Тело запроса

interface ResetPasswordRequest {
  token: string;              // Токен сброса пароля из письма
  password: string;           // Новый пароль (те же требования, что при регистрации)
  confirmPassword: string;    // Должен совпадать с password
}

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

Нет

Ответ (200 OK)

interface ResetPasswordResponse {
  message: string;
}

Ответы с ошибками

Статус	Код	Описание
400	VALIDATION_ERROR	Неверные входные данные
400	PASSWORD_MISMATCH	Пароли не совпадают
400	INVALID_TOKEN	Токен сброса недействителен
400	TOKEN_EXPIRED	Токен сброса истек
400	PASSWORD_TOO_WEAK	Пароль не соответствует требованиям
400	PASSWORD_RECENTLY_USED	Нельзя использовать недавно использованный пароль

Пример

Запрос:

curl -X POST https://api.iwm-platform.com/api/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "password": "NewSecurePass456",
    "confirmPassword": "NewSecurePass456"
  }'

Ответ:

{
  "success": true,
  "data": {
    "message": "Password successfully reset"
  }
}

---

POST /api/v1/auth/2fa/setup

Инициализация настройки двухфакторной аутентификации.

Аутентификация: Обязательна

Лимит запросов: 100 запросов в минуту

Заголовки запроса

Authorization: Bearer <access_token>

Тело запроса

interface TwoFactorSetupRequest {
  method: 'TOTP' | 'SMS' | 'EMAIL';
}

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

Нет

Ответ (200 OK)

interface TwoFactorSetupResponse {
  method: 'TOTP' | 'SMS' | 'EMAIL';
  // Для метода TOTP
  secret?: string;             // Секрет в кодировке Base32
  qrCode?: string;             // Data URL для QR-кода
  manualEntryKey?: string;     // Для ручного ввода в приложение аутентификатор
  // Для методов SMS/EMAIL
  maskedDestination?: string;  // например, "+7***1234" или "u***@example.com"
}

Ответы с ошибками

Статус	Код	Описание
400	VALIDATION_ERROR	Неверный метод
401	UNAUTHORIZED	Недействительный или истекший access token
409	TWO_FACTOR_ALREADY_ENABLED	2FA уже включена
400	PHONE_NOT_VERIFIED	Телефон должен быть подтвержден для метода SMS
400	EMAIL_NOT_VERIFIED	Email должен быть подтвержден для метода EMAIL

Пример

Запрос:

curl -X POST https://api.iwm-platform.com/api/v1/auth/2fa/setup \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "method": "TOTP"
  }'

Ответ:

{
  "success": true,
  "data": {
    "method": "TOTP",
    "secret": "JBSWY3DPEHPK3PXP",
    "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "manualEntryKey": "JBSWY3DPEHPK3PXP"
  }
}

---

POST /api/v1/auth/2fa/verify

Верификация и включение двухфакторной аутентификации.

Аутентификация: Обязательна

Лимит запросов: 100 запросов в минуту

Заголовки запроса

Authorization: Bearer <access_token>

Тело запроса

interface TwoFactorVerifyRequest {
  code: string;               // 6-значный код верификации
}

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

Нет

Ответ (200 OK)

interface TwoFactorVerifyResponse {
  enabled: true;
  method: 'TOTP' | 'SMS' | 'EMAIL';
  backupCodes: string[];       // Одноразовые коды восстановления
}

Ответы с ошибками

Статус	Код	Описание
400	VALIDATION_ERROR	Неверный формат кода
400	INVALID_CODE	Неверный код верификации
400	CODE_EXPIRED	Код верификации истек
401	UNAUTHORIZED	Недействительный или истекший access token
400	SETUP_NOT_INITIATED	Сначала необходимо вызвать /2fa/setup

Пример

Запрос:

curl -X POST https://api.iwm-platform.com/api/v1/auth/2fa/verify \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "code": "123456"
  }'

Ответ:

{
  "success": true,
  "data": {
    "enabled": true,
    "method": "TOTP",
    "backupCodes": [
      "ABCD-1234-EFGH",
      "IJKL-5678-MNOP",
      "QRST-9012-UVWX",
      "YZAB-3456-CDEF",
      "GHIJ-7890-KLMN",
      "OPQR-1234-STUV",
      "WXYZ-5678-ABCD",
      "EFGH-9012-IJKL"
    ]
  }
}

---

POST /api/v1/auth/2fa/disable

Отключение двухфакторной аутентификации.

Аутентификация: Обязательна

Лимит запросов: 100 запросов в минуту

Заголовки запроса

Authorization: Bearer <access_token>

Тело запроса

interface TwoFactorDisableRequest {
  password: string;           // Текущий пароль аккаунта
  code: string;               // Текущий код 2FA или резервный код
}

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

Нет

Ответ (200 OK)

interface TwoFactorDisableResponse {
  disabled: true;
  message: string;
}

Ответы с ошибками

Статус	Код	Описание
400	VALIDATION_ERROR	Неверные входные данные
401	UNAUTHORIZED	Недействительный или истекший access token
401	INVALID_PASSWORD	Неверный пароль
401	INVALID_CODE	Неверный код 2FA
400	TWO_FACTOR_NOT_ENABLED	2FA в данный момент не включена

Пример

Запрос:

curl -X POST https://api.iwm-platform.com/api/v1/auth/2fa/disable \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "password": "SecurePass123",
    "code": "123456"
  }'

Ответ:

{
  "success": true,
  "data": {
    "disabled": true,
    "message": "Two-factor authentication has been disabled"
  }
}

---

GET /api/v1/auth/sessions

Получение списка всех активных сессий текущего пользователя.

Аутентификация: Обязательна

Лимит запросов: 100 запросов в минуту

Заголовки запроса

Authorization: Bearer <access_token>

Тело запроса

Нет

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

Параметр	Тип	Описание
page	number	Номер страницы (опционально)
pageSize	number	Элементов на странице, макс. 50 (опционально)

Ответ (200 OK)

interface SessionsResponse {
  sessions: Session[];
}

interface Session {
  id: string;
  deviceFingerprint: string | null;
  ipAddress: string;
  userAgent: string;
  location: {
    country: string | null;
    city: string | null;
  };
  isCurrent: boolean;
  createdAt: string;
  lastActiveAt: string;
  expiresAt: string;
}

Ответы с ошибками

Статус	Код	Описание
401	UNAUTHORIZED	Недействительный или истекший access token

Пример

Запрос:

curl -X GET "https://api.iwm-platform.com/api/v1/auth/sessions?page=1&pageSize=10" \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Ответ:

{
  "success": true,
  "data": {
    "sessions": [
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "deviceFingerprint": "abc123def456",
        "ipAddress": "192.168.1.1",
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
        "location": {
          "country": "Russia",
          "city": "Moscow"
        },
        "isCurrent": true,
        "createdAt": "2024-01-15T10:30:00Z",
        "lastActiveAt": "2024-01-15T14:45:00Z",
        "expiresAt": "2024-01-22T10:30:00Z"
      },
      {
        "id": "660e8400-e29b-41d4-a716-446655440002",
        "deviceFingerprint": "xyz789ghi012",
        "ipAddress": "192.168.1.2",
        "userAgent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0)...",
        "location": {
          "country": "Russia",
          "city": "Saint Petersburg"
        },
        "isCurrent": false,
        "createdAt": "2024-01-14T08:00:00Z",
        "lastActiveAt": "2024-01-14T12:30:00Z",
        "expiresAt": "2024-01-21T08:00:00Z"
      }
    ]
  },
  "meta": {
    "pagination": {
      "total": 2,
      "page": 1,
      "pageSize": 10,
      "totalPages": 1,
      "hasNext": false,
      "hasPrevious": false
    }
  }
}

---

DELETE /api/v1/auth/sessions/:id

Отзыв определенной сессии.

Аутентификация: Обязательна

Лимит запросов: 100 запросов в минуту

Заголовки запроса

Authorization: Bearer <access_token>

Параметры пути

Параметр	Тип	Описание
id	string (UUID)	ID сессии для отзыва

Тело запроса

Нет

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

Нет

Ответ (200 OK)

interface RevokeSessionResponse {
  message: string;
  sessionId: string;
}

Ответы с ошибками

Статус	Код	Описание
401	UNAUTHORIZED	Недействительный или истекший access token
404	SESSION_NOT_FOUND	Сессия не найдена или принадлежит другому пользователю
400	CANNOT_REVOKE_CURRENT	Нельзя отозвать текущую сессию (используйте /logout)

Пример

Запрос:

curl -X DELETE https://api.iwm-platform.com/api/v1/auth/sessions/660e8400-e29b-41d4-a716-446655440002 \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Ответ:

{
  "success": true,
  "data": {
    "message": "Session revoked successfully",
    "sessionId": "660e8400-e29b-41d4-a716-446655440002"
  }
}

---

Связанные документы

• Стандарты API
• Структура API
• API Пользователей