Integrator hub

Goal

Connect external systems to BlueMatrix using Public API v1 (read-only) and the OpenAPI contract.

Who it is for

Partners and internal integrators. Staff Integrations UI (integration.view, module integration_api) manages webhooks/connections — it is not the Public API token mint screen. Tokens are Sanctum personal access tokens with tenant:{uuid} plus api:* abilities.

Preconditions

• A staff user (or service account user) that can create tokens in your environment.
• Know which abilities you need (api:parties.read, api:items.read, …).
• For CRM reads: tenant has crm module enabled.

Start here

1. Public API v1 — auth, rate limits, read-only scope
2. OpenAPI specification — download YAML
3. Narrative API reference — endpoints and samples
4. Custom and headless storefronts — Commerce public kit for agencies

Steps

1. Create a token including tenant:{uuid} and the api:* abilities you need.
2. Call GET {origin}/api/v1/meta with Authorization: Bearer … to verify tenant scope.
3. Read list/detail endpoints; respect page / per_page (max 100) and 120 req/min throttle.
4. Treat cross-tenant UUIDs as 404; missing ability as 403; disabled CRM module as 422.

Result

Downstream systems sync read models without using the staff UI.

Hard stops

v1 has no write routes; POS/portal/staff APIs are out of scope for AD-003 public integration.

Related

• Develop index
• Permissions model