OAuth 2.0

Authorization Code Flow

Brutlers implementa l'OAuth 2.0 Authorization Code Flow con PKCE (RFC 7636). Ecco come funziona il processo:

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

1. Registra l'app

Registra la tua app nel Vendor Dashboard sotto Integrazioni. Riceverai una Client ID e un Client Secret.

2. Authorization Request

Reindirizza il vendor al nostro authorization endpoint. Il vendor accede e concede l'autorizzazione.

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

Dopo l'autorizzazione ricevi un Authorization Code. Scambialo per un Access Token e un 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. Chiamate API

Utilizza l'Access Token come Bearer Token nell'header Authorization delle tue chiamate API.

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

5. Rinnova il token

Gli Access Token sono validi per 1 ora. Utilizza il Refresh Token per ottenere un nuovo Access Token. I Refresh Token sono validi per 30 giorni e vengono ruotati a ogni utilizzo.

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

Scope disponibili

Revoca token

Invalida un Access Token o un Refresh Token. L'endpoint restituisce sempre 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_..."

Note di sicurezza

• • Conserva il Client Secret in modo sicuro — viene mostrato una sola volta.
• • Utilizza PKCE (S256) per i client pubblici (es. Single-Page App).
• • Gli Authorization Code sono validi per 10 minuti e possono essere utilizzati una sola volta.
• • I Redirect URI devono corrispondere esattamente all'URI registrato.
• • Utilizza il parametro state per la protezione CSRF.