Ключі API та області доступу

Кожен запит до Sursa API виконується з ключем API вашої організації. Ключ належить організації, а не людині: він працює й далі, коли працівник, який його створив, іде з компанії, а те, що ключ може робити, задано в самому ключі.

Що ключу дозволено робити

Три налаштування ключа визначають, що запит із ним може бачити й змінювати. Кожне лише звужує інші.

Налаштування	Що воно визначає
Роль	`admin`, `editor`, `verifier` або `viewer` — ті самі ролі, що й у людей. Ключ може робити те, що може користувач із цією роллю.
Області доступу	Які частини API ключ може викликати, наприклад `cards:read` або `webhooks:manage`. Див. Області доступу ключа.
Профіль доступу	Необов’язково. Обмежує ключ категоріями знань, які дозволяє профіль, як користувача з цим профілем.

Ключ також можна обмежити певними колекціями й задати йому строк дії. Запит поза цими межами завершується помилкою: відсутня область доступу повертає 403 з кодом api_keys.scope, а об’єкт, якого ключ не може бачити, повертає 404 — точно так, ніби його не існує.

Надайте кожній інтеграції власний ключ із найвужчими роллю й областями доступу, яких вона потребує. Завданню синхронізації, яке лише записує документи, не потрібен admin; завданню звітності не потрібні області доступу на запис.

Створіть ключ

Адміністратор організації створює ключі в Sursa в розділі Administration → API keys (адміністрування → ключі API) або через POST /v1/api-keys із ключем чи сесією, що мають роль admin:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "role": "editor",
    "expires_at": "2027-06-30T00:00:00Z"
  }'

Відповідь містить значення ключа в key. Його показують один раз: Sursa зберігає лише його хеш і не може показати ключ знову. Ключ має вигляд kb_, за яким ідуть 43 символи; перші символи (prefix) показано в списку ключів, щоб ключі можна було розрізнити.

Без scopes ключ отримує області доступу своєї ролі. Передайте scopes, щоб звузити його ще більше. Без expires_at строк дії ключа не закінчується.

Зберігайте ключі в таємниці

Зберігайте ключі в менеджері секретів або у змінних середовища свого сервісу, ніколи — у вихідному коді.
Використовуйте ключі лише зі своїх серверів. Sursa приймає запити з браузерів (CORS відкрито), але ключ на вебсторінці бачить кожен, хто її відкриває.
Ніколи не передавайте ключ в URL. Надсилайте його лише в заголовку Authorization.
Якщо ключ потрапив у чужі руки, негайно відкличте його й створіть новий.

Перевірте ключ

GET /v1/me повертає ключ, його роль, чинні області доступу, профіль доступу, строк дії та ліміт частоти. Ця операція працює з будь-яким дійсним ключем, хоч би які області доступу він мав, тож використовуйте її для перевірки з’єднання вашої інтеграції й під час з’ясування причин 403.

Перевипустіть ключ

Ротація замінює ключ без зупинки інтеграції. Найшвидший спосіб — перевипустити ключ: POST /v1/api-keys/{key_id}/roll видає нове значення того самого ключа з тими самими роллю, областями доступу, колекціями й строком дії. Попереднє значення працює ще overlap_hours (типово 24 години, до 168), тож за цей час можна розгорнути нове значення; POST /v1/api-keys/{key_id}/revoke-previous достроково завершує перекриття.

Щоб натомість замінити ключ іншим ключем:

Створіть новий ключ із тими самими роллю, областями доступу й профілем доступу.
Розгорніть новий ключ у своїй інтеграції.
Стежте за старим ключем у Administration → API keys (або за last_used у GET /v1/api-keys), доки його не перестануть використовувати.
Відкличте старий ключ.

Задавайте ключам строк дії й перевипускайте їх до його закінчення. Sursa попереджає адміністраторів організації перед закінченням строку дії ключа; ключ, строк дії якого минув, повертає 401 з кодом api_keys.expired.

Відкличте ключ

Відкликайте ключ у Administration → API keys або через DELETE /v1/api-keys/{key_id}. Відкликання набуває чинності за лічені секунди на кожному сервері API. Запити з відкликаним ключем повертають 401 з кодом auth.not_authenticated.

Ключі власного джерела

Власне джерело має власний вид ключа. Такий ключ починається з kbsrc_, може лише записувати документи в це одне джерело й не може нічого читати чи шукати. Це найбезпечніший ключ для платформи інтеграцій, як-от Zapier. Створіть його на сторінці джерела в розділі API keys (ключі API джерела) або через POST /v1/sources/{source_id}/push-keys.

Коли ключі недоступні

Ключі API входять до тарифу організації. Якщо тариф їх не містить, створення ключа й кожен запит із ключем повертають 403 з кодом api_keys.feature_disabled.