Permissions Reference

Permissions (scopes) control what data your app can access through the API. They are requested during app registration and granted when a merchant installs your app.

API Scopes

These scopes are used in the OAuth flow and when creating Custom Apps.

Data Access Scopes

Special Scopes

Scope Enforcement

Every API endpoint requires a specific scope. If your app doesn't have the required scope, the API returns:

{
  "message": "Insufficient scope. Required: read:orders",
  "code": "insufficient_scope",
  "required_scope": "read:orders",
  "status": 403
}

Scope-to-Endpoint Mapping

Orders

Products

Categories

Customers

Discounts

Inventory

Store

Billing

Webhooks

Webhook Event Topics by Scope

The event topics your app can subscribe to depend on the scopes your app has been granted. The platform does not enforce topic-to-scope restrictions at the subscription level, but the payload will be filtered based on your permissions (see Webhook Payload Filtering below).

Requesting Scopes

Platform Apps

Specify scopes in your app configuration's requested_scopes field. When a merchant installs your app, they see the requested scopes and choose to grant or deny them.

Only request scopes your app actually needs. Requesting unnecessary scopes reduces merchant trust and install rates.

Custom Apps

Select scopes during app creation in the dashboard wizard. You can update scopes later from Settings > Apps > Manage.

Webhook Payload Filtering

Merchant-created webhooks (from the dashboard Webhooks tab) support permission-based payload filtering. This controls which data fields are included in webhook payloads.

Webhook Permissions

When a merchant creates a webhook subscription from the dashboard, they can select these payload permissions:

Example

A webhook subscription with only read_orders permission receiving an order.status_changed event:

Full payload (app webhook):

{
  "data": {
    "order_id": 1045,
    "status": "confirmed",
    "total": 1460.00,
    "customer_name": "Rahim Ahmed",
    "customer_phone": "+8801712345678"
  }
}

Filtered payload (merchant webhook with only read_orders):

{
  "data": {
    "order_id": 1045,
    "status": "confirmed",
    "total": 1460.00
  }
}

Customer fields are removed because the read_customers permission was not granted.

Extension Scopes

Extensions inherit their parent app's OAuth scopes. When a sandbox extension calls selorax.api.get('/apps/v1/orders'), the API proxy checks that the app has read:orders. No additional scopes are needed specifically for extensions — the app's existing scopes apply.

Extension deployment and management use client credentials (X-Client-Id + X-Client-Secret) and do not require OAuth scopes. See Extensions for details.

Best Practices

• Least privilege — Request only the scopes your app needs. You can always add more scopes later (merchants will need to re-authorize).
• Check scopes at runtime — The token exchange response includes a scope field listing what was actually granted. Verify it contains what your app needs.
• Handle scope changes — If a merchant re-installs with different scopes, your stored scopes may be outdated. Always check the latest scope from the installation data.
• Document your scope usage — In your app's description, explain why each scope is needed. Merchants are more likely to install apps that justify their permissions.