API-ключі

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

Як створити ключ

1. В exoCortex Core відкрий Integrations → API keys. Потрібна адміністративна роль, наприклад it_admin або integration_admin.
2. Дай ключу назву, яка показує, хто ним користується, наприклад «Конектор ERP».
3. Вибери scope, тобто що ключ може робити (див. нижче).
4. Скопіюй повний ключ і збережи його в менеджері секретів системи, яка ним користуватиметься. exoCortex показує його лише один раз і зберігає тільки його відбиток: якщо ти його втратиш, створи новий ключ.

Ключ має вигляд nhk.<keyid>.<secret>. keyid ідентифікує ключ у списку; secret знаєш лише ти.

Scope

Scope	Що дозволяє
tickets:create	Створювати тікети
tickets:read	Читати статус тікета
tickets:comment	Додавати коментарі до тікета
tickets:*	Усі операції з тікетами
*	Усе, що дозволяє API v1

Призначай кожному ключу лише ті scope, які йому потрібні. Ключ без scope має повний доступ до API v1: це дозволено, але не рекомендовано.

Як користуватися ключем

Надсилай ключ у заголовку Authorization кожного запиту:

POST /api/v1/tickets HTTP/1.1
Host: exocortex-api.ai-exo-cortex.com
Authorization: Bearer nhk.9f2c4e1a7b3d.…
Content-Type: application/json
Idempotency-Key: 6b1f0c4e-2a7d-4b39-9e51-8c3d2f7a1b60

{ "subject": "Payment gateway returns HTTP 502", "priority": "High" }

Замість нього можна використовувати заголовок X-NH-API-Key. Тенант вказувати не треба: exoCortex визначає його за ключем.

Завжди використовуй Idempotency-Key, коли створюєш тікет: якщо повториш запит із тим самим ключем ідемпотентності, отримаєш уже створений тікет, а не дублікат.

Обмеження частоти запитів

Кожен ключ має ліміт запитів: за замовчуванням — 600 запитів за 60 секунд. Кожна відповідь показує, скільки ти вже використав:

Заголовок	Значення
RateLimit-Limit	Скільки запитів дозволено у вікні
RateLimit-Remaining	Скільки запитів ще доступно
RateLimit-Reset	Скільки секунд до нового вікна
Retry-After	Лише з відповіддю 429: скільки секунд почекати перед повторною спробою

Помилки

Помилки API v1 повертають JSON з ok: false, зрозумілим повідомленням в error і стабільним кодом у code. Будуй логіку свого клієнта на code, а не на повідомленні.

code	HTTP-статус	Що робити
missing_api_key	401	Додай заголовок Authorization
invalid_api_key	401	Перевір ключ: він може бути неправильним або відкликаним
insufficient_scope	403	Додай ключу scope, вказаний у required_scope
api_key_disabled	403	Ключ деактивовано: використовуй активний ключ
validation_error	400	Виправ поле, вказане в field
not_found	404	Тікет не існує або не належить тенанту ключа
rate_limited	429	Зачекай стільки секунд, скільки вказано в Retry-After
ingest_failed	500	Повтори запит із тим самим Idempotency-Key

exoCortex може додавати нові коди: якщо отримаєш невідомий код, вирішуй, що робити, за HTTP-статусом.

Як відкликати ключ

У Integrations → API keys можна відкликати ключ, коли система більше ним не користується або якщо ти підозрюєш, що його розкрито. Відкликання діє одразу. Список також показує останнє використання кожного ключа: це допомагає знаходити неактивні ключі.

Застарілі ключі nh_…

Ключі в старому форматі nh_… працюють до 30 червня 2027 року. Відповіді на запити з такими ключами містять заголовки Deprecation і Sunset. Щоб перейти на новий формат, створи ключ nhk. із потрібними scope, онови систему, що ним користується, а потім відклич старий ключ.