OAuth 2.0

Authorization Code Flow

Brutlers implementiert den OAuth 2.0 Authorization Code Flow mit PKCE (RFC 7636). So funktioniert der Ablauf:

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

1. App registrieren

Registriere deine App im Vendor Dashboard unter Integrationen. Du erhältst eine Client ID und ein Client Secret.

2. Authorization Request

Leite den Vendor zu unserem Authorization-Endpoint weiter. Der Vendor loggt sich ein und erteilt die Berechtigung.

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. Token Exchange

Nach der Autorisierung erhältst du einen Authorization Code. Tausche ihn gegen ein Access Token und 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. API-Aufrufe

Verwende das Access Token als Bearer Token im Authorization-Header deiner API-Aufrufe.

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

5. Token erneuern

Access Tokens sind 1 Stunde gültig. Verwende das Refresh Token um ein neues Access Token zu erhalten. Refresh Tokens sind 30 Tage gültig und werden bei jeder Nutzung rotiert.

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_..."

Verfügbare Scopes

Token widerrufen

Invalidiere ein Access Token oder Refresh Token. Der Endpoint gibt immer HTTP 200 zurück (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_..."

Sicherheitshinweise

• • Speichere das Client Secret sicher — es wird nur einmal angezeigt.
• • Verwende PKCE (S256) für Public Clients (z.B. Single-Page-Apps).
• • Authorization Codes sind 10 Minuten gültig und können nur einmal verwendet werden.
• • Redirect URIs müssen exakt mit der registrierten URI übereinstimmen.
• • Verwende den state-Parameter zum CSRF-Schutz.