Uwierzytelnianie: HMAC, key ID, scopes

Każdy request do Commerce API v1 jest podpisany kluczem HMAC. Klucz składa się z publicznego identyfikatora key_id oraz tajnego sekretu. Sekret pokazujemy tylko raz — w chwili utworzenia klucza — więc zapisz go od razu w bezpiecznym miejscu. W przykładach key ID jest zawsze maskowany: cba_test_••••••••.

Model klucza

• key_id — publiczny identyfikator, wysyłany w nagłówku X-CBA-Key-Id.
• sekret — tajny materiał do liczenia podpisu; nigdy nie opuszcza serwera.
• scopes — zakresy uprawnień w modelu deny-by-default (bez nadanego scope request zostaje odrzucony 403).
• wygaśnięcie — klucz ma datę ważności.
• rotacja — wymiana klucza z oknem nakładania starego i nowego.

Nagłówki podpisu

Każdy request niesie komplet nagłówków. Do metod modyfikujących dane (POST, PATCH, DELETE) dołączasz dodatkowo Idempotency-Key.

Jak liczyć podpis

Podpis obejmuje kanoniczny string złożony z sześciu elementów, połączonych znakiem nowej linii w stałej kolejności:

1. metoda HTTP (wielkie litery, np. POST),
2. kanoniczna ścieżka (np. /api/v1/commerce/orders),
3. kanoniczne query (parametry posortowane, puste gdy brak),
4. znacznik czasu (X-CBA-Timestamp),
5. nonce (X-CBA-Nonce),
6. hash body (X-CBA-Content-SHA256).

Na tak zbudowanym stringu liczysz HMAC-SHA256 z użyciem sekretu i umieszczasz wynik w X-CBA-Signature.

CANONICAL="POST\n/api/v1/commerce/orders\n\n2026-07-11T10:00:00Z\n$NONCE\n$BODY_SHA256"
SIGNATURE=$(printf "%b" "$CANONICAL" | openssl dgst -sha256 -hmac "$SECRET" -binary | xxd -p -c 256)
# nagłówek: X-CBA-Signature: hmac-sha256=$SIGNATURE

const canonical = [method, path, query, timestamp, nonce, bodySha256].join('\n');
const signature = crypto.createHmac('sha256', secret).update(canonical).digest('hex');
// header: `X-CBA-Signature: hmac-sha256=${signature}`

$canonical = implode("\n", [$method, $path, $query, $timestamp, $nonce, $bodySha256]);
$signature = hash_hmac('sha256', $canonical, $secret);
// header: "X-CBA-Signature: hmac-sha256={$signature}"

Okno replay i nonce

Znacznik czasu musi mieścić się w oknie 300 sekund względem czasu serwera — zadbaj o synchronizację zegara (NTP). Nonce musi być unikalny per klucz w tym oknie; powtórzony nonce zostaje odrzucony jako próba replay. Typowe odrzucenia opisuje sekcja Błędy (401 invalid_signature, expired_timestamp, replay_nonce).

Scopes

Uprawnienia działają w modelu deny-by-default — klucz może wyłącznie to, co jawnie nadałeś. Nadawaj najwęższy potrzebny zestaw.

Rotacja i reveal-once

Sekret jest pokazywany jednorazowo. Przy rotacji utwórz nowy klucz, wdróż go równolegle (okno nakładania pozwala starym i nowym kluczom działać jednocześnie), a po potwierdzeniu ruchu na nowym kluczu unieważnij stary. Dzięki temu wymiana klucza nie powoduje przerwy w integracji.

Dobre praktyki

• Trzymaj sekret wyłącznie po stronie serwera; nigdy w kliencie ani w URL.
• Podpisuj request tuż przed wysyłką, aby nie przekroczyć okna 300 s.
• Loguj correlation_id z odpowiedzi błędu, ale nigdy nie loguj sekretu.
• Więcej w sekcji Bezpieczeństwo i dane.