OAuth 2.0

Met OAuth 2.0 kan uw software namens een leverancier toegang krijgen tot de Brutlers API. De leverancier autoriseert de toegang eenmalig — daarna synchroniseert uw software automatisch.

Authorization Code Flow

Brutlers implementeert de OAuth 2.0 Authorization Code Flow met PKCE (RFC 7636). Zo werkt het proces:


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

1. App registreren

Registreer uw app in het leveranciersdashboard onder Integraties. U ontvangt een Client ID en een Client Secret.

Naar het leveranciersdashboard

2. Authorization Request

Leid de leverancier door naar ons authorization-endpoint. De leverancier logt in en verleent toestemming.

http

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

Parameter	Required	Description
response_type	Yes	Moet "code" zijn
client_id	Yes	Uw Client ID
redirect_uri	Yes	Moet exact overeenkomen met een geregistreerde URI
scope	Yes	Door spaties gescheiden lijst van scopes
state	Aanbevolen	Willekeurige tekenreeks voor CSRF-bescherming
code_challenge	Aanbevolen	Base64url-gecodeerde SHA-256 hash van de Code Verifier
code_challenge_method	Aanbevolen	Moet "S256" zijn

3. Token Exchange

Na autorisatie ontvangt u een Authorization Code. Wissel deze in voor een Access Token en Refresh Token.

bash

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"

Antwoord

json

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

4. API-aanroepen

Gebruik het Access Token als Bearer Token in de Authorization-header van uw API-aanroepen.

http

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

5. Token vernieuwen

Access Tokens zijn 1 uur geldig. Gebruik het Refresh Token om een nieuw Access Token te verkrijgen. Refresh Tokens zijn 30 dagen geldig en worden bij elk gebruik geroteerd.

bash

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

Beschikbare scopes

Scope	Description
orders:read	Opdrachten lezen
orders:write	Opdrachten aanmaken en status wijzigen
customers:read	Klantgegevens lezen
profile:read	Leveranciersprofiel lezen

Token intrekken

Ongeldig maken van een Access Token of Refresh Token. Het endpoint geeft altijd HTTP 200 terug (RFC 7009).

bash

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

Beveiligingsaanbevelingen

• Bewaar het Client Secret veilig — het wordt slechts één keer weergegeven.
• Gebruik PKCE (S256) voor publieke clients (bijv. single-page-apps).
• Authorization Codes zijn 10 minuten geldig en kunnen slechts eenmaal worden gebruikt.
• Redirect URI's moeten exact overeenkomen met de geregistreerde URI.
• Gebruik de state-parameter voor CSRF-bescherming.