Public API v1

Goal

Call the read-only BlueMatrix Public API with a tenant-scoped Sanctum token.

Who it is for

Integrators and partners.

Preconditions

• Token abilities: tenant:{uuid} plus resource abilities (api:parties.read, api:items.read, api:inventory.read, api:sales.read, api:purchases.read, api:crm.read as needed).
• Base URL: {origin}/api/v1.
• CRM routes also need the crm module enabled.

Steps

1. Create a token (example in reference) with the required abilities.
2. Send Authorization: Bearer {token} on every request.
3. Probe GET /meta to confirm api_version and tenant_id.
4. Call read list/detail endpoints only — v1 has no write routes.
5. Respect pagination (per_page max 100) and rate limit 120 requests/minute (throttle:120,1).

Result

You can sync parties, items, availability, posted sales/purchase documents, and CRM reads without the staff UI.

Hard stops

Status	Meaning
403	Missing api:* ability (or auth failure)
404	Unknown or other-tenant UUID (RLS)
422	CRM module disabled (CRM routes)
429	Rate limit exceeded

Related

• OpenAPI specification
• Narrative reference
• Integrator hub