Uwierzytelnianie

Format klucza API, nagłówek Authorization, jednorazowe wyświetlenie i rotacja z oknem karencji.

Każde żądanie do /api/external/v1/* wymaga klucza API. Klucze są przypisane do workspace i noszą jawną listę zakresów — trasa, do której zakresu brakuje, odpowiada 403 API_KEY_INSUFFICIENT_SCOPE.

Skąd wziąć klucz

W Portalu wejdź w Ustawienia → Integracje → Klucze API.
Kliknij Wygeneruj nowy klucz API.
Nadaj nazwę i zaznacz zakresy — minimalny zestaw, jaki wystarcza integracji.
Skopiuj pełny klucz od razu. Pokazujemy go jeden raz.
Wrzuć go do menedżera sekretów albo zmiennej środowiskowej. Nigdy do repozytorium.

Klucz zobaczysz tylko raz

Przechowujemy wyłącznie skrót sekretu (HMAC-SHA256), więc nie możemy pokazać klucza ponownie — nawet gdybyśmy chcieli. Zgubiony klucz zastępuje się rotacją albo nowym kluczem.

Format klucza

Produkcja:  mflo_live_<keyId>_<secret>
Deweloperka: mflo_test_<keyId>_<secret>

keyId to 16 znaków szesnastkowych — część jawna, widoczna na liście kluczy i używana do korelacji logów. secret to 64 znaki szesnastkowe.

Przykład:

mflo_live_a1b2c3d4e5f6a7b8_9f8e7d6c5b4a39281706f5e4d3c2b1a0aabbccddeeff00112233445566778899

Prefiks nie jest gwarancją środowiska

Prefiks mflo_live_ albo mflo_test_ nie mówi, przeciwko czemu klucz działa — oba weryfikują się identycznie. To kosmetyka; nie buduj na tym logiki.

Nagłówek

Klucz jedzie w nagłówku Authorization ze schematem Bearer:

Authorization: Bearer mflo_live_a1b2c3d4e5f6a7b8_x9y8z7w6...

curl -s https://app.mediflo.ai/api/external/v1/bots \
  -H "Authorization: Bearer mflo_live_..." \
  -H "Content-Type: application/json"

Co może pójść nie tak

Status	Kod	Znaczenie
401	`API_KEY_INVALID`	Format klucza jest zły albo klucza nie ma
401	`API_KEY_EXPIRED`	Klucz minął datę ważności
401	`API_KEY_REVOKED`	Klucz został unieważniony
403	`API_KEY_INSUFFICIENT_SCOPE`	Klucz jest dobry, ale brakuje mu zakresu; `details` niesie `requiredScope` i `availableScopes`
503	`EXTERNAL_API_UNAVAILABLE`	Nie udało nam się zweryfikować klucza z powodu awarii po naszej stronie

401 jest celowo nierozróżnialne poza „wygasł" i „unieważniony" — żeby nie dało się nim sondować, które klucze istnieją.

`503` to nigdy nie jest problem z kluczem

EXTERNAL_API_UNAVAILABLE znaczy, że nasz backend nie odpowiedział podczas weryfikacji. Ponów żądanie z wykładniczym odczekaniem. Nie rotuj kluczy w reakcji na 503 — Twoje poświadczenia są w porządku.

Rotacja klucza

Rotacja jest tylko przez API — w Portalu nie ma jeszcze przycisku.

POST /api/api-keys/{apiKeyId}/rotate

To endpoint zarządczy, nie część /api/external/v1: uwierzytelnia go sesja Portalu (nie klucz Bearer mflo_…) i wymaga uprawnienia api-keys.manage. {apiKeyId} to UUID id klucza — wartość z listy kluczy API, a nie jawny keyId.

curl -s -X POST \
  'https://app.mediflo.ai/api/api-keys/550e8400-e29b-41d4-a716-446655440000/rotate' \
  -H 'Content-Type: application/json' \
  -H 'Cookie: <ciasteczko sesji Portalu>' \
  -d '{ "graceHours": 24 }'

graceHours — jak długo działa poprzedni sekret. Liczba całkowita 1–168 (7 dni), domyślnie 24. Puste ciało też jest przyjmowane i bierze wartość domyślną.
Odpowiedź zawiera nowy formattedKey raz. Nigdy więcej go nie pokażemy.
Jawny keyId się nie zmienia, więc korelacja logów przeżywa rotację.
Do końca okna karencji uwierzytelnia i stary, i nowy sekret. Wdróż nowy klucz, potwierdź ruch, poczekaj aż okno się zamknie.
Klucza unieważnionego nie da się zrotować (409 API_KEY_ROTATE_REVOKED).

Honorujemy tylko jeden poprzedni sekret

Rotacja wykonana w trakcie otwartego okna karencji sprawia, że poprzednikiem staje się sekret z drugiej rotacji — a pierwotny przestaje działać natychmiast, przed końcem obiecanego okna. Zrotuj raz, dokończ wdrożenie, dopiero potem rotuj ponownie.

Wygaśnięcie jest wyliczane, nie zamiatane: kolumny poprzedniego sekretu nie są czyszczone po upływie okna — weryfikacja po prostu przestaje je akceptować, gdy previousSecretExpiresAt jest w przeszłości.

Higiena kluczy

Osobne klucze dla osobnych integracji. Wtedy unieważnienie jednej nie kładzie pozostałych, a dziennik audytu mówi, kto co zrobił.
Minimalne zakresy. Zobacz Zakresy.
Data ważności przy tworzeniu, jeśli integracja jest tymczasowa.
Podglądaj „Ostatnio użyty" na liście kluczy i unieważniaj to, czego nikt nie używa.
Klucz wyciekł? Unieważnij go, nie czekając na rotację.