# Authentication

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

| Plane | What it's for | Credential |
|  --- | --- | --- |
| **Data API** | `/job`, `/stream`, and their downstream endpoints — the crawl/query API | your API key (`kwy_live_…`) |
| **Account / Dashboard** | account setup, API-key management, billing, credit usage | your kwery.co **dashboard session** |


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.

## Data API: your API key

### Getting a key

Sign up at [kwery.co](https://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.

### Key format

```
kwy_live_<48 base64url characters>
```

### Sending your key

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_...
```

```bash
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.

### Legacy authentication

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:

```bash
# 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.

## Account / Dashboard: your kwery.co session

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](/guides/self-serve) for the credits and
usage endpoints.

## The subscription model

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](/guides/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:

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

This is returned with HTTP 200 — see [Errors & limits](/guides/errors-and-limits) for the
response envelope.

## Which auth do I use?

| You're calling... | Use |
|  --- | --- |
| `POST /job`, `GET /job/{id}`, `/job/{id}/download`, `POST /stream`, `/stream/*` | Data API key (`kwy_live_…`) — Bearer or `x-api-key` |
| `GET /v1/account/credits`, `PATCH /v1/account/budget-cap`, API-key management, billing | kwery.co dashboard session |


## Next steps

- [Getting started](/guides/getting-started) — your first authenticated request.
- [Self-serve](/guides/self-serve) — credits, usage, and plans.
- [Code samples](/guides/code-samples) — API key, Basic, and Bearer in Node.js and Python.