Authentication

API keys, scopes, the device flow and where keys must never go.

Bearer keys

Every API request carries a key that starts with cimg_. Send it in the Authorization header. The x-api-key header is accepted for compatibility, but Authorization: Bearer is preferred.

bash

curl -H "Authorization: Bearer $CAR_IMAGE_API_KEY" \
  https://carimage.dev/api/v1/account

Query-string keys are rejected

URLs leak through history, logs, analytics and referrers, so a key in a URL never authenticates. For <img> tags and anything else a browser can see, mint signed URLs from your backend instead.

Keys are created in the dashboard or by the CLI. The plaintext is shown exactly once; the server stores only a SHA-256 hash plus a short prefix for display. You can hold up to 10 active keys per account — one per environment or agent is a good habit, because revocation is instant and per-key.

Dashboard keys get images:read and account:read.
CLI keys (approved in the browser at /activate) also get billing:write, so an agent can hand you a Stripe Checkout link when credits run low.

Scopes

API key scopes
Parameter	Type	Description
`images:read`	scope	Fetch images, create signed URLs, search and resolve vehicles, send feedback.
`account:read`	scope	Read the credit balance and pricing from GET /api/v1/account.
`billing:write`	scope	Create hosted Stripe Checkout and Billing Portal URLs. Never completes a charge — a human still pays in the browser. Granted only to keys created through the CLI device flow.

A request outside a key's scopes fails with 403; the response body names the scope that is missing.

Device flow (CLI and agents)

npx @meterapp/car-image login requests a device code, prints a short user code and opens https://carimage.dev/activate. You sign in and approve the code; the new key is delivered only to the waiting CLI, stored at ~/.config/car-image-api/config.json with mode 0600, and never shown in the browser.

POST/api/auth/device/code

nonefree

POST/api/auth/device/token

device codefree

Codes expire after ten minutes. Polling before approval returns authorization_pending; the key is returned exactly once, after which the code is consumed.

Checking your balance

GET/api/v1/account

account:readfree

200 OK

{
  "data": {
    "credits": 4871,
    "auto_reload": false,
    "has_payment_method": true,
    "pricing": {
      "credits_per_delivery": 1,
      "packs": [
        {
          "credits": 5000,
          "cents": 500
        },
        {
          "credits": 10000,
          "cents": 1000
        },
        {
          "credits": 25000,
          "cents": 2500
        },
        {
          "credits": 100000,
          "cents": 10000
        }
      ]
    }
  },
  "links": {
    "dashboard": "https://carimage.dev/dashboard",
    "pricing": "https://carimage.dev/pricing"
  },
  "request_id": "req_01j9x…"
}

Environment variables

The CLI, the SDK and the local MCP server all read the same two variables:

Parameter	Type	Description
`CAR_IMAGE_API_KEY`required	string	Your cimg_ key. Inject it as a secret in CI or an agent sandbox.
`CAR_IMAGE_API_URL`	url	Override the API origin (self-hosting, staging).Default: `https://carimage.dev`

Never commit a keyNever paste a key into a promptRotate by creating a new key, then revoking the old one

Bearer keys

Creating and revoking keys

Scopes

Device flow (CLI and agents)

Checking your balance

Environment variables