Autentykacja

Tokeny Bearer ze szczegółowymi scopes. Klucze sandboxowe omijają limit planu i nie zapisują historii.

Format klucza

Wszystkie klucze mają format nk_(live|test)_ + 36 znaków hex (44 znaki łącznie). Pierwsze 12 znaków (np. nk_live_a3f9) to publiczny prefix, który możesz bezpiecznie pokazywać w logach i UI. Reszta to sekret - w bazie przechowywany jako SHA-256 hash.

bash

# Live - produkcja
nk_live_a3f9c1d8b2e7f4a1c6d9e0b3a4f7c2d5e8

# Sandbox - bez quoty, bez historii
nk_test_8e2c1f9a7d4b6e3c0a5f8d7b9e1c4a2f6d3b

Wysyłanie klucza

Każde żądanie musi mieć nagłówek Authorization: Bearer <klucz>:

bash

curl https://api.naprawksef.pl/api/v1/me \
  -H "Authorization: Bearer nk_live_a3f9..."

Klucze SDK (TypeScript i PHP) walidują format przed pierwszym requestem - błąd konfiguracji wykryjesz na poziomie konstruktora.

Sandbox vs produkcja

Cecha	nk_live_*	nk_test_*
Quota planu	Konsumuje	Omija
Historia walidacji	Zapisuje	Nie zapisuje
Emisja webhooków	Tak	Tak (do endpointów testowych)
Limit zapytań na klucz	Zależny od planu (np. 600/min)	Zależny od planu (taki sam)

Scopes

Każdy klucz nosi listę uprawnień. Endpointy odrzucają żądania z brakującym scope:

Scope	Endpointy
validate	POST /validate
correction	POST /correction/analyze, POST /correction/build
scenarios	GET /scenarios
webhooks	CRUD /webhooks
reports	GET /reports (planowane)

Zasada najmniejszych uprawnień

Twórz osobny klucz dla każdej integracji i daj mu wyłącznie scope, których faktycznie potrzebuje. To ogranicza powierzchnię ataku w razie wycieku.

Lifecycle i revoke

Wygaśnięcie - opcjonalnie ustaw expires_at; po tej dacie klucz jest automatycznie unieważniany. Cron auto-expire uruchamia się co godzinę.
Ręczne revoke - natychmiastowe. Wszystkie aktywne sesje zostają unieważnione, każdy kolejny request zwraca 401 INVALID_KEY.
Ślad audytu - w dashboardzie widzisz, kiedy klucz był użyty, z jakiego IP, ile requestów dziennie / total oraz kto i kiedy unieważnił klucz.

Przechowywanie kluczy

Nigdy w repo

Klucze API nie należą do kodu, plików .env w git, frontendu, ani publicznych snippetów. Trzymaj je w zarządzanym sekret managerze (AWS/GCP/Azure Secrets Manager, Doppler, Infisical, 1Password Connect) i wstrzykuj jako zmienne środowiskowe przy starcie procesu.