Authentication and API keys
Every request is authenticated with a bearer token in the Authorization header:
GET /v1/me HTTP/1.1
Host: api.vehiso.com
Authorization: Bearer vh_live_sk_...
There are no sessions, cookies or CSRF tokens. The key identifies the dealer, so every dealer uses the same host, api.vehiso.com.
Key types
| Prefix | Type | Use it for | Data it reaches |
|---|---|---|---|
vh_live_sk_ | Secret | Servers, scripts, ETL jobs | The dealer's own data |
vh_live_pk_ | Publishable | Browser code on a bespoke website | The dealer's public data |
vh_test_sk_ | Secret (test) | Building and testing | Your dealership's sandbox |
vh_test_pk_ | Publishable (test) | Building and testing | Your dealership's sandbox |
vh_oat_ | OAuth access token | Partner apps | The dealer that authorised the app |
vh_live_ak_ | Agency key | Agencies that manage several dealerships | Every dealership the agency manages, one per request |
vh_test_ak_ | Agency key (test) | Building and testing as an agency | Each dealership's sandbox |
Agency keys are created in the agency portal rather than the DMS, and name the dealership they act for in a Vehiso-Dealer header. See Agencies.
A key has the form vh_<environment>_<type>_<lookup>_<secret>. The fixed vh_ prefix lets secret scanners such as GitHub secret scanning recognise a leaked key.
A key is shown once, when it is created or rolled. Vehiso stores only a SHA-256 hash of its secret part, so a lost key cannot be recovered, only replaced.
Secret keys
Secret keys can be given any scope the key owner is allowed. Treat them like a password: keep them in a secrets manager or environment variable on a server.
A secret key must never be used from a browser. If a request made with a secret key carries an Origin header, the API refuses it with 403 secret_key_in_browser. A key that has been in browser code has been exposed to everyone who opened developer tools, so roll it and use a publishable key instead.
Secret keys need a paid Vehiso plan. On the Free plan, requests with a secret key are refused with 403 plan_not_entitled.
Publishable keys
Publishable keys are made to be embedded in a website's front-end code. They are fixed to a public subset of the API and cannot be given more:
vehicles:read, limited to public fields and stock that is visible on the websitebranches:readPOST /v1/public/enquiriesPOST /v1/public/valuation-requests
A publishable key must have an origin allowlist of at least one https://host[:port] entry. A browser request from an origin that is not on the list is refused with 403 origin_not_allowed. Publishable keys work on every plan, including Free.
See Building a website with a publishable key.
Test keys and the sandbox
Test keys (vh_test_sk_..., vh_test_pk_...) work against your dealership's own sandbox: a separate dealership that holds demo stock, enquiries, customers, appointments, a deal and a workshop job, and none of your real data. Use it while you build: you can create, change and delete records freely without affecting real stock or real customers.
- It is set up on first use. The first request with a test key starts it, and requests get
503 sandbox_not_readywith aRetry-Afterheader until it is ready, usually within a couple of minutes. - Test keys need a paid plan, publishable ones included. On the Free plan they are refused with
403 plan_not_entitled. - It follows your plan, with a few differences. It sends no email or text messages and takes no payments. Registration lookups and valuations never call a data provider: a part exchange is filled in with made-up vehicle details, and a valuation request always quotes an instant, made-up figure. The same registration and mileage always give the same answer, so your tests can assert on them, but they are not market values. AI theme generation is refused with
403 not_available_in_sandbox. It holds at most 50 vehicles in stock; beyond that, adding stock is refused with403 sandbox_stock_cap_reached. - A test key acts as the sandbox's own user, not as one of your staff.
- Records you create are deleted after 30 days. The demo data stays, so the sandbox never empties.
- An unused sandbox is deleted. If no test key uses it for 30 days it is removed, and a fresh one is set up the next time a test key is used.
- You can reset it from Administration > Developers in the DMS. That sets up a fresh sandbox with new demo data and keeps your webhook endpoints. Your test keys keep working against the old one until the new one is ready.
Do not put real personal data in the sandbox.
Switching to production is a matter of swapping the test key for a live one. Nothing else about the request changes.
Who a key acts as
A key belongs to the dealership, but it acts as a person: its owner, by default the staff member who created it. Every request runs as that user, so branch restrictions, activity logs and business rules behave exactly as they would for that person in the DMS.
A key's effective permissions are its scopes and its owner's current permissions in the DMS:
- If the owner loses the DMS permission a scope needs, that scope stops working and the API answers
403 scope_not_permitted_for_owner. The rest of the key keeps working. - If the owner is deleted or banned, the whole key stops working with
401 key_owner_inactive.
The DMS shows these problems next to the key, and an administrator can move the key to another owner without changing the key itself. The permission each scope needs is listed on the Scopes page.
Optional restrictions
Each key can be narrowed further in the DMS:
| Restriction | Applies to | Effect |
|---|---|---|
| Branches | All keys | The key sees and writes only data for the chosen branches. Empty means all branches. |
| IP allowlist | Secret keys | Requests from any other IP address are refused with 403 ip_not_allowed. |
| Origin allowlist | Publishable keys (required) | Browser requests from any other origin are refused with 403 origin_not_allowed. |
| Expiry | All keys | After the expiry date the key is refused with 401 api_key_expired. |
An IP allowlist is a good idea for any secret key used from servers with fixed addresses.
Rolling and revoking keys
In Administration > Developers:
- Roll replaces a key's secret. The old key is revoked immediately and a copy with a new secret is shown once. Update wherever the key is stored straight away; requests with the old key are refused with
401 api_key_revoked. - Revoke disables a key permanently.
Roll a key whenever it may have been exposed: committed to a repository, pasted into a ticket, used in a browser, or held by someone who has left.
Authentication errors
| Status | code | Meaning |
|---|---|---|
| 401 | missing_api_key | No Authorization: Bearer header. |
| 401 | invalid_api_key | The key is malformed or unknown. |
| 401 | api_key_revoked | The key was revoked or rolled, or the OAuth grant was revoked. |
| 401 | api_key_expired | The key is past its expiry date. |
| 401 | key_owner_inactive | The key's owner was deleted or banned. |
| 403 | insufficient_scope | The key does not have the scope this endpoint needs. |
| 403 | scope_not_permitted_for_owner | The key has the scope, but its owner no longer has the permission behind it. |
| 403 | plan_not_entitled | Secret keys, webhooks and OAuth need a paid plan. |
| 403 | ip_not_allowed | The request came from an IP address outside the key's allowlist. |
| 403 | origin_not_allowed | The browser origin is not on the publishable key's allowlist. |
| 403 | secret_key_in_browser | A secret key was used from a browser. Roll it. |
The response body format is described in Requests and responses.