Skip to main content

Quickstart

Get your application talking to AI providers through the Observra Gateway in a few minutes. By the end you'll have made one real request through the gateway and confirmed it was observed.

Prerequisites​

  • An Observra account with an Organization, Project, Environment, and Application set up.
  • A Gateway Key for that Application/Environment.
  • Your own API key for whichever provider you want to call (OpenAI, Anthropic, etc.) - Observra never stores this, you keep it.

1. Get a Gateway Key​

Issue a Gateway Key for your Application/Environment from the Observra Dashboard. The plaintext key is shown exactly once at creation - copy it now, only a hash is stored server-side.

See Gateway Authentication for how the key is used, and Quotas & Rate Limits for the optional per-key requests/minute limit.

2. Point your provider SDK at the gateway​

You keep using your existing provider SDK. Only two things change: the baseURL and adding your Gateway Key. Your actual provider API key is still sent - Observra forwards it upstream, it is never stored or logged (see Gateway Authentication). The example below uses /openai - see Other Providers for the full list of supported providers and their URL segments.

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.observra.in/openai/v1", // your gateway's base URL + provider segment
  apiKey: process.env.OPENAI_API_KEY,                   // your own provider key, unchanged
  defaultHeaders: {
    "X-Gateway-Key": process.env.OBSERVRA_GATEWAY_KEY,  // the key from step 1
  },
});

const completion = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "Say hello" }],
});

See OpenAI SDK Integration for more detail, including alternate ways to pass the Gateway Key, and Other Providers if you're not using OpenAI.

3. Make a request​

Run the code above (or any equivalent call through the gateway). The gateway:

  1. Resolves the provider from the URL (/openai/...) - no auto-detection (Routing & Providers).
  2. Authenticates the Gateway Key, checks the optional per-key rate limit and any configured IP allowlist (Quotas & Rate Limits).
  3. Forwards your request to the real provider, streaming or buffering the response back to you exactly as the provider sent it.

Your request completes normally - observability never blocks or slows down your actual AI call.

Troubleshooting​

  • A 401 means the Gateway Key wasn't recognized, or your provider key was missing/rejected.
  • A 403 means the environment's IP allowlist rejected the client IP.
  • Confirm you're using the correct provider URL segment for the provider you're calling (see Routing & Providers).

Next steps​