API Authentication

Product API requests (VIN decode and related vehicle endpoints) use an API key issued per organization. Dashboard login uses a browser JWT session and is separate from machine keys. This guide covers how to create a key, send it on every request, and verify your first successful call.

API keys (machine-to-machine)

After you create an account, buy a prepaid token pack, and finish organization setup, create keys in Dashboard → API Keys. Keys use the format sk_carsage_…. The full secret is shown once at creation — store it in your secrets manager. Rotate keys if they leak; revoke unused keys from the same dashboard page.

Send the key on every product request using either header:

Authorization: Bearer YOUR_API_KEY
# or
X-API-Key: YOUR_API_KEY

Base URL

All versioned product routes live under /v1/ on the API host:

https://api.carsage.dev/

Example path: /v1/vin/decode/WP0AF2A99KS165242

Example VIN decode request

Lite decode costs 1 prepaid token on success; Full costs 5. Invalid VINs are not charged. Prefer the VIN decode API quickstart for a full walkthrough.

curl -X GET "https://api.carsage.dev/v1/vin/decode/WP0AF2A99KS165242" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Common auth errors

401 — missing or invalid key. Confirm the header name and that you copied the full secret.
402 — insufficient tokens. Buy another pack on Billing, then retry.
429 — rate limit. Back off using Retry-After when present.

Full table: Errors & rate limits.

Need interactive schemas? Open the carsage OpenAPI Swagger documentation on the API host, or return to the docs overview.