Authentication

Bazex uses OAuth 2.0 Authorization Code flow. Merchants approve your app, and you receive a scoped access token to call the API on their behalf.

OAuth 2.0 Flow

1. Your app redirects merchant → Bazex authorization page

2. Merchant reviews scopes and approves

3. Bazex redirects back to your app with ?code=...

4. Your server exchanges code → access token

5. Use token to call the App API

Step 1: Redirect to authorization

Redirect the merchant to the Bazex consent screen:

https://admin.bazex.co/apps/authorize?app_id=YOUR_CLIENT_ID&scopes=read_products,read_orders

Query Parameters

Name	Type	Required	Description
app_id	string	Yes	Your application's Client ID
scopes	string	No	Comma-separated list of requested scopes (defaults to app's registered scopes)
state	string	No	Opaque value for CSRF protection — returned unchanged in the callback
redirect_url	string	No	Must match one of your registered redirect URLs

The merchant sees your app name, description, and the permissions you're requesting. When they approve, Bazex redirects to your registered redirect URL.

Step 2: Receive the authorization code

After the merchant approves, they're redirected to your callback URL:

https://your-app.com/callback?code=a1b2c3d4e5f6...&state=your_state_value

⚠

Code expiration

Authorization codes expire after 5 minutes and can only be used once. Exchange the code immediately.

Step 3: Exchange code for access token

Make a server-side POST request to exchange the authorization code for an access token. Authenticate using HTTP Basic with your Client ID and Client Secret.

cURLbash

curl -X POST https://api.bazex.co/apps/oauth/token \
  -H "Authorization: Basic $(echo -n 'YOUR_CLIENT_ID:YOUR_CLIENT_SECRET' | base64)" \
  -H "Content-Type: application/json" \
  -d '{ "code": "a1b2c3d4e5f6..." }'

Responsejson

{
  "access_token": "fbat_9a8b7c6d5e4f3a2b1c0d...",
  "token_type": "Bearer",
  "scope": "read_products read_orders",
  "business_id": "clx1abc2def3ghi4jkl",
  "webhook_secret": "whsec_a1b2c3d4..."
}

⚠

Store securely

The access_token is shown only during this exchange — it cannot be retrieved later. Store it securely in your database. The token does not expire; it is revoked when the merchant uninstalls your app.

Using the access token

Include the token in the Authorization header for all API requests:

curl https://api.bazex.co/app-api/products \
  -H "Authorization: Bearer fbat_9a8b7c6d5e4f3a2b1c0d..."

The token is scoped to a specific merchant (business). All API responses are automatically filtered to that merchant's data. You cannot access other merchants' data with the same token.

Token formats

Token	Prefix	Purpose
Access Token	fbat_	API authentication — sent in Authorization header
Client Secret	fbcs_	OAuth token exchange — used in Basic auth
Webhook Secret	whsec_	Webhook signature verification

Scopes

Scopes control what data your app can access. Request only the scopes you need — merchants are more likely to approve apps that request minimal permissions.

Scope	Description
read_products	View the merchant's product catalog
write_products	Create, update, and delete products
read_orders	View orders and order history
write_orders	Create orders and update order status
read_analytics	View analytics dashboard data
read_business	View business information
read_reviews	View product and store reviews
read_pages	View site pages
write_pages	Create and edit site pages

Scope expansion & re-consent

If you add new scopes to your app after it's already installed, existing merchants need to re-approve. Bazex handles this automatically:

You add new scopes in the developer portal and submit for review
After approval, existing installations are flagged with needsReConsent
The merchant sees a prompt to approve the additional scopes
Until re-approved, the token only grants the original scopes