Klucze API

Klucz API upoważnia system zewnętrzny, na przykład Państwa system ERP, do korzystania z REST API v1 exoCortex: otwierania zgłoszeń, odczytywania ich stanu i dodawania komentarzy. Każdy klucz należy do jednego tenanta i widzi wyłącznie zgłoszenia tego tenanta.

Tworzenie klucza

1. W exoCortex Core należy otworzyć Integrations → API keys. Wymagana jest rola administracyjna, na przykład it_admin lub integration_admin.
2. Należy nadać kluczowi nazwę wskazującą, kto go używa, na przykład „Konektor ERP”.
3. Należy wybrać scope, czyli zakres działań dozwolonych dla klucza (zob. niżej).
4. Należy skopiować pełny klucz i zapisać go w menedżerze sekretów systemu, który będzie go używał. exoCortex wyświetla go tylko raz i przechowuje wyłącznie jego skrót: w razie utraty klucza trzeba utworzyć nowy.

Klucz ma postać nhk.<keyid>.<secret>. keyid identyfikuje klucz na liście; secret znają wyłącznie Państwo.

Scope

Scope	Co umożliwia
tickets:create	Otwieranie zgłoszeń
tickets:read	Odczytywanie stanu zgłoszenia
tickets:comment	Dodawanie komentarzy do zgłoszenia
tickets:*	Wszystkie operacje na zgłoszeniach
*	Wszystko, na co pozwala API v1

Każdemu kluczowi należy przypisać tylko potrzebne mu scope. Klucz bez scope ma pełny dostęp do API v1: jest to dopuszczalne, ale niezalecane.

Używanie klucza

Klucz należy przesyłać w nagłówku Authorization każdego żądania:

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" }

Alternatywnie można użyć nagłówka X-NH-API-Key. Tenanta nie trzeba wskazywać: exoCortex ustala go na podstawie klucza.

Przy otwieraniu zgłoszenia należy zawsze używać nagłówka Idempotency-Key: jeśli żądanie zostanie powtórzone z tym samym kluczem idempotencji, zwrócone zostanie już utworzone zgłoszenie zamiast duplikatu.

Limity częstotliwości

Każdy klucz ma limit żądań: wartość domyślna to 600 żądań na 60 sekund. Każda odpowiedź informuje o bieżącym stanie:

Nagłówek	Znaczenie
RateLimit-Limit	Liczba żądań dozwolonych w oknie
RateLimit-Remaining	Liczba żądań, które jeszcze pozostały
RateLimit-Reset	Liczba sekund do nowego okna
Retry-After	Tylko w odpowiedzi 429: liczba sekund, którą należy odczekać przed ponowieniem

Błędy

Błędy API v1 zwracają JSON z ok: false, czytelnym komunikatem w error i stałym kodem w code. Logikę klienta należy opierać na code, a nie na komunikacie.

code	Stan HTTP	Co zrobić
missing_api_key	401	Dodać nagłówek Authorization
invalid_api_key	401	Sprawdzić klucz: może być błędny lub unieważniony
insufficient_scope	403	Dodać do klucza scope wskazany w required_scope
api_key_disabled	403	Klucz jest wyłączony: należy użyć aktywnego klucza
validation_error	400	Poprawić pole wskazane w field
not_found	404	Zgłoszenie nie istnieje lub nie należy do tenanta klucza
rate_limited	429	Odczekać liczbę sekund wskazaną w Retry-After
ingest_failed	500	Ponowić próbę z tym samym Idempotency-Key

exoCortex może dodawać nowe kody: w przypadku otrzymania nieznanego kodu należy podjąć decyzję na podstawie stanu HTTP.

Unieważnianie klucza

W Integrations → API keys można unieważnić klucz, gdy system już go nie używa lub gdy istnieje podejrzenie, że został ujawniony. Unieważnienie działa natychmiast. Lista pokazuje też ostatnie użycie każdego klucza, co ułatwia znalezienie nieaktywnych kluczy.

Wycofywane klucze nh_…

Klucze w starym formacie nh_… działają do 30 czerwca 2027. Odpowiedzi na żądania z tymi kluczami zawierają nagłówki Deprecation i Sunset. Aby przeprowadzić migrację, należy utworzyć klucz nhk. z potrzebnymi scope, zaktualizować system, który go używa, a następnie unieważnić stary klucz.