> ## 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.

# LLM Gateway API

> Programmatically configure the Barndoor LLM Gateway: credentials, providers, model routes, pricing, governance, routing policies, launch profiles, and gateway API keys.

The LLM Gateway API is the configuration surface behind the **LLM Management**
hub in the Barndoor portal — exposed so platform teams can script provisioning,
manage configuration as code, and run automated audits.

<Note>
  This API configures how the gateway routes and governs traffic. It is
  **separate** from the runtime endpoints that carry LLM traffic
  (`/v1/chat/completions`, `/v1/messages`, `/v1/embeddings`, …), which follow
  OpenAI's and Anthropic's own API shapes and are documented in the
  [Quickstart Guide](/how-tos/llm-gateway-quickstart#sending-requests).
</Note>

## Base URL

All configuration endpoints sit under `/api/llm-gateway/admin` on your Barndoor
portal host:

```
https://app.barndoor.ai/api/llm-gateway/admin
```

On a dedicated or self-hosted deployment, replace `app.barndoor.ai` with your
organization's portal hostname.

For comparison, the runtime endpoints live under
`https://app.barndoor.ai/api/llm-gateway/v1`.

## Authentication

Configuration endpoints require a **Barndoor user bearer token (JWT)** — the
same identity you use to sign in to the portal. The easiest way to obtain one
from a script is the Barndoor SDK:

```ts theme={null}
import { loginInteractive } from "@barndoor/sdk";

const sdk = await loginInteractive();
// sdk includes the bearer token; pass it on every API call.
```

Send the token on every request:

```bash theme={null}
curl https://app.barndoor.ai/api/llm-gateway/admin/providers \
  -H "Authorization: Bearer eyJhbGciOi..."
```

<Warning>
  The `bd-…` gateway API keys you create through this API authenticate
  **runtime** traffic only (`/v1/chat/completions`, `/v1/messages`, and so on).
  They are **not** accepted on `/admin/...` endpoints. Use a bearer token for
  configuration and a `bd-…` key for traffic.
</Warning>

## Permissions

Every configuration endpoint requires the **admin** (or **superadmin**) role
on the calling user. Users without it receive `403`. Developers manage their
own keys and see their available models in the portal, under
**Settings → My Models**.

## Conventions

* Every resource is scoped to the caller's organization. There is no `org_id`
  parameter — it's resolved from your token. A resource in another
  organization behaves as if it doesn't exist (`404`).
* Timestamps are RFC 3339 (`2026-06-12T18:30:00Z`).
* Most resources are identified by UUID. Launch profiles are identified by
  their slug, and route group members by route name.
* Most update endpoints accept partial bodies — fields you omit are left
  unchanged. A handful also distinguish **omitted** from **explicit `null`**
  (which clears the value); the affected fields are documented inline.

## Errors

Errors come back with an HTTP status that matches the failure and a JSON body
in OpenAI's error shape:

```json theme={null}
{
  "error": {
    "message": "request_timeout_secs must be between 1 and 3600",
    "type": "invalid_request_error",
    "code": null
  }
}
```

| Status | `type` | Meaning |
| - | - | - |
| `400` | `invalid_request_error` | Validation failure — fix the request body and retry. |
| `401` | `authentication_error` | Missing or invalid bearer token. |
| `403` | `permission_error` | The caller's role doesn't allow this action. |
| `404` | `not_found_error` | The resource doesn't exist, or belongs to another organization. |
| `409` | `conflict_error` | Conflicts with existing data — the `message` says what. |
| `503` | `service_unavailable_error` | Transient; retry with backoff. |
| `500` | `internal_error` | Unexpected server error. |

## API groups

The endpoints are grouped by the resource they manage. Each group maps to a
section of **LLM Management**.

| Group | Paths | Manages | Portal section |
| - | - | - | - |
| **Credentials** | `/admin/connections` | Reusable upstream credentials — API keys, AWS IAM roles, Google service accounts, Entra ID service principals. Includes the AWS role configuration and per-credential AWS trust info. | Credentials |
| **Providers** | `/admin/providers` | Named upstream connections, each using one set of credentials, and the model routes that target a provider. | Providers |
| **Model Routes** | `/admin/model-mappings` | Enabled models and client-facing routes with their ordered targets, including reordering targets. | Models, Model Routes |
| **Route Groups** | `/admin/model-route-groups` | Named sets of routes that a model access policy can target as a unit, and their members. | Model Routes → Route Groups |
| **Model Pricing** | `/admin/model-pricing` | Organization pricing rules, their history and archived versions, and Barndoor's default price catalog. | Model Pricing |
| **Budgets** | `/admin/budgets` | Token and spending budgets. | Budgets |
| **Rate Limits** | `/admin/rate-limits` | Request and token throughput limits. | Rate Limits |
| **Model Access** | `/admin/model-access` | Allow and deny policies for models and routes. | Model Access |
| **Routing Policies** | `/admin/routing-policies` | Virtual model names that pick a model per request. | Routing Policies |
| **Routing Rules** | `/admin/routing-rules` | Plain-English rules that constrain a routing policy's choice. | Routing Rules |
| **Launch Profiles** | `/admin/agent-runtime-profiles` | Organization defaults for governed Claude Code and Codex sessions, including which profile is the default. | Launch Profiles |
| **API Keys** | `/admin/api-keys` | `bd-…` gateway keys — create, list, disable, and revoke. | API Keys |
| **Governance Configuration** | `/admin/governance-config` | Organization-wide settings: whether routes require pricing, the default model access posture, and whether callers must use a routing policy. | Model Pricing, Model Access, Routing Policies |

Browse each group's operations in the sidebar.

<Note>
  Routing policies, routing rules, and launch profiles may not be enabled for
  your organization yet — contact Barndoor if you need them.
</Note>

## Where to next

* New to the gateway? Read [Using the LLM Gateway](/how-tos/use-llm-gateway).
* Setting it up for the first time? Follow the [Quickstart Guide](/how-tos/llm-gateway-quickstart),
  which also covers the runtime endpoints (chat completions, messages,
  embeddings, model listing).
* Managing configuration as code? See the [Terraform provider](/terraform/llm-gateway).


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