REST API

The buyer integration API is /api/v1 with a Sanctum personal access token bound to one workspace. It is not a CMS browser session, not a Portal magic link, and not the Field/mobile sync API.

Path: Profile menu → API tokens (/app/profile/tokens). Plan feature api_access.

Base URL (substitute your installed host — never a licensing domain):

https://your-veldriq-domain.example/api/v1

Point the API at your Veldriq origin — the same host you use in the browser. Installed-product Scramble /docs/api is authenticated on the app — not this public documentation site.

Not this API

Surface	Use
/api/v1/mobile/*	Veldriq Field native login/session (not this PAT)
/api/v1/field/sync/*	Veldriq Field outbox/sync (not this PAT)
CMS /app/w/{slug}/…	Inertia pages, cookie session
Portal / /book	Magic link / public booking, not PAT

A Field-mobile token (field-mobile / mobile-select) is rejected on the workspace API (403). Integration tokens use ability API integration.

Create a token

1. Plan feature api_access must be on. Without it the lock copy is API tokens and webhooks require a plan that includes API access.
2. Signed-in staff: avatar menu → API tokens. Password confirm on create/revoke.
3. Create token → Token name → create.
4. Copy your new token now / You will not be able to see it again. Then Revoke unused tokens.

Tokens do not expire by default. Revoke takes effect immediately. Do not put tokens in git or in this documentation.

Authenticate a request

curl -sS \
  -H "Authorization: Bearer vel_pat_example_not_a_real_token" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  https://your-veldriq-domain.example/api/v1/customers

The token already binds a workspace. Optional header X-Tenant-Id must match that workspace or the API returns 403. Do not send an arbitrary tenant UUID to “switch” workspace.

Authorization stack

1. Marketplace license veldriq.
2. Valid active-account Sanctum token.
3. Workspace from the token + plan feature api_access (and monthly api_calls quota when the plan sets one).
4. Module capability when the route has capability:….
5. Role permission (e.g. customers.view). Missing permission → 403, not an empty list.

A user with invoices.view still cannot open invoicing if the invoicing capability is off.

Money in responses: integer minor units (*_cents). Do not treat them as major-unit decimals.

Related: Webhooks · Plans.