Docs/Get Started/Authentication
Authentication
Your vk_ key identifies you to valite; your provider key passes through to the provider untouched.
Two keys, two jobs
Every request through the gateway carries two credentials that never mix:
Your provider key (OpenAI's Authorization: Bearer sk-... or Anthropic's x-api-key: sk-ant-...) is forwarded to the provider exactly as sent. valite never stores it, and it is redacted from the call log.
Your valite key — prefixed vk_, created in the dashboard — identifies your organization to the gateway. It is stripped before the request goes upstream, so the provider never sees it.
Sending your valite key
The gateway accepts the key on either of two headers:
Accepted headers
x-valite-api-keyheaderThe canonical header. Always consumed by the gateway and never forwarded upstream.
x-api-keyheaderIf the value starts with vk_, it is treated as your valite key and removed. Any other value (e.g. your Anthropic key) passes through untouched. Useful for SDKs that only expose a single key field.
Not a Bearer token
Authorization header is never used for the valite key — it belongs to your provider credential and is forwarded as-is. Sending Authorization: Bearer vk_... will reach the provider and fail there.client = OpenAI(
base_url="https://gateway.valite.ai/openai/v1",
default_headers={"x-valite-api-key": "vk_..."},
)A missing key (where required) returns 401 with: missing valite api key: send x-valite-api-key: vk_… (or a vk_ value in x-api-key) alongside your provider key. An invalid key returns 401 invalid valite api key.
Provider key passthrough
For calls to the provider your client addressed, valite adds no credentials of its own — your key is the only one used. The gateway holds provider keys only for cross-provider replays and routes(e.g. replaying OpenAI traffic against an Anthropic model), configured server-side per upstream. When such a route is applied, your credential headers are dropped and the gateway's own key for the target provider is attached instead.
How keys are verified
The gateway verifies vk_keys against the valite control plane and caches verdicts by key digest — valid keys for 60 seconds, invalid ones for 10 — so verification adds no measurable latency in steady state. Verification also stamps the key's last usedtime, which is what the dashboard's key list shows.
If the control plane is unreachable, gateways configured to require keys fail closed (requests are rejected); gateways where keys are optional fail open.
Control-plane access
The control plane (/valite/api/…) does not take vk_ keys. When an admin secret is configured — which the gateway requires on any non-loopback listen — every control-plane request, reads and job triggers alike, must present x-valite-admin-secret. Requests are scoped to one organization by x-valite-account-id; the dashboard proxies control-plane calls for your signed-in org, attaching both headers for you. A request without an account header is the un-scoped operator view — it needs the secret too. Only a secretless loopback dev gateway serves the control plane header-free. See the Jobs API.