## LLM Gateway API

The LLM Gateway API is the same surface that powers the **LLM Management** hub (including its **Controls** sections) and **Settings → My Models** in the Barndoor portal — exposed so platform teams can script provisioning, run automated audits, and integrate with their own management tooling.

These endpoints control how the gateway routes traffic. They are **distinct** from the runtime LLM endpoints (`/v1/chat/completions`, `/v1/messages`, `/v1/embeddings`, …) — those are documented in [Quickstart Guide](https://docs.barndoor.ai/how-tos/llm-gateway-quickstart#sending-requests).

## Base URL

All requests are issued against your Barndoor instance. The administrative API sits under `/api/llm-gateway`:

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

Replace `app.barndoor.ai` with your tenant host on Enterprise.

## Authentication

Endpoints require a **JWT Bearer token** issued by your organization’s identity provider — the same login flow you use for the Barndoor portal. The easiest way to obtain a token from a script is the Barndoor SDK:

```
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:

```
curl https://app.barndoor.ai/api/llm-gateway/admin/providers \
  -H "Authorization: Bearer eyJhbGciOi..."
```

The `bd-…` API keys you create through these endpoints are for the runtime proxy (`/v1/chat/completions`, `/v1/messages`, etc.) — they are **not** accepted on `/admin/...` or `/user/...` paths. Use a JWT for administration and a `bd-…` key for traffic.

## Permissions

| Endpoint family | Required role |
| --- | --- |
| `/admin/...` | `admin` (or higher) on the calling user |
| `/user/...` | Any authenticated user (results scoped to that user) |

## Conventions

- Every resource is automatically scoped to the caller’s organization. There is no `org_id` parameter on any endpoint — it’s resolved from your JWT.
- All timestamps are RFC 3339 (`2026-06-12T18:30:00Z`).
- All identifiers are UUIDv4.
- `PUT` / update endpoints accept partial bodies — fields you omit are left unchanged. A handful of endpoints also distinguish **omitted** from **explicit `null`** on `Option`-typed columns; the affected fields are documented inline.

## Errors

Errors come back with a stable JSON shape and an HTTP status code that matches the failure mode:

```
{
  "error": "BadRequest",
  "message": "request_timeout_secs must be between 1 and 3600"
}
```

| Status | Meaning |
| --- | --- |
| `400` | Validation failure — fix the request body and retry |
| `401` | Missing or invalid JWT |
| `403` | The caller’s role does not allow this action |
| `404` | Resource does not exist (or belongs to another organization) |
| `409` | Conflicts with existing data (rare; specifics in `message`) |
| `5xx` | Transient gateway error |

## Resource map

[**Credentials** 
\
Reusable upstream credentials — API keys, AWS roles, Vertex service accounts.](https://docs.barndoor.ai/api-reference/llm-gateway/credentials/listCredentials)

[**Providers** 
\
Named upstream providers backed by a credential and a model family.](https://docs.barndoor.ai/api-reference/llm-gateway/providers/listProviders)

[**Model Routes** 
\
Map a client-facing alias to one or more provider/model pairs with failover.](https://docs.barndoor.ai/api-reference/llm-gateway/model-routes/listAllRoutes)

[**Model Pricing** 
\
Per-million-token costs and history; powers usage and budget reporting.](https://docs.barndoor.ai/api-reference/llm-gateway/model-pricing/listPricing)

[**Rate Limits** 
\
Requests-per-minute and tokens-per-minute caps.](https://docs.barndoor.ai/api-reference/llm-gateway/rate-limits/listRateLimits)

[**Token Budgets** 
\
Daily, weekly, and monthly token / cost budgets with alert thresholds.](https://docs.barndoor.ai/api-reference/llm-gateway/token-budgets/listBudgets)

[**Model Access** 
\
Allow- and deny-list policies for models, providers, or aliases.](https://docs.barndoor.ai/api-reference/llm-gateway/model-access/listModelAccess)

[**Smart Models** 
\
Routing policies that pick a target model per-request.](https://docs.barndoor.ai/api-reference/llm-gateway/smart-models/listSmartModels)

[**Governance Configuration** 
\
Org-wide gateway behavior toggles.](https://docs.barndoor.ai/api-reference/llm-gateway/governance/getGovernanceConfig)

[**Route Health** 
\
Operational view of upstream ejection and recovery.](https://docs.barndoor.ai/api-reference/llm-gateway/route-health/getRouteHealth)

[**API Keys** 
\
Org-managed `bd-…` gateway API keys.](https://docs.barndoor.ai/api-reference/llm-gateway/api-keys/listApiKeys)

[**User self-service** 
\
Personal API keys and the model catalog scoped to the calling user.](https://docs.barndoor.ai/api-reference/llm-gateway/user/listUserApiKeys)

## Where to next

- New to the gateway? Read [Using the LLM Gateway](https://docs.barndoor.ai/how-tos/use-llm-gateway).
- Looking for the runtime proxy reference (chat completions, messages, embeddings)? See the [Quickstart Guide](https://docs.barndoor.ai/how-tos/llm-gateway-quickstart).