# Authentication The Ask Xverum API uses API keys for authentication. Each request must carry your key in the `x-api-key` HTTP header. ## How it works ```http POST /v1/search HTTP/1.1 Host: search-api.xverum.com x-api-key: XVERUM-API-KEY Content-Type: application/json ``` Every authenticated request is validated against the Xverum user-management service, which confirms the API key resolves to an active account. If it does not, the request is rejected before any search work is done. See the errors below. Validation results are cached briefly to avoid a round-trip on every request. The key is a long-lived credential — there is no token-exchange step and no expiry on the key itself. Rotate it through user-management. ## Getting a key Your API keys are available to view and manage directly in your [Xverum dashboard](https://myaccount.xverum.com/dashboard) — no need to contact support. Treat the key like a password: - Never commit it to source control. - Never embed it in browser-side code — keys belong on a server you control. - Rotate keys periodically and on any suspected leak. ## One key, one account Multiple API keys for the same Xverum account share one **credit balance**. Each key has its own **rate-limit bucket** (60 requests/minute by default — see [Rate limits](https://ask.xverum.com/docs/rate-limits.md)). The keys exist for rotation and for labelling distinct integrations. ## Error format Every API error returns a structured envelope with a stable, machine-readable `code`: ```json { "error": { "code": "out_of_credits", "message": "Out of credits. Top up to continue.", "request_id": "9f1c2a7e6b3d4f08", "upgrade_url": "https://myaccount.xverum.com/plans" } } ``` - **`code`** — a value from a documented closed enum. Branch on this, never on `message`. - **`message`** — human-readable, may be reworded at any time. Do not parse it. - **`request_id`** — the same id returned in the `X-Request-Id` response header; quote it in support tickets. - **`upgrade_url`** — present **only** on the `402 out_of_credits` error; a URL to top up credits. Optional — absent on every other error. Treat unknown `error.code` values as forward-compatible: map any code you don't recognise to your generic failure handling keyed off the HTTP status. ## Errors | Status | `error.code` | Meaning | What to do | | --- | --- | --- | --- | | `401` | `invalid_api_key` | Missing or invalid API key. | Check the `x-api-key` header is present and spelled exactly. | | `402` | `out_of_credits` | Credit balance is zero or negative. | Top up the account before retrying. | | `403` | `account_not_authorized` | Account is not authorized. | Contact Xverum support. | | `429` | `rate_limited` | Rate limit exceeded. | Wait for `Retry-After` seconds and retry. See [Rate limits](https://ask.xverum.com/docs/rate-limits.md). | See each endpoint reference for the full per-endpoint error list ([Search](https://ask.xverum.com/docs/search.md), [Profiles](https://ask.xverum.com/docs/profiles.md)).