llm gateway quickstart.md

Quickstart Guide

Configure the Barndoor LLM Gateway, connect your tools (Cursor, Claude Code, Codex, the OpenAI/Anthropic SDKs), send requests, and troubleshoot.

Quickstart

If your admin has already configured a provider and at least one model, you can be sending requests in two minutes.

Steps

  1. Get your API key: Open Settings → My Models in the Barndoor portal and click Create Key. Copy the bd-… token immediately — you won't be able to see it again.

  2. Find your endpoint: On the same page, the LLM Gateway Endpoint card shows your base URL — it looks like https://app.barndoor.ai/api/llm-gateway/v1.

  3. Send a request:

    curl https://app.barndoor.ai/api/llm-gateway/v1/chat/completions \
  -H "Authorization: Bearer bd-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Say hello"}]
  }'

Use a model name from the Available Models list — either a plain alias (gpt-4o-mini) or a provider-qualified name (openai/gpt-4o-mini).

The rest of this guide expands on each piece — admin setup, client integrations, advanced features, and troubleshooting.

Admin: Configure the Gateway

All admin configuration happens in LLM Management in the Barndoor portal — a single hub whose left-hand nav groups every piece of the gateway.

Group Section What it configures
Connections Credentials The actual upstream credentials (API key, AWS role, Vertex service account, etc.).
Connections Providers A named upstream that references one set of credentials and a model family.
Models Models The catalog of upstream models exposed via this provider.
Models Model Pricing Per-million-token input/output costs used for usage and budget reporting.
Models Model Routes The client-facing model name (for example gpt-4o-mini) and the ordered list of providers / upstream models it resolves to.
Keys API Keys bd-… keys issued on a user's behalf — assigned to a user, a group, or neither (developers mint their own under Settings → My Models).
Controls Budgets, Rate Limits, Model Access Governance policies — token/spending budgets, RPM/TPM throttles, and model allow/denylists. Covered in Configuring LLM Controls.
Step Description
Add Provider Credentials Most credentials live in LLM Management → Credentials, where you save reusable secrets that one or more providers can share.
Create a Provider From the Providers tab, click Add Provider to open the Add a Provider card grid:
Enable Models Open the Models tab and toggle on every upstream model your org should be able to call (for example gpt-4o-mini, claude-sonnet-5, text-embedding-3-large).
Configure Model Pricing (optional) Barndoor already costs every request against its managed default catalog of market-rate prices, so the cost-aware features below work without any setup.
Define Model Routes This is the most important step. A Model Route maps a client-facing model name to one or more (provider, upstream model) targets in priority order.
Add Governance (optional) Once routes are live, layer on usage policies — token budgets, rate limits, and model access. All of these live under the Controls group of LLM Management.
Create an Org API Key (optional) If you need a service-account-style key not tied to a single user, use LLM Management → API Keys → Create Key.

User: Get Your Endpoint and API Key

If you're a developer who just wants to call the gateway from your app or editor:

Steps

  1. Open My Models: In the Barndoor portal, navigate to Settings → My Models. The top of the page shows your LLM Gateway Endpoint — copy this base URL.

  2. Create an API key: Under My API Keys, click Create Key, give it a descriptive name (for example Cursor on laptop), and click Create. The dialog shows a bd-… token — copy it now.

  3. Pick a model: The Available Models section lists every model your admin has enabled and that your access policies allow.

Sending Requests

The gateway speaks two API dialects on the same port:

Endpoint Use it from
POST /v1/chat/completions OpenAI SDKs, LangChain, LlamaIndex, most chatbots
POST /v1/messages Anthropic Messages clients (Claude Code, Anthropic SDK)

List Available Models

To enumerate what a key can call instead of hardcoding model names:

curl https://app.barndoor.ai/api/llm-gateway/v1/models \
  -H "Authorization: Bearer bd-…"

Non-Streaming Chat Completion

curl https://app.barndoor.ai/api/llm-gateway/v1/chat/completions \
  -H "Authorization: Bearer bd-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "You are a terse assistant."},
      {"role": "user", "content": "Summarize Barndoor in one sentence."}
    ]
  }'

Example of Streaming Chat Completion

curl -N https://app.barndoor.ai/api/llm-gateway/v1/chat/completions \
  -H "Authorization: Bearer bd-…" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "stream": true,
    "messages": [{"role": "user", "content": "Stream a haiku about gateways."}]
  }'

Troubleshooting

Common Errors

  1. 401 invalid API key / missing or invalid Authorization header: Confirm the header is Authorization: Bearer bd-… (with a space after Bearer).
  2. 404 model not found / no route configured for alias: Call GET /v1/models to see exactly which aliases your key can use.
  3. 403 Forbidden (model access denied): Check LLM Management → Model Access for the policy that applies to your role/group.

Frequently Asked Questions