Docs · Authentication

Get started

Authentication

Every endpoint except /v1/status requires an API key, sent as a bearer token.

The header

Send your key in the Authorization header on every request:

curl 
$ curl https://api.carvector.io/v1/vehicles?make=Toyota&model=Tacoma \
  -H "Authorization: Bearer cv_your_key"

Getting a key

Create a key from your dashboard. Keys are prefixed with cv_ and shown in full only once, at creation — we store a hash, never the raw key. You can create multiple keys (e.g. one per environment) and give each a label.

Keep keys server-side

A CarVector key carries your plan's full access. Never embed it in client-side code, a mobile app, or a public repo. Call the API from your backend and proxy results to your front end. If a key leaks, revoke it from the dashboard — it's invalid immediately.

Revoking a key

Revoke any key from the dashboard. Revocation takes effect on the next request — a revoked key returns 401.

No key, or a bad key?

They are different. A bad key returns 401 — your integration is broken and you should fix it. No key returns 402 with payment terms, described below. See Errors & rate limits for the exact shapes.

Paying per call, without a key

An agent with no account can pay per request instead of signing up. Send no key and the API answers 402 with x402 terms; pay them and the same request returns data. Settlement is USDC on Base at $0.01 per call. No signup, no card, no credentials to store.

Any x402-capable client 
$ # x402-fetch, @x402/fetch, or any client that understands HTTP 402
curl https://api.carvector.io/v1/vehicles?make=BMW&limit=10
# → 402 Payment Required, with terms in the body

Per-call pricing is the expensive way to buy this data

At $0.01 a call, x402 costs roughly 2.5× the Developer plan's per-request rate and 40× Business. It exists for agents that cannot hold an account — not as a cheaper door. If you are making more than a few hundred calls a month, a plan is cheaper, and the free tier is 500 calls a month at no cost.

What a paid call returns

x402 requests are served at free-tier limits — up to 10 results per page on list endpoints, where a Business key gets 100. Endpoints that require a paid plan stay 401 and cannot be unlocked by paying per call. A repeated payment is honoured briefly so a dropped connection can retry without being charged twice; after that it needs a new payment.
← Quickstart API reference →