Authentication

API keys, both accepted headers, and the plan limits — straight from the code.

Every /v2/* request needs a credential. For developers that credential is an API key, created under Account → API.

Creating a key

  1. Sign in at cardog.app
  2. Go to Account → API
  3. Create a key and name it for its environment ("production", "ci", …)
  4. Copy it immediately — it is shown once and never again

Sending the key

Two headers are accepted; they are equivalent:

bash
# x-api-key header
curl "https://api.cardog.app/v2/vin/1HGCM82633A123456" \
  -H "x-api-key: $CARDOG_API_KEY"

# Authorization bearer
curl "https://api.cardog.app/v2/vin/1HGCM82633A123456" \
  -H "Authorization: Bearer $CARDOG_API_KEY"

Plans

Monthly request allowances per plan (rendered from the platform's own plan definitions — see /pricing for current prices):

PlanAPI requests / month
Free50
Starter1,000
Pro5,000
Business25,000
Enterprise100,000

Metered responses carry X-Credits-* headers, and GET /v2/pricing returns the machine-readable rate card without auth.

When auth fails

Failures use the standard error envelope:

  • 401 unauthorized — no valid key, session, or internal credential
  • 403 forbidden — the credential lacks the scope for this route group
  • 402 insufficient_credits — free-tier hard stop (paid tiers bill overage instead)
  • 429 rate_limited — per-minute rate limit exceeded

Key hygiene

  • Never commit keys to version control — use environment variables
  • Use separate keys for development and production
  • Rotate keys periodically; revoke unused keys in the dashboard
  • Monitor usage under Account → API