OAuth 2.0

Authorization Code Flow

Brutlers implémente le flux OAuth 2.0 Authorization Code avec PKCE (RFC 7636). Voici comment fonctionne le processus :

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

1. Enregistrer l'application

Enregistrez votre application dans le tableau de bord prestataire sous Intégrations. Vous recevrez un Client ID et un Client Secret.

2. Authorization Request

Redirigez le prestataire vers notre endpoint d'autorisation. Le prestataire se connecte et accorde la permission.

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

Après l'autorisation, vous recevez un Authorization Code. Échangez-le contre un Access Token et 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. Appels API

Utilisez l'Access Token comme Bearer Token dans l'en-tête Authorization de vos appels API.

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

5. Renouveler le token

Les Access Tokens sont valides 1 heure. Utilisez le Refresh Token pour obtenir un nouvel Access Token. Les Refresh Tokens sont valides 30 jours et sont renouvelés à chaque utilisation.

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

Scopes disponibles

Révoquer un token

Invalide un Access Token ou un Refresh Token. L'endpoint retourne toujours 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_..."

Conseils de sécurité

• • Conservez le Client Secret en lieu sûr — il n'est affiché qu'une seule fois.
• • Utilisez PKCE (S256) pour les clients publics (ex. Single-Page-Apps).
• • Les Authorization Codes sont valides 10 minutes et ne peuvent être utilisés qu'une seule fois.
• • Les URIs de redirection doivent correspondre exactement à l'URI enregistrée.
• • Utilisez le paramètre state pour la protection CSRF.