Scopes

A scope grants a key access to one area of the API. Give each key only the scopes it needs.

A scope only works while the key's owner holds the DMS permission behind it. When the DMS creates a key, you can only grant scopes that you hold yourself.

Scope	What it allows	Owner needs	Personal data
vehicles:read	Read vehicles and their images	stock.view	No
vehicles:write	Create, update, delete and change the status of vehicles; upload and order images; batch upload	stock.manage	No
branches:read	Read branches	Nothing	No
enquiries:read	Read enquiries	enquiries.view	Yes
enquiries:write	Create and update enquiries, add notes	enquiries.manage	Yes
enquiries:delete	Delete enquiries	enquiries.delete	Yes
customers:read	Read customers	customers.view	Yes
customers:write	Create and update customers	customers.manage	Yes
customers:delete	Delete customers (soft delete)	customers.delete	Yes
sales:read	Read deals, invoices and payments	enquiries.view	Yes
sales:write	Change a deal's status	enquiries.manage	Yes
appointments:read	Read appointments	calendar.view	Yes
appointments:write	Create, update and cancel appointments	calendar.view and enquiries.manage	Yes
workshop:read	Read workshop job cards	workshop.view	Yes
workshop:write	Create and update job cards	workshop.manage	Yes
part_exchanges:read	Read part exchanges	part_exchanges.manage	No
part_exchanges:write	Create part exchanges	part_exchanges.manage	No
users:read	Read staff users	Nothing	No (staff names and emails)
webhooks:manage	Create and manage webhook endpoints	integrations.manage	No
website_themes:read	Read website theme builds and versions	website.theme	No
website_themes:write	Request website theme builds and publish theme versions	website.theme	No
events:read	Read the event log	Nothing, but events are filtered by the key's other scopes	Follows the event

GET /v1/me and GET /v1/reference/{list} work with any key and any scope. The MCP server needs no scope of its own, but each of its tools is offered only to a key that has that tool's scope.

Personal data

Scopes marked as reaching personal data return information about the dealer's customers. If your integration handles them, you are processing that data on the dealer's behalf: store only what you need and keep it secure.

Publishable keys

Publishable keys have a fixed set that cannot be changed:

Scope	Allows
vehicles:read	Public vehicle fields, website-visible stock only
branches:read	Branches
public:enquiries	POST /v1/public/enquiries
public:valuation_requests	POST /v1/public/valuation-requests

Events and scopes

events:read returns only events the key could otherwise see, and a branch-restricted key sees only events about its branches or about no branch. Each event family needs a matching scope:

Event types	Scope needed
vehicle.*	vehicles:read
vehicle_batch.*	vehicles:write
enquiry.*	enquiries:read
customer.*	customers:read
deal.*	sales:read
appointment.*	appointments:read
job_card.*	workshop:read
theme_generation.*	website_themes:read

Errors

A request to an endpoint whose scope the key lacks is refused with 403 insufficient_scope. A key that has the scope but whose owner lost the permission gets 403 scope_not_permitted_for_owner.