Skip to main content

Gateway Authentication

The gateway distinguishes two entirely separate credentials on every request:

  • Gateway Key - issued by Observra, identifies which Application/Environment is calling.
  • Provider Key - your own credential for the upstream AI provider (OpenAI, Anthropic, etc.), forwarded but never stored.

You keep using your existing provider SDK; only baseURL and a Gateway Key are configured, and provider API keys are forwarded upstream but never stored or logged.

Gateway Key​

Accepted, in order of precedence, from:

  1. X-Gateway-Key header.
  2. Authorization: Bearer <key> - or the compound form Authorization: Bearer <gateway-key>||<provider-key> (the gateway splits on ||).
  3. A body fallback field: gateway_key, x_gateway_key, or x-gateway-key (useful for clients that can't set arbitrary headers).

If the key is missing, unknown, or revoked, the request is rejected with 401.

Provider Key​

Your actual provider credential is never confused with the Gateway Key. It is accepted from, in order:

  1. X-Provider-Key header.
  2. x-api-key header.
  3. x-goog-api-key header (Gemini only).
  4. api-key header (Azure only).
  5. provider_key query parameter.
  6. The second half of a compound Authorization: Bearer <gateway>||<provider> header.

If no provider key can be resolved, the gateway responds 401 Missing provider key. The provider key is forwarded upstream in the request the gateway sends to the actual provider and is never stored or logged.

Azure OpenAI​

Azure has no single static upstream base URL per provider segment, so an additional header is required: X-Azure-Endpoint, an https:// Azure OpenAI endpoint (*.openai.azure.com or the .azure.us / .azure.eu variants). The gateway validates and normalizes this before using it as the upstream base.

What happens after authentication​

Once both keys are resolved, the gateway also checks the per-key requests/minute quota (if configured) and the environment's IP allowlist before forwarding the request - see Quotas & Rate Limits. Only after all of these pass does the request reach the provider adapter.