Authentication

Every endpoint outside the public /public/* Discover signals requires an API key. Keys are sent as a request header — never in the URL — so they don’t leak into logs, browser history or referrers.

#Get an API key

API keys live in the app, on your project:

1. Open Project → API Access in the app sidebar.
2. Enable API access on the Pro plan. This unlocks every endpoint family, a monthly request quota and per-minute rate limit (see Rate limits).
3. Create a key, give it a name, and copy it. You can hold up to 10 keys per project — use separate keys per environment or service so you can rotate one without touching the rest.

#Send the key

Provide the key on every request in one of two equivalent ways.

X-API-Key header — the simplest form:

curl "https://d2tr.com/api/v1/trends?region=us" \
  -H "X-API-Key: $D2TR_API_KEY"

Authorization: Bearer header — if you prefer the OAuth-style convention:

curl "https://d2tr.com/api/v1/trends?region=us" \
  -H "Authorization: Bearer $D2TR_API_KEY"

Both are accepted on every authenticated endpoint. Pick one; don’t send both.

#Market scopes

A key can be restricted to a set of markets. A market-scoped key may only read the countries it was granted — a request with a region the key doesn’t allow returns 403 Forbidden, and endpoints that return many markets silently drop the ones outside the key’s scope. A key with no restriction can read every market. Set scopes when you create the key in API Access.

#Authentication errors

• 401 Unauthorized — the key is missing, malformed or revoked. The response tells you which header to send.
• 403 Forbidden — the key is valid but not allowed for the requested market.
• 503 Service Unavailable — the auth service is momentarily degraded. This is not an “invalid key” signal; retry after the Retry-After interval rather than rotating the key.