Перейти до змісту

Авторизація

SMSBAT ChatHub API використовує дворівневу систему аутентифікації на основі JWT токенів: токени компанії та токени операторів.

Процес Авторизації

graph TD
    A[Облікові Дані] --> B[Отримати Токен Компанії]
    B --> C[Використати Токен Компанії]
    C --> D[Отримати Токен Оператора]
    D --> E[Використати Токен Оператора]
    E --> F[Валідація Токена]

Токен Компанії

Токени компанії надають доступ до ChatHub API на рівні організації.

Отримання Токена Компанії

Ендпоінт: POST /api/company/get-token

Запит:

curl -X POST https://chatapi.smsbat.com/api/company/get-token \
  -H "Content-Type: application/json" \
  -d '{
    "login": "your-company-login",
    "password": "your-company-password"
  }'

Тіло Запиту (Request Body):

{
  "login": "string",
  "password": "string"
}

Відповідь:

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"

Рядок відповіді — це JWT токен.

Використання Токена Компанії

Включайте токен компанії в API запити одним із двох методів:

Метод 1: Заголовок Authorization (Рекомендовано)

curl -X GET https://chatapi.smsbat.com/api/company/organization \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Метод 2: Заголовок X-Authorization-Key

curl -X GET https://chatapi.smsbat.com/api/company/organization \
  -H "X-Authorization-Key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Токен Оператора

Токени оператора надають доступ до дій від імені окремого оператора в межах організації.

Отримання Токена Оператора

Ендпоінт: POST /api/operator/get-token

Запит:

curl -X POST https://chatapi.smsbat.com/api/operator/get-token \
  -H "Authorization: Bearer {company-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 123,
    "expiresAt": "2025-12-31T23:59:59Z"
  }'

Тіло Запиту:

{
  "id": 0,
  "expiresAt": "2025-01-20T14:33:34.147Z"
}

Параметри:

Параметр Тип Обов'язково Опис
id integer Так ID оператора
expiresAt string (ISO 8601) Так Дата і час закінчення терміну дії токена (максимум через 24 години від поточного часу)

Важливо: Максимальний час життя токена становить 24 години. Параметр expiresAt не може перевищувати 24 години в майбутньому.

Відповідь:

"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcGVyYXRvcl9pZCI6MTIzLCJleHAiOjE3Mzc0MTI3OTl9.example_signature"

Використання Токена Оператора

Включайте токен оператора в API запити (наприклад, для віджета чату):

curl -X GET https://chatapi.smsbat.com/api/operator \
  -H "Authorization: Bearer {operator-token}"

Валідація Токена

Перевірте, чи токен все ще дійсний перед його використанням.

Ендпоінт: POST /api/operator/validate-token

Запит:

curl -X POST https://chatapi.smsbat.com/api/operator/validate-token \
  -H "Authorization: Bearer {company-token}" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Тіло Запиту:

{
  "token": "string"
}

Відповідь (Вдала перевірка, валідний токен):

{
  "isValid": true,
  "operatorId": 123,
  "clientId": 0,
  "expiresAt": "2025-12-31T23:59:59Z",
  "error": null
}

Відповідь (Невалідний токен):

{
  "isValid": false,
  "error": "Invalid token"
}

Термін Дії Токенів (Expiration)

Токени Компанії

  • Не мають явної дати закінчення в API відповіді.
  • Зв'яжіться із своїм менеджером для узгодження життєвого циклу токенів компанії.
  • Рекомендується періодично (раз на 3-6 місяців) змінювати (ротувати) токени з міркувань безпеки.

Токени Операторів

  • Термін дії визначається під час запиту на отримання токена (параметр expiresAt).
  • Обов'язково валідуйте токен перед його використанням (перевірка чи він не сплив або не відкликаний).
  • Запрошуйте новий токен перед закінченням терміну дії.

Кращі Практики

Зберігання Токенів

  • ✅ Зберігайте токени в безпечних місцях (зашифровані бази даних, Secret Managers).
  • ✅ Ніколи не комітьте (commit) токени в систему контролю версій (напр. в Git).
  • ✅ Використовуйте змінні середовища (Environment Variables) для роботи з обліковими даними.
  • ❌ Не зберігайте токени у відкритому вигляді (Plain text).
  • ❌ Не розкривайте Токен Компанії в клієнтському коді (Frontend, Mobile App).

Обробка помилок (Error Handling)

Завжди перевіряйте статуси HTTP: - 401 Unauthorized означає, що токен неправильний, або його термін дії закінчився. - 403 Forbidden означає, що токен не має необхідних прав для даної операції.

Наступні Кроки