Authentication

kwery has two separate authentication planes. Mixing them up is the most common integration mistake, so keep this distinction in mind:

Your API key never authenticates dashboard endpoints, and your dashboard session never authenticates data API calls. See the table at the bottom for a quick reference.

Sign up at kwery.co and an API key is issued to your org automatically. You can also create additional keys, rotate, or revoke them at any time — entirely in the dashboard. There is no API endpoint for key issuance; keys are a dashboard-managed resource, not a self-service API call.

The raw key is shown to you once, at creation time. kwery stores only a SHA-256 hash of it — if you lose the raw value, revoke it and issue a new one.

kwy_live_<48 base64url characters>

Send it as either a Bearer token or the x-api-key header — both are accepted on every data API request:

Authorization: Bearer kwy_live_...

x-api-key: kwy_live_...

curl -s https://api.kwery.co/job \
  -H "Authorization: Bearer $KWERY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "idealo",
    "country": "de",
    "key": "gtin",
    "values": ["4006381333962", "4719512101148"]
  }'

Always use HTTPS so the key is encrypted in transit.

Existing and enterprise clients provisioned before self-serve may still authenticate with HTTP Basic (username + password) or a Bearer JWT issued directly by us. Both continue to work unchanged on the data API:

# Legacy HTTP Basic (accounts provisioned before self-serve)
curl -s https://api.kwery.co/job/{id} -u "your_username:your_password"

Authorization: Bearer <your-jwt>

If you're a new self-serve signup, use your kwy_live_ key — you won't be issued a username/password or JWT.

Everything under /v1/account/* — credits, API-key management, plan and billing — is authenticated with the Supabase JWT your browser session holds when you're logged in to the kwery.co dashboard. This is a separate identity from your data API key:

• You never send your kwy_live_ key to /v1/account/* endpoints.
• You never use your dashboard session to call /job or /stream.
• API keys are created, rotated, and revoked in the dashboard — there is no /v1/account/keys call you make with your own API key to mint another one.

If you're building an integration that also needs to read your own credit balance programmatically (e.g. GET /v1/account/credits), that call still requires a dashboard session token, not your data API key. See Self-serve for the credits and usage endpoints.

Independent of which credential you send, access is also gated per source.country pair. For example, an account may be enabled for idealo.de, amazon.de, and amazon.fr. Self-serve accounts get every live source by default and are gated by credits instead (see Self-serve); enterprise accounts may be scoped to specific sources.

When you submit a job for a combination your account is not enabled for, the API returns:

{ "error": true, "message": "not subscribed to source" }

This is returned with HTTP 200 — see Errors & limits for the response envelope.

• Data API key (kwy_live_…, sent as Bearer or x-api-key) — everything that submits or fetches data: POST /job, GET /job/{id}, GET /job/{id}/download, POST /stream, and the /stream/* endpoints.
• kwery.co dashboard session — everything about your account: GET /v1/account/credits, PATCH /v1/account/budget-cap, API-key management, and billing.

• Getting started — your first authenticated request.
• Self-serve — credits, usage, and plans.
• Code samples — API key, Basic, and Bearer in Node.js and Python.