{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Authentication","description":"Real-time price and offer data across major marketplaces."},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"authentication","__idx":0},"children":["Authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["kwery has ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["two separate authentication planes"]},". Mixing them up is the most common"," ","integration mistake, so keep this distinction in mind:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Plane"},"children":["Plane"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What it's for"},"children":["What it's for"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Credential"},"children":["Credential"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Data API"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/job"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/stream"]},", and their downstream endpoints — the crawl/query API"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["your API key (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kwy_live_…"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Account / Dashboard"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["account setup, API-key management, billing, credit usage"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["your kwery.co ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["dashboard session"]}]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"data-api-your-api-key","__idx":1},"children":["Data API: your API key"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"getting-a-key","__idx":2},"children":["Getting a key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sign up at ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://kwery.co"},"children":["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 —"," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["entirely in the dashboard"]},". There is no API endpoint for key issuance; keys are a"," ","dashboard-managed resource, not a self-service API call."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The raw key is shown to you ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"key-format","__idx":3},"children":["Key format"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"kwy_live_<48 base64url characters>\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"sending-your-key","__idx":4},"children":["Sending your key"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send it as either a Bearer token or the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]}," header — both are accepted on every"," ","data API request:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Authorization: Bearer kwy_live_...\n"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"x-api-key: kwy_live_...\n"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -s https://api.kwery.co/job \\\n  -H \"Authorization: Bearer $KWERY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"source\": \"idealo\",\n    \"country\": \"de\",\n    \"key\": \"gtin\",\n    \"values\": [\"4006381333962\", \"4719512101148\"]\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Always use HTTPS so the key is encrypted in transit."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"legacy-authentication","__idx":5},"children":["Legacy authentication"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Legacy HTTP Basic (accounts provisioned before self-serve)\ncurl -s https://api.kwery.co/job/{id} -u \"your_username:your_password\"\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Authorization: Bearer <your-jwt>\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you're a new self-serve signup, use your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kwy_live_"]}," key — you won't be issued a"," ","username/password or JWT."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"account--dashboard-your-kweryco-session","__idx":6},"children":["Account / Dashboard: your kwery.co session"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Everything under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/account/*"]}," — credits, API-key management, plan and billing — is"," ","authenticated with the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You never send your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kwy_live_"]}," key to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/account/*"]}," endpoints."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You never use your dashboard session to call ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/job"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/stream"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API keys are created, rotated, and revoked in the dashboard"]}," — there is no"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/account/keys"]}," call you make with your own API key to mint another one."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you're building an integration that also needs to read your own credit balance"," ","programmatically (e.g. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/account/credits"]},"), that call still requires a dashboard"," ","session token, not your data API key. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/self-serve"},"children":["Self-serve"]}," for the credits and"," ","usage endpoints."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-subscription-model","__idx":7},"children":["The subscription model"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Independent of which credential you send, access is also gated per ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["source.country"]}]}," ","pair. For example, an account may be enabled for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idealo.de"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amazon.de"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["amazon.fr"]},"."," ","Self-serve accounts get every live source by default and are gated by credits instead (see"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/self-serve"},"children":["Self-serve"]},"); enterprise accounts may be scoped to specific sources."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When you submit a job for a combination your account is not enabled for, the API returns:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{ \"error\": true, \"message\": \"not subscribed to source\" }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is returned with HTTP 200 — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/errors-and-limits"},"children":["Errors & limits"]}," for the"," ","response envelope."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"which-auth-do-i-use","__idx":8},"children":["Which auth do I use?"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Data API key"]}," (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["kwy_live_…"]},", sent as Bearer or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]},") — everything that submits or"," ","fetches data: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /job"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /job/{id}"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /job/{id}/download"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /stream"]},", and"," ","the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/stream/*"]}," endpoints."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["kwery.co dashboard session"]}," — everything about your account: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /v1/account/credits"]},","," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH /v1/account/budget-cap"]},", API-key management, and billing."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next-steps","__idx":9},"children":["Next steps"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/getting-started"},"children":["Getting started"]}," — your first authenticated request."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/self-serve"},"children":["Self-serve"]}," — credits, usage, and plans."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/guides/code-samples"},"children":["Code samples"]}," — API key, Basic, and Bearer in Node.js and Python."]}]}]},"headings":[{"value":"Authentication","id":"authentication","depth":1},{"value":"Data API: your API key","id":"data-api-your-api-key","depth":2},{"value":"Getting a key","id":"getting-a-key","depth":3},{"value":"Key format","id":"key-format","depth":3},{"value":"Sending your key","id":"sending-your-key","depth":3},{"value":"Legacy authentication","id":"legacy-authentication","depth":3},{"value":"Account / Dashboard: your kwery.co session","id":"account--dashboard-your-kweryco-session","depth":2},{"value":"The subscription model","id":"the-subscription-model","depth":2},{"value":"Which auth do I use?","id":"which-auth-do-i-use","depth":2},{"value":"Next steps","id":"next-steps","depth":2}],"frontmatter":{"seo":{"title":"Authentication"}},"lastModified":"2026-08-13T10:18:58.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/authentication","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}