Authentication

Authentication

TCG API uses API keys for authentication. Some endpoints (like listing games) are public, but most require a valid API key.

API Key Format

API keys use the prefix tcg_live_ followed by a random string:

tcg_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Sending Your Key

Include your API key in the X-API-Key header:

curl "https://api.tcgapi.dev/v1/search?q=charizard" \
  -H "X-API-Key: tcg_live_a1b2c3d4..."

Public vs Authenticated Endpoints

Public (no key required)

• GET /v1/games — List all games
• GET /v1/games/:slug — Game details
• GET /v1/games/:slug/sets — Sets for a game

Free tier (100 req/day)

• GET /v1/sets, /v1/sets/:id, /v1/sets/:id/cards
• GET /v1/cards/:id, /v1/cards/:id/prices
• GET /v1/cards/tcgplayer/:id — Lookup by TCGPlayer product ID
• GET /v1/search — Full-text card search
• GET /v1/prices/top-movers — Daily price movers

Pro tier ($9.99/mo, 10K req/day)

• Everything in Free, plus:
• GET /v1/cards/:id/history — Price history
• GET /v1/bulk/prices, /v1/bulk/cards — Bulk lookups
• GET /v1/sets/:id/prices — Full set price data

Business tier ($99/mo, 100K req/day)

• Everything in Pro, plus:
• GET /v1/cards/:id/history/detailed — Detailed history
• GET /v1/bulk/history — Bulk history
• GET /v1/export/set/:id — Set data export (CSV/JSON)
• Commercial use license included

Managing API Keys

Create a key

curl -X POST "https://api.tcgapi.dev/v1/keys" \
  -H "Content-Type: application/json" \
  -H "Cookie: session=YOUR_SESSION_TOKEN" \
  -d '{"name": "my-app"}'

List your keys

curl "https://api.tcgapi.dev/v1/keys" \
  -H "Cookie: session=YOUR_SESSION_TOKEN"

Delete a key

curl -X DELETE "https://api.tcgapi.dev/v1/keys/KEY_ID" \
  -H "Cookie: session=YOUR_SESSION_TOKEN"

Security Best Practices

• Never expose your API key in client-side code. Use a backend proxy.
• Use separate keys for different applications so you can revoke independently.
• Monitor your usage via GET /v1/usage to detect unauthorized use.
• Keys are hashed with SHA-256 before storage — we never store your raw key.

Error Responses

Missing API key

// 401
{
  "error": {
    "message": "API key required. Get one free at https://tcgapi.dev",
    "code": "API_KEY_REQUIRED"
  }
}

Invalid API key

// 401
{
  "error": {
    "message": "Invalid or deactivated API key",
    "code": "INVALID_API_KEY"
  }
}

Tier restriction

// 403
{
  "error": {
    "message": "This endpoint requires a Pro subscription",
    "code": "TIER_REQUIRED"
  }
}