OAuth 2.0

Authorization Code Flow

Brutlers implementuje OAuth 2.0 Authorization Code Flow z PKCE (RFC 7636). Oto jak przebiega ten proces:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  Your App   │     │   Brutlers   │     │   Vendor    │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │
       │  1. Redirect      │                   │
       │──────────────────>│                   │
       │                   │  2. Login/Consent │
       │                   │<─────────────────>│
       │                   │                   │
       │  3. code + state  │  3. Allow         │
       │<──────────────────│<──────────────────│
       │                   │                   │
       │  4. Exchange code │                   │
       │──────────────────>│                   │
       │                   │                   │
       │  5. Tokens        │                   │
       │<──────────────────│                   │
       │                   │                   │
       │  6. API calls     │                   │
       │──────────────────>│                   │

1. Zarejestruj aplikację

Zarejestruj swoją aplikację w panelu usługodawcy w sekcji Integracje. Otrzymasz Client ID oraz Client Secret.

2. Żądanie autoryzacji

Przekieruj usługodawcę do naszego endpointu autoryzacji. Usługodawca loguje się i udziela uprawnień.

GET /api/oauth/authorize?
  response_type=code
  &client_id=brut_app_...
  &redirect_uri=https://app.example.com/callback
  &scope=orders:read orders:write
  &state=random_csrf_token
  &code_challenge=BASE64URL_SHA256_HASH
  &code_challenge_method=S256

3. Wymiana tokenu

Po autoryzacji otrzymasz kod autoryzacyjny. Wymień go na Access Token i Refresh Token.

curl -X POST https://brutlers.com/api/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=AUTH_CODE" \
  -d "client_id=brut_app_..." \
  -d "client_secret=brut_secret_..." \
  -d "redirect_uri=https://app.example.com/callback" \
  -d "code_verifier=ORIGINAL_RANDOM_STRING"

{
  "access_token": "brut_at_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "brut_rt_...",
  "scope": "orders:read orders:write"
}

4. Wywołania API

Użyj Access Token jako Bearer Token w nagłówku Authorization swoich wywołań API.

GET /api/vendor/orders HTTP/1.1
Host: brutlers.com
Authorization: Bearer brut_at_...

5. Odśwież token

Access Tokeny są ważne przez 1 godzinę. Użyj Refresh Token, aby uzyskać nowy Access Token. Refresh Tokeny są ważne przez 30 dni i są rotowane przy każdym użyciu.

curl -X POST https://brutlers.com/api/oauth/token \
  -d "grant_type=refresh_token" \
  -d "refresh_token=brut_rt_..." \
  -d "client_id=brut_app_..." \
  -d "client_secret=brut_secret_..."

Dostępne zakresy

Unieważnij token

Unieważnia Access Token lub Refresh Token. Endpoint zawsze zwraca HTTP 200 (RFC 7009).

curl -X POST https://brutlers.com/api/oauth/revoke \
  -d "token=brut_at_..." \
  -d "client_id=brut_app_..." \
  -d "client_secret=brut_secret_..."

Wskazówki dotyczące bezpieczeństwa

• • Przechowuj Client Secret w bezpiecznym miejscu — jest wyświetlany tylko raz.
• • Używaj PKCE (S256) dla klientów publicznych (np. aplikacji jednostronicowych).
• • Kody autoryzacyjne są ważne przez 10 minut i mogą być użyte tylko raz.
• • Redirect URI muszą dokładnie odpowiadać zarejestrowanemu URI.
• • Używaj parametru state do ochrony przed CSRF.