Autentykacja

Bearer tokens z fine-grained scopes. Klucze sandbox bypassują quotę 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	Bypass
Historia walidacji	Zapisuje	Nie zapisuje
Webhooks emit	Tak	Tak (do test endpointów)
Rate limit per klucz	Plan-bound (np. 600/min)	Plan-bound (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
read:history	GET /history (planowane)

Principle of least privilege

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 auto-revoke. 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.
Audit trail - w dashboardzie widzisz kiedy klucz był użyty, z jakiego IP, ile requestów dziennie / total, oraz kto i kiedy wykonał revoke.

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.