Scopes
Scopes are shop-granted permissions on the integration; the shop's normal access rules apply underneath.
A scope is a grant the shop makes to the integration. Write does not imply read. Any mutation that returns a complete resource requires both its write/action scope and its read scope. Required companion scopes are enforced when a grant is saved and on every request.
The human managing the integration must hold integrations.manage and every internal permission represented by every requested scope. Where a permission can be limited to selected records, the grantor must hold it shop-wide (ALL). This applies to all scopes, not only those labeled sensitive.
| Scope | Grants | Notes |
|---|---|---|
shop.read |
Shop profile, hours, capabilities | Start here |
customers.read |
Complete customer representation: identity, contact/address, consent, notes, tags | sensitive |
customers.write |
Create/update/archive customers | requires customers.read |
vehicles.read |
Read vehicles | |
vehicles.write |
Create/update vehicles | requires vehicles.read |
appointments.read |
Read appointments and availability | |
appointments.write |
Create, reschedule, cancel, check in | requires appointments.read |
repair_orders.read |
Read repair-order/job operational data; sale pricing is separately gated | |
repair_orders.write |
Create repair orders, add jobs | requires repair_orders.read |
jobs.actions |
Start / complete / flag job execution | sensitive; requires repair_orders.read; never authorization |
pricing.read |
Sale pricing on ROs, jobs, parts, labor, canned jobs | sensitive field capability |
inventory.read |
Read inventory items without costs | |
inventory.cost.read |
Read inventory/part acquisition costs | sensitive; requires inventory.read |
canned_jobs.read |
Read the canned-job catalog | |
technicians.read |
Technician assignment identities (name, role label) | no HR data |
invoices.read |
Posted invoices and credit notes | |
payments.read |
The payment ledger | sensitive |
tasks.read |
Read tasks | |
tasks.write |
Create, update, complete tasks | requires tasks.read |
webhooks.manage |
Manage webhook endpoint subscriptions | write |
external_refs.write |
Attach your own ids to records | also requires the target resource's read scope |
What is deliberately not exposed
- Estimate authorization — a customer's approval of work is never granted through the API. Integrations can read the authorization state and send customers to the shop's own estimate link.
- Customer messaging (SMS/email threads) — excluded pending a separate privacy design.
- Employee, payroll, and attendance data; platform administration.
- Financial writes (posting invoices, recording payments) — a later, separately-gated phase.
Webhooks follow scopes
An endpoint only receives events its integration could read: invoice.* needs invoices.read, customer.* needs customers.read, and so on. Adding a scope later starts delivering the matching events; removing it stops them.
Scopes can be changed by the shop at any time; the change applies on the integration's next request.