Platform API

The Platform API is the foundation layer shared by every BayWise product. It answers the cross-cutting questions you need to wire up once before calling the Scheduler or Payments APIs: who am I, what can I see, what have I connected, and how do I get notified?

The full endpoint reference with schemas and a “try it” console is at Platform API reference → .

What’s in it

Endpoint group	What it does
Identity (`/me`)	Confirm a key works; see its org, location scope, plan tier, and granted permissions.
Locations	List the workshop sites visible to the key — use this to resolve the `locationId` you send to product endpoints.
Integrations	Register external systems (DMS, ERP, POS) so synced records can be attributed to their source.
Webhooks	Subscribe a URL to real-time job and step events instead of polling.

Typical setup flow

When building an integration, wire the Platform layer up front — before any Scheduler or Payments calls.

1. Confirm your key and discover scope:


GET /v1/platform/me
Authorization: Bearer bw_live_…


{
  "keyId": "key-uuid",
  "orgId": "org-uuid",
  "locationId": null,
  "planTier": "pro",
  "scopes": ["…list of granted permissions…"]
}

locationId: null means this is an org-scoped key (covers all locations). A location-scoped key has a non-null locationId and pins all operations to that site.

2. Resolve your location IDs:


GET /v1/platform/locations
Authorization: Bearer bw_live_…


{
  "data": [
    { "id": "loc-uuid-1", "name": "Downtown Workshop", "timezone": "Asia/Dubai", "currencyCode": "AED" },
    { "id": "loc-uuid-2", "name": "Marina Branch",     "timezone": "Asia/Dubai", "currencyCode": "AED" }
  ]
}

Use id as locationId when creating jobs, transactions, or any location-scoped resource. Note the timezone — all workshop-local times (attendance, day-close, promise times) use this zone.

3. Register your integration (optional but recommended):


POST /v1/platform/integrations
Content-Type: application/json

{ "name": "Autorox DMS", "systemType": "dms" }

Returns an Integration with an id. You don’t need to link it to your API key — registering it lets synced records (technicians, bays, jobs) be attributed to their source in audit trails and reconciliation reports.

4. Register a webhook (optional):


POST /v1/platform/webhooks
Content-Type: application/json

{
  "url": "https://yourapp.example.com/hooks/baywise",
  "events": ["job.created", "job.delivered", "step.completed"]
}

Store the signingSecret from the response — BayWise signs every delivery with it. See Webhooks for verification steps and retry behaviour.

Key scoping: location vs org

	Location-scoped key	Org-scoped key
`locationId` in response	Set (pinned to one site)	`null`
Product create/write calls	No `locationId` needed — it’s implied	Must include `locationId` in every create/write body
List calls	Returns data for that location only	Returns data across all locations
Best for	A single-site DMS connector, a till integration	A group dashboard, a head-office DMS that drives multiple branches

Rotating a webhook secret

Send a patch with rotateSecret: true — the response carries the new signingSecret. Update your verification code before rotating in production.


PATCH /v1/platform/webhooks/{id}
Content-Type: application/json

{ "rotateSecret": true }

Need help?

Quote the request id from any response when contacting support. Keys can be revoked any time from Settings → Developer — a revoked key stops working immediately.