Skip to main content
Documentation
Service VIN developer & AI platformGetting startedAuthenticationPaginationIdempotencyRate limitsErrorsWebhooks & signature verificationConnecting ClaudeRecipesMCP servers & the Claude connectorREST resource referenceCapability indexCustomers capabilitiesVehicles capabilitiesLeads capabilitiesWarranties capabilitiesQuotes capabilitiesInvoices capabilitiesPayments capabilitiesServices capabilitiesJobs capabilitiesCalendar capabilitiesScheduling capabilitiesStaff capabilitiesInventory capabilitiesComms capabilitiesTasks capabilitiesShop capabilitiesDocuments capabilitiesKnowledge capabilitiesReports capabilitiesBooking capabilitiesForms capabilitiesMarketing capabilitiesReviews capabilitiesAutomations capabilitiesIntegrations capabilitiesChangelogSearch

Guide

Authentication

API keys for code you control, and the OAuth connector for a shop owner who clicks Connect. Which to pick, and what each one can reach.

Two credentials reach the same capabilities through the same gates. They differ in who holds them and what revoking one does.

API keys

Every endpoint except the OpenAPI document takes a shop API key as a bearer token. Keys start with svk_live_.

Header
Authorization: Bearer svk_live_…

A key is minted with one of two scopes and neither can be changed afterwards. A read-only key is refused, with 403 insufficient_scope, by every capability that declares writes — which is the scope gate, and it is the LAST of the four gates a call passes. A full-access key does everything documented here, for the one shop it belongs to.

Keys are passwords. Mint one per tool, name it after that tool, and revoke that one key if it leaks — revocation takes effect immediately. A key may also carry an expiry date, after which it stops working on its own.

A missing, unknown or revoked key all return the same 401 with one message — deliberately, so a probe cannot tell a revoked key from a fictional one. An expired key gets its own message, since only its holder can ever see it.

The Claude connector

The connector is OAuth 2.1 with dynamic client registration and PKCE. A shop owner clicks Connect in Claude, sees a consent screen naming what the connection may do — reads, writes, and in plain language whether it may message their customers — and approves it. No key is ever pasted.

Every token is bound to the granting USER, not to the shop. That is the property worth understanding: the person's own permissions are the ceiling on what the connection can do, and revoking their login revokes the machine with it. A receptionist who connects Claude gets a Claude that can do exactly what a receptionist can do.

What both are narrowed by

Four gates, always in this order, and the order is not arbitrary:

  1. 1Ring — does this feature exist for this account at all? A miss answers 404 not_found, the same answer an unknown id gets, because an upgrade wall in front of something nobody can buy is a fake door.
  2. 2Plan — has this shop bought it? 402 plan_required, which names the plan.
  3. 3Permission — may this person do it? 403 forbidden. A read-only dashboard login is refused here, before scope is even considered.
  4. 4Scope — may this credential do it? 403 insufficient_scope.

A machine acting for a user gets exactly what that user gets

The permission gate asks the same question the dashboard asks — the ACT question, which admits a <section>.access grant and refuses a .view one. A capability can narrow what a login may do. Nothing here can widen it.