Authentication
The Developer API uses API keys for authentication. Each key is scoped to a single store and has granular permissions that control which endpoints it can access.
Creating an API Key
- Log in to the Admin Panel.
- Click Developer API in the navigation menu.
- Click Create API Key.
- Fill in the form:
| Field | Description |
|---|---|
| Name | A descriptive label (e.g., "Website Sync", "BI Dashboard") |
| Scopes | Select which permissions the key should have (see below) |
| Rate Limit | Requests per minute (default: 60, max: 1,000) |
| Expires At | Optional expiration date |
| Test Mode | If enabled, the key can only read data — all write operations are blocked |
- Click Create API Key.
- Copy the key immediately. It is displayed only once and cannot be retrieved later.
The full API key is shown only once when you create it. If you lose it, you must revoke the key and create a new one. Store it securely — treat it like a password.
Using Your API Key
Include the key in the X-API-Key header on every request:
curl -H "X-API-Key: bpos_abc123..." \
https://yourstore.brotherpos.ca/api/v1/products
Never pass your API key as a query parameter. Always use the X-API-Key header to prevent the key from being logged in server access logs or browser history.
Scopes
Scopes control what your API key can access. Select only the scopes you need — this follows the principle of least privilege.
Read Scopes
| Scope | Grants Access To |
|---|---|
products:read | Products, categories, brands, store settings |
customers:read | Customer profiles, loyalty info |
sales:read | Sales history, receipts, line items |
inventory:read | Stock levels, inventory adjustments |
loyalty:read | Loyalty tiers, rewards, transactions |
gift_cards:read | Gift card balances |
store_credits:read | Store credit balances |
Write Scopes
| Scope | Grants Access To |
|---|---|
products:write | Bulk-update product prices and stock |
customers:write | Create and update customer records |
inventory:write | Create stock adjustments |
webhooks:manage | Create, update, and delete webhook subscriptions |
A key with customers:write can also read customers. You don't need to add both scopes.
Revoking a Key
If a key is compromised or no longer needed:
- Go to Developer API > API Keys.
- Click on the key name.
- Click Revoke Key.
Revocation is immediate. All requests using that key will receive a 401 Unauthorized response.
Error Responses
| Status | Meaning |
|---|---|
401 Unauthorized | Missing, invalid, or revoked API key |
403 Forbidden | Valid key but insufficient scope for this endpoint |
429 Too Many Requests | Rate limit exceeded — check Retry-After header |
What's Next?
- Pagination & Filtering — Control result sets
- Webhooks — Subscribe to real-time events
- Endpoints — Full endpoint reference