Документація API/Початок роботи/Авторизація і токени

Авторизація і токени

Кожен запит до API підписується персональним токеном. Токен діє від імені конкретного користувача й має рівно його права.

Налаштування → APIAuthorization: Bearer <token>Права: роль користувача

Створення токена

Відкрийте Налаштування → API, вкладка «Токени та доступ», і натисніть «Створити токен».
Вкажіть назву (де використовується), термін дії та користувача, від імені якого діятиме токен.
Скопіюйте токен одразу: повністю він показується один раз. У списку далі видно лише slm_live_••••8f9a.

Поле	Що означає
Назва	Щоб у списку й журналі було зрозуміло, яка інтеграція ходить: «Сайт», «Prom.ua», «Power BI».
Термін дії	30 днів, 90 днів, 1 рік або безстроково (не рекомендується). Прострочений токен отримує 401.
Користувач	Від чийого імені діє токен. Усі зміни в історії записів будуть від цього користувача. Можна обрати лише користувача, чиї права не ширші за ваші.

Права токена

Токен не має власного набору правВін повністю повторює права ролі свого користувача на кожен запит, у реальному часі. Змінили роль, і права токена змінились, перевипуск не потрібен.

●Окремий сервісний користувач на кожну інтеграцію, наприклад «Інтеграція Prom», з окремою роллю.
●Мінімум прав. Інтеграції замовлень не потрібні фінанси й зарплата, тож не давайте їх ролі.
●Режим «лише свої» (owned) працює і в API: токен бачить та змінює тільки записи, де його користувач є відповідальним.
●Дочірні дані за правом батька. Позиції замовлення змінює той, хто може змінювати замовлення.

Запит із токеном

GET /api/v1/contact/42 HTTP/1.1
Host: acme.silium.io
Authorization: Bearer slm_live_7Qe...8f9a
Accept: application/json

cURL

curl "https://<компанія>.silium.io/api/v1/contact?per-page=10" \
  -H "Authorization: Bearer $SILIUM_TOKEN"

JavaScript (fetch)

const res = await fetch('https://<компанія>.silium.io/api/v1/contact?per-page=10', {
  headers: { Authorization: `Bearer ${process.env.SILIUM_TOKEN}` },
})
if (!res.ok) throw new Error((await res.json()).error.message)
const { items, total } = await res.json()

Python (requests)

import os, requests

r = requests.get(
    "https://<компанія>.silium.io/api/v1/contact",
    headers={"Authorization": f"Bearer {os.environ['SILIUM_TOKEN']}"},
    params={"per-page": 10},
    timeout=30,
)
r.raise_for_status()
items = r.json()["items"]

Білий список IP

Для кожного токена можна обмежити адреси, з яких він працює: окремі IP (203.0.113.7) або мережі у форматі CIDR (203.0.113.0/24, IPv6 теж). Порожній список означає «без обмежень». Запит з іншої адреси отримує 403.

●Мережу записуємо в канонічному вигляді: 10.0.0.7/24 збережеться як 10.0.0.0/24.
●Некоректний запис не зберігається (422). Правило «весь інтернет» (0.0.0.0/0) не приймається: просто залиште список порожнім.

Журнал запитів

У вкладці «Журнал запитів» видно кожен виклик: токен, метод, шлях, код відповіді, тривалість, IP і ціну в очках квоти. Журнал зберігається 30 днів.

Помилки авторизації

Код	error.code	Причина
`401`	`unauthorized`	Немає заголовка, токен невідомий, вимкнений, прострочений або його користувача видалено.
`403`	`forbidden`	Адреса поза білим списком IP або ролі бракує права на дію.
`429`	`rate_limited`	Після 30 невдалих спроб авторизації за хвилину з однієї адреси настає пауза до кінця хвилини. Інші причини описано в розділі Ліміти та квоти.

Безпека

●Тримайте токен у змінних середовища чи сховищі секретів, не в коді, Git чи логах.
●У разі витоку видаліть токен у Налаштування → API: він перестає працювати одразу.
●Обмежуйте токен білим списком IP, якщо інтеграція працює з фіксованих адрес.
●Для довгих інтеграцій ставте обмежений термін і плануйте ротацію.