Authentication
Authenticate every inference request with an OpenRelay API key (vl_…), sent as a Bearer token or an x-api-key header.
The Inference API authenticates requests with an OpenRelay API key. Keys are
prefixed with vl_ and are bound to a single organization, whose balance pays
for the usage.
Create a key
Create a key in the dashboard under Settings → API Keys. The plaintext value is shown once — store it somewhere safe.
export OPENRELAY_API_KEY="vl_your_api_key"Sending the key
The gateway accepts the key in either of two headers, so it works as a drop-in for both ecosystems of clients:
An alternative header accepted for clients that prefer it. This is the header the Anthropic SDKs and Claude Code send by default, so it's what you use for Messages requests.
curl https://api.openrelay.inc/v1/models \
-H "x-api-key: $OPENRELAY_API_KEY"A well-formed Authorization: Bearer <key> is used first; if that header is
absent or isn't a valid Bearer token, the x-api-key header is used instead.
Both headers work on every endpoint, including both /v1/chat/completions
and /v1/messages; pick whichever your client sends natively.
One key, two hosts
The examples above list models against api.openrelay.inc because the
model catalog lives on the control plane. Inference traffic itself (chat
completions, messages, and the Batch API) goes to
inference.openrelay.inc. The same vl_ key works on both hosts.
Keep keys secret
Never commit API keys to source control, embed them in client-side code, or share them in screenshots. Use environment variables or a secrets manager. If a key leaks, revoke it from the dashboard and issue a new one.
Authentication errors
A missing or invalid key returns 401 Unauthorized with an OpenAI-style error
body:
{
"error": {
"message": "invalid API key",
"type": "authentication_error",
"code": "invalid_api_key"
}
}The code distinguishes the cause:
code | Cause |
|---|---|
missing_api_key | No key was sent. Add an Authorization: Bearer or x-api-key header. |
invalid_api_key | The key was not recognized. |
revoked_api_key | The key was revoked. Create a new one. |
expired_api_key | The key has passed its expiry. Create a new one. |
See Errors for the full status-code reference.