> ## Documentation Index
> Fetch the complete documentation index at: https://docs.barndoor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Using the LLM Gateway

> Send LLM traffic from Cursor, Claude Code, Codex, your apps, and the OpenAI / Anthropic SDKs through the Barndoor LLM Gateway.

## Overview

The Barndoor **LLM Gateway** is a proxy that sits between your AI tools and one or more upstream LLM providers. It speaks the **OpenAI** API (Chat Completions, Completions, Responses, Embeddings) and the **Anthropic Messages** API natively, so most clients — the OpenAI and Anthropic SDKs, Cursor, Claude Code, Codex, LangChain, and similar tools — work by pointing their base URL at Barndoor.

Pointing your client at the gateway gives you a single endpoint that:

* **Centralizes provider credentials** — provider API keys and cloud roles stay in Barndoor, never on developer machines.
* **Enforces governance** — token and spending budgets, rate limits, and per-user / per-group model access policies.
* **Routes intelligently** — named model routes with ordered fallbacks, automatic retries on upstream 429s, and health-aware failover.
* **Records usage** — per-request tokens, cost, and request duration, reported on the [LLM Usage Dashboard](/how-tos/read-llm-usage-dashboard).

<Info>
  Anything that speaks the OpenAI API can use the gateway by setting its base URL. Clients built on Anthropic's Messages API (for example **Claude Code**) talk to the gateway directly as well. See [Supported Endpoints](#supported-endpoints).
</Info>

## Architecture at a Glance

<div className="bd-diagram" role="group" aria-label="Barndoor LLM Gateway architecture: clients send OpenAI- or Anthropic-format requests with a Barndoor API key; the gateway authenticates, enforces rate limits and budgets, checks model access, and routes with retry and failover to upstream providers such as OpenAI, Anthropic, Azure, AWS Bedrock, Google Vertex AI, Google AI (Gemini), and xAI.">
  <div className="bd-arch-tier">
    <div className="bd-diagram-label">Your clients</div>

    <div className="bd-arch-row">
      <span className="bd-chip">Cursor</span>
      <span className="bd-chip">Claude Code</span>
      <span className="bd-chip">Codex</span>
      <span className="bd-chip">SDKs</span>
      <span className="bd-chip">curl</span>
    </div>
  </div>

  <div className="bd-arch-link"><span><code>bd-…</code> API key · OpenAI or Anthropic JSON</span></div>

  <div className="bd-arch-gateway">
    <div className="bd-arch-title">Barndoor LLM Gateway</div>

    <ol className="bd-arch-stages">
      <li><span className="bd-num">1</span><strong>Authenticate</strong><span>Barndoor API key, user and org</span></li>
      <li><span className="bd-num">2</span><strong>Rate limits & budgets</strong><span>Requests, tokens, and spend</span></li>
      <li><span className="bd-num">3</span><strong>Model access</strong><span>Allow and deny policies</span></li>
      <li><span className="bd-num">4</span><strong>Route</strong><span>Model routes, retries, failover</span></li>
    </ol>

    <div className="bd-arch-foot">Every request's tokens, cost, and duration are recorded to the LLM Usage Dashboard</div>
  </div>

  <div className="bd-arch-link"><span>Provider credentials, stored encrypted</span></div>

  <div className="bd-arch-tier">
    <div className="bd-arch-row">
      <span className="bd-chip">OpenAI</span>
      <span className="bd-chip">Anthropic</span>
      <span className="bd-chip">Azure OpenAI / Microsoft Foundry</span>
      <span className="bd-chip">AWS Bedrock</span>
      <span className="bd-chip">Google Vertex AI</span>
      <span className="bd-chip">Google AI (Gemini)</span>
      <span className="bd-chip">xAI (Grok)</span>
      <span className="bd-chip">…and more</span>
    </div>

    <div className="bd-diagram-label" style={{ marginTop: "0.5rem", marginBottom: 0 }}>Upstream providers</div>
  </div>
</div>

## Key Concepts

The gateway is configured from a small set of building blocks. Each one references the one above it.

| Concept | What it is |
| - | - |
| **Credentials** | A saved secret or identity that authorizes Barndoor against an upstream account — an API key, an AWS IAM role, a Google service account, an Entra ID service principal. Stored encrypted and never returned to the browser. |
| **Provider** | A named upstream connection that uses one set of credentials. The provider carries the settings that decide how requests are sent — for example which model API family it targets, whether a failing health check blocks traffic, and whether token cost is calculated. |
| **Model** | An upstream model enabled on a provider, such as `gpt-5.4-mini` on your OpenAI provider. Enabling a model makes it callable as `<provider name>/<model>`. |
| **Model Route** | A client-facing model name that maps to one or more provider models, tried top to bottom as fallbacks. This is the name most callers put in the `model` field. |
| **API key** | A `bd-…` key that callers send to authenticate. A key belongs to a user, a group, or the whole organization, and governance policies apply based on who the key belongs to. |

### Credentials and providers

Credentials and providers are separate on purpose: **one set of credentials can back many providers.** You might save a single OpenAI key and create two providers from it — one for everyday traffic and one reserved for a specific team — or save one AWS IAM role and create a provider for each Bedrock API family you use.

The split follows what each object is responsible for:

* **Credentials** hold what authorizes the account: the key or identity, and the account-level location such as the base URL, AWS region, or GCP project. Rotating a key on the credentials updates every provider that uses it.
* **Providers** hold how requests are made: the **Model API Family** (for AWS Bedrock, Google Vertex AI, and Microsoft Foundry), health-check enforcement, catalog model sync, and billing.

Because many providers can share one set of credentials, usage and cost are reported per provider, not per credential.

### Models and routes

A model has to be **enabled on a provider** before anything can call it. Once enabled, it is reachable by its provider-prefixed name (for example `OpenAI Prod/gpt-5.4-mini`, using the provider's name).

A **Model Route** gives one or more enabled models a single plain name (for example `gpt-5.4-mini` or `team-coding-model`) and an order to try them in. If the first target fails with a failover-eligible error, the gateway tries the next. See [Model Naming](/how-tos/llm-gateway-quickstart#model-naming) for how the gateway reads the `model` field, and [Failover, Cooldowns, and Route Health](/how-tos/llm-gateway-failover-and-cooldowns) for when it moves to the next target.

### Routing policies

A **routing policy** is a virtual model name that picks a model per request — routing each request to the cheapest model strong enough for it, from an ordered list of options — and **routing rules** constrain that choice for particular kinds of request. See [Routing Policies](/how-tos/llm-routing-policies).

<Note>
  Routing policies may not be enabled for your organization yet — contact Barndoor if you don't see **Routing Policies** in **LLM Management**.
</Note>

## Where Things Live in the Portal

| Area | Who sees it | What's there |
| - | - | - |
| **LLM Management** | Admins | The configuration hub: **Credentials** and **Providers** (Connections); **Models**, **Model Pricing**, **Model Routes**, **Launch Profiles**, **Routing Policies**, and **Routing Rules** (Models); **API Keys** (Keys); **Budgets**, **Rate Limits**, and **Model Access** (Controls). |
| **Reporting → LLM Usage Dashboard** | Admins | Per-request usage, cost, and duration across the organization — see [Reading the LLM Usage Dashboard](/how-tos/read-llm-usage-dashboard). |
| **Settings → My Models** | Every user | **Available Models** (the model names you can call), **Gateway Endpoint** (your base URLs), and **API Keys** (create and revoke your own `bd-…` keys). |

Some sections of **LLM Management** appear only when the related feature is enabled for your organization:

* **Launch Profiles** set the organization's defaults for governed Claude Code and Codex sessions started with `barndoor run`. See [Barndoor Bridge](/how-tos/barndoor-bridge/overview).
* **Routing Policies** and **Routing Rules** — see [Routing policies](#routing-policies).
* In some organizations, the separate **Models** section is replaced by a **Models** panel on each provider's detail page (click the provider's name on **Providers**). The controls are the same.

If a section described here is missing, contact Barndoor to have it enabled.

## Supported Providers

Pick these from **Providers → Add Provider**. Cards marked **Official** come from Barndoor's provider catalog, with default base URLs and model lists pre-filled.

| Provider | Authentication |
| - | - |
| **OpenAI** | API key |
| **OpenAI Codex OAuth** | Forwards each developer's own ChatGPT sign-in from Codex — see [Use Codex with the LLM Gateway](/how-tos/use-codex-with-llm-gateway) |
| **Anthropic** | API key |
| **Anthropic OAuth** | Forwards each developer's own Claude sign-in from Claude Code — see [Anthropic OAuth passthrough](/how-tos/llm-gateway-quickstart#step-1-add-provider-credentials) |
| **Azure OpenAI** | API key |
| **Microsoft Foundry** | Deployment API key, or Entra ID service principal |
| **AWS Bedrock** | AWS IAM role, static AWS keys, or Bedrock API key |
| **Google Vertex AI** | Workload Identity / ADC, service account impersonation, or service account key |
| **Google AI (Gemini)** | API key |
| **Cohere**, **DeepSeek**, **Fireworks AI**, **Groq**, **Mistral AI**, **OpenRouter**, **Perplexity**, **Together AI**, **xAI (Grok)** | API key |
| **TypeSafe AI** (Jev classifier) | API key. Serves `/systemone` only; see [Calling Jev Through the Gateway](/how-tos/use-jev-classifier). |
| **Custom Provider** | Any OpenAI-compatible endpoint, with your own base URL and API key — including self-hosted models. See [Connect a Self-Hosted Model](/how-tos/connect-self-hosted-model). |

## Supported Endpoints

All endpoints live under your gateway base URL, `https://app.barndoor.ai/api/llm-gateway/v1`.

| Endpoint | Wire format | Typical clients |
| - | - | - |
| `POST /chat/completions` | OpenAI Chat Completions | OpenAI SDKs, LangChain, LlamaIndex, Cursor |
| `POST /completions` | OpenAI legacy completions | Older OpenAI text-completion clients |
| `POST /responses` | OpenAI Responses | Codex, OpenAI Responses API clients |
| `POST /embeddings` | OpenAI Embeddings | OpenAI / LangChain embeddings clients |
| `POST /messages` | Anthropic Messages | Claude Code, Anthropic SDKs |
| `POST /messages/count_tokens` | Anthropic token counting | Claude Code and Anthropic clients that pre-flight token counts |
| `GET /models` | OpenAI or Anthropic model list | Any client that lists models on startup |
| `POST /systemone` | TypeSafe System One | TypeSafe's SDKs, for the Jev classifier. See [Calling Jev Through the Gateway](/how-tos/use-jev-classifier). |

For chat-style traffic, the endpoint a client calls and the provider that serves it are independent: for example, a Claude Code request on `/messages` can be routed to Claude on Anthropic, AWS Bedrock, Google Vertex AI, or Microsoft Foundry. Request examples are in the [Quickstart Guide](/how-tos/llm-gateway-quickstart#sending-requests).

## Authentication

Callers authenticate with a Barndoor gateway **API key** (`bd-…`), sent in either header:

* `Authorization: Bearer bd-…` — what OpenAI clients send.
* `x-api-key: bd-…` — what Anthropic clients send.

When both are present, the gateway reads the key from `x-api-key`. That lets Claude Code and Codex send the gateway key in `x-api-key` while passing the developer's own Claude or ChatGPT sign-in token in `Authorization` for the OAuth passthrough providers.

There are two ways to get a key:

* **Developers** create their own under [**Settings → My Models → API Keys**](https://app.barndoor.ai/settings/models?section=api-keys). Usage is attributed to that user.
* **Admins** create keys under **LLM Management → API Keys**, assigned to a user, to a group, or to neither (an organization-wide key, typically for services and CI).

The gateway's configuration API (the one behind **LLM Management**) uses your Barndoor login instead of a `bd-…` key — see the [LLM Gateway API](/api-reference/llm-gateway/introduction).

## Before You Begin

You'll need:

* A Barndoor account with access to **LLM Management** (admins) and/or **Settings → My Models** (any user).
* The base URL of your Barndoor portal. Throughout these guides we use `https://app.barndoor.ai` (the Barndoor SaaS host). The authoritative value for your tenant is on the **LLM Gateway Endpoint** card under [**Settings → My Models → Gateway Endpoint**](https://app.barndoor.ai/settings/models?section=endpoint) — copy it from there.
* For **admins** setting up the gateway for the first time: an account with at least one upstream provider (OpenAI, Anthropic, AWS, Google Cloud, and so on) and credentials for it.

<Note>
  The LLM Gateway is enabled per organization. If you don't see **LLM Management** or **My Models** in the sidebar, contact your Barndoor admin or [support@barndoor.ai](mailto:support@barndoor.ai) to have it enabled. **LLM Management** is visible to admins only.
</Note>

<Info>
  **Self-hosted and private-cloud deployments:** if Barndoor runs on your own infrastructure, swap `app.barndoor.ai` for your organization's portal hostname everywhere in these guides. The path (`/api/llm-gateway/v1`) is the same.
</Info>

## Next Steps

**Admins** set the gateway up first — continue to the **[Quickstart Guide](/how-tos/llm-gateway-quickstart)**, which walks through credentials, providers, models, routes, and keys, then sends a first request.

After that, layer on:

* **[Configuring LLM Controls](/how-tos/use-llm-controls)** — budgets, rate limits, and model access.
* **[Managing Model Pricing](/how-tos/manage-model-pricing)** — override Barndoor's default prices.
* **[Failover, Cooldowns, and Route Health](/how-tos/llm-gateway-failover-and-cooldowns)** — how routes fail over and recover.

**Developers** working against an already-configured gateway can go straight to **[Connecting Your Tools to the LLM Gateway](/how-tos/connect-tools-to-llm-gateway)** — getting a key, a model name, and the endpoint, then configuring Cursor, Claude Code, LangChain, and the OpenAI / Anthropic SDKs.

For Codex CLI and Codex Desktop specifically, see **[Use Codex with the LLM Gateway](/how-tos/use-codex-with-llm-gateway)**.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.