OAuth 2.0

With OAuth 2.0, your software can access the Brutlers API on behalf of a vendor. The vendor authorizes access once — then your software syncs automatically.

Authorization Code Flow

Brutlers implements the OAuth 2.0 Authorization Code Flow with PKCE (RFC 7636). Here is how it works:


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

1. Register Your App

Go to Vendor Dashboard

2. Authorization Request

Redirect the vendor to our authorization endpoint. The vendor logs in and grants permission.

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	Must be "code"
client_id	Yes	Your Client ID
redirect_uri	Yes	Must match a registered URI exactly
scope	Yes	Space-separated list of scopes
state	Recommended	Random string for CSRF protection
code_challenge	Recommended	Base64url-encoded SHA-256 hash of the code verifier
code_challenge_method	Recommended	Must be "S256"

3. Token Exchange

After authorization, you receive an authorization code. Exchange it for an access token and 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"

Response

json

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

4. API Calls

Use the access token as a Bearer token in the Authorization header of your API calls.

http

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

5. Refresh Tokens

Access tokens are valid for 1 hour. Use the refresh token to obtain a new access token. Refresh tokens are valid for 30 days and are rotated on each use.

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

Available Scopes

Scope	Description
orders:read	Read orders
orders:write	Create orders and update status
customers:read	Read customer data
profile:read	Read vendor profile

Revoke Tokens

Invalidate an access token or refresh token. The endpoint always returns HTTP 200 (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_..."

Security Notes

• Store the Client Secret securely — it is only shown once.
• Use PKCE (S256) for public clients (e.g., single-page apps).
• Authorization codes are valid for 10 minutes and can only be used once.
• Redirect URIs must match the registered URI exactly.
• Use the state parameter for CSRF protection.