OAuth 2.0 — jako dostawca, z zakresami i PKCE

Który przepływ wybrać#

Nie obsługujemy przepływów implicit, password ani device_code. Punkt końcowy tokenów jest wspólny: POST https://api.premiumsupply.pl/oauth/token, ciało application/x-www-form-urlencoded (akceptujemy też JSON).

Identyfikatory i prefiksy#

Każdy sekret ma czytelny prefiks — po samej wartości widać w logach i skanerach wycieków, co to jest. Tokeny są nieprzezroczyste (32 losowe bajty, w bazie tylko SHA-256) — nie są JWT i nie da się z nich nic odczytać.

client_credentials — token na własne konto#

curl -s -X POST https://api.premiumsupply.pl/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "scope=offers:read offers:write"

{
  "access_token": "ps_at_Qm9ndXNfdG9rZW5fZG9rdW1lbnRhY2ppXzEyMzQ1Njc4OTA",
  "token_type": "Bearer",
  "expires_in": 43200,
  "scope": "offers:read offers:write"
}

• Basic auth: base64(client_id:client_secret). Alternatywnie client_id i client_secret jako pola formularza — ale nie w URL.
• scope jest opcjonalny; pominięty = wszystkie zakresy aplikacji. Zakres spoza aplikacji → 400 invalid_scope.
• Aplikacja o statusie suspended nie dostaje tokenów (401 invalid_client), a tokeny już wydane przestają działać.

authorization_code + PKCE — dostęp do kont innych sprzedawców#

Sprzedawca loguje się na premiumsupply.pl, widzi nazwę Twojej aplikacji, listę zakresów słowami (nie kodami) oraz host, na który wróci, i klika „Zezwól”. Wracasz z jednorazowym kodem, który wymieniasz na parę tokenów. PKCE (S256) jest obowiązkowe — także dla aplikacji serwerowych z sekretem.

Krok 1: PKCE i state#

import { createHash, randomBytes } from "node:crypto";

// code_verifier: 43–128 znaków z zestawu [A-Za-z0-9-._~]; 32 losowe bajty → 43 znaki base64url
const codeVerifier = randomBytes(32).toString("base64url");

// code_challenge = base64url(SHA-256(code_verifier)) — zawsze 43 znaki
const codeChallenge = createHash("sha256").update(codeVerifier).digest("base64url");

// state: min. 8 znaków, losowy, zapisany w sesji użytkownika do porównania po powrocie
const state = randomBytes(16).toString("base64url");

Krok 2: przekierowanie na /oauth/authorize#

GET https://api.premiumsupply.pl/oauth/authorize
    ?response_type=code
    &client_id=psa_3f9c1b2a4d5e6f708192a3b4
    &redirect_uri=https%3A%2F%2Fapp.example.com%2Foauth%2Fcallback
    &scope=offers%3Aread%20orders%3Aread%20shipments%3Awrite
    &state=k3Jm9pQ2vX8sLw4T
    &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
    &code_challenge_method=S256

Krok 3: powrót z kodem#

https://app.example.com/oauth/callback
    ?code=ps_ac_dGVzdG93eV9rb2RfYXV0b3J5emFjeWpueQ
    &state=k3Jm9pQ2vX8sLw4T

https://app.example.com/oauth/callback
    ?error=access_denied
    &state=k3Jm9pQ2vX8sLw4T

Krok 4: wymiana kodu na tokeny#

curl -s -X POST https://api.premiumsupply.pl/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=$CODE" \
  -d "redirect_uri=https://app.example.com/oauth/callback" \
  -d "code_verifier=$CODE_VERIFIER"

{
  "access_token": "ps_at_c2VsbGVyX3Rva2VuX2Rva3VtZW50YWNqYV8wOTg3NjU0MzIx",
  "token_type": "Bearer",
  "expires_in": 43200,
  "refresh_token": "ps_rt_cmVmcmVzaF90b2tlbl9kb2t1bWVudGFjamlfMTEyMjMzNDQ1NQ",
  "scope": "offers:read orders:read shipments:write"
}

• Kod jest jednorazowy i żyje 10 minut. Drugie użycie, inny redirect_uri albo zły code_verifier → 400 invalid_grant.
• Zakresy tokenu = zakresy, na które sprzedawca wyraził zgodę. Sprawdzisz je przez GET /v1/me.
• Jeden sprzedawca może wyrazić zgodę wielokrotnie — każda daje niezależną parę tokenów.

Odświeżanie i rotacja refresh tokenu#

curl -s -X POST https://api.premiumsupply.pl/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=$REFRESH_TOKEN"

{
  "access_token": "ps_at_bm93eV9hY2Nlc3NfdG9rZW5fcG9fcm90YWNqaV8wMDExMjIzMw",
  "token_type": "Bearer",
  "expires_in": 43200,
  "refresh_token": "ps_rt_bm93eV9yZWZyZXNoX3Rva2VuX3N0YXJ5X2p1el9uaWVfZHppYWxh",
  "scope": "offers:read orders:read shipments:write"
}

funkcja odśwież(sesja):
  zablokuj(sesja)                          # jedno odświeżenie naraz dla tej sesji
  odpowiedź = POST /oauth/token (grant_type=refresh_token, refresh_token=sesja.refresh)

  jeśli odpowiedź.status == 200:
    zapisz_atomowo(sesja, access = odpowiedź.access_token,
                          refresh = odpowiedź.refresh_token)   # NAJPIERW zapis, potem użycie
  w przeciwnym razie, gdy error == "invalid_grant":
    oznacz(sesja, "wymaga ponownej zgody")  # stary refresh już nie wróci
  odblokuj(sesja)

Access token wydany wcześniej pozostaje ważny do swojego wygaśnięcia — rotacja dotyczy tylko refresh tokenu. Zakresy nowej pary są identyczne z poprzednią; żeby dodać zakres, sprzedawca musi przejść zgodę ponownie.

Czasy życia#

Zakresy uprawnień#

Zakresy są krótkie i bez prefiksu. Aplikacja deklaruje je w panelu; token może mieć podzbiór. Sprzedawca na ekranie zgody widzi etykiety z kolumny „Co oznacza”. Kolumna „Zasoby w v1” pokazuje, co dziś wymaga danego zakresu — pozostałe zakresy są zarezerwowane dla zasobów zapowiedzianych w changelogu; proś o nie dopiero, gdy będą potrzebne.

GET /v1/me nie wymaga zakresu. Brak zakresu na zasobie → 403 insufficient_scope z nazwą brakującego zakresu w message.

Kiedy token traci ważność#

• Upływ czasu — 12 h (access), 90 dni (refresh), 10 min (kod).
• Użycie refresh tokenu — odwołuje ten konkretny refresh token (rotacja). Access tokeny wydane wcześniej działają do wygaśnięcia.
• Usunięcie aplikacji w panelu — natychmiast odwołuje wszystkie jej tokeny u wszystkich sprzedawców.
• Zawieszenie aplikacji (status suspended) — tokeny przestają być akceptowane, nowe nie są wydawane.
• Rotacja client_secret — nie odwołuje tokenów. To wymiana klucza, nie odcięcie integracji; na odcięcie jest usunięcie aplikacji.

Panel aplikacji (apps.developer.premiumsupply.pl ↗) pokazuje aktywne tokeny per rodzaj z ostatnim użyciem, adresem IP i User-Agentem — to widok „kto ma dostęp do mojego sklepu”. Ekran zgody dla sprzedawców znajduje się pod https://premiumsupply.pl/oauth/consent i jest wywoływany wyłącznie przez /oauth/authorize.

Błędy OAuth#

Punkty /oauth/* zwracają błędy w kształcie RFC 6749: { error, error_description, traceId }. Kody invalid_client, invalid_grant, invalid_scope, invalid_request, unsupported_grant_type, access_denied i unsupported_response_type są opisane w katalogu błędów. Pozostałe zasoby (/v1/*) używają wspólnego kształtu { traceId, errors[] }.