Authentication

Sending the key

Send the key in the Authorization header as a bearer token. This is the way to do it from a server.

curl "https://api.tcggraph.com/v1/games" \
  -H "Authorization: Bearer $TCGGRAPH_API_KEY"

Where a client cannot set headers, the key is also accepted as the api_key query parameter. Query strings end up in server logs, proxies and browser history, so prefer the header whenever you can. When a request carries both, the header is used.

curl "https://api.tcggraph.com/v1/games?api_key=$TCGGRAPH_API_KEY"

The GraphQL endpoint takes the key the same way. The scan socket, which cannot carry headers, takes a short-lived ticket instead; see Card recognition.

Keys

Keys look like tcg_live_ followed by 32 characters. Create as many as you need in the dashboard, one per app or environment, so each can be revoked on its own. The full key is shown once, when it is created; we store only a hash of it. Every key on an account has the same access and draws on the same credits: there are no scopes and no read-only or publishable keys. Some older keys start tcg_test_; they work, and are metered, exactly like live keys.

Using a key in a browser

The API sends CORS headers for every origin, so it can be called from a web page. A key in a page can be read by anyone who opens it, so give such a key an allowed-origins list when you create it: a request whose Origin header is not on the list is refused with a 403. Origins are compared exactly after normalizing to scheme, host and port (https://app.example.com); there are no wildcards, so list each subdomain.

The list only binds browsers. A request with no Origin header, which is any request not made by a browser, is allowed, so a key copied out of a page can still be used from a script. For anything beyond a demo, call the API from your own server and keep the key there.

Rotation and revocation

Create the new key, deploy it, then revoke the old one in the dashboard. Both work during the overlap. Revocation is immediate: the key is checked against the database on every request, so the next request with a revoked key is a 401.

Authentication errors

No key, from the live API:

{
  "error": {
    "code": "unauthenticated",
    "message": "Missing API key. Send `Authorization: Bearer <key>`.",
    "details": {
      "docs": "https://tcggraph.com/docs/authentication"
    }
  }
}

A key that does not exist:

{
  "error": {
    "code": "unauthenticated",
    "message": "That API key is not valid, or it has been revoked.",
    "details": {
      "keys": "https://tcggraph.com/dashboard/keys"
    }
  }
}

See Errors for every error and how to handle it.