Quickstart Guide - Barndoor Documentation

Quickstart

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

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

Skip this section if your admin has already set up providers and models. Jump to Get Your Endpoint and API Key.

All admin configuration happens in LLM Management in the Barndoor portal — a single hub whose left-hand nav groups every piece of the gateway. Work top to bottom: provision your connections and models, mint keys, then layer on governance.

Per-request usage and cost reporting live separately, under Reporting → LLM Usage Dashboard.

Step 1: Add Provider Credentials

Most credentials live in LLM Management → Credentials, where you save reusable secrets that one or more providers can share. A few setups have their own flow:

• Anthropic OAuth passthrough is configured exclusively on the Providers tab (there are no Credentials to save) — see Anthropic OAuth passthrough below.
• AWS Bedrock and Google Vertex AI can be set up from either tab — pre-create reusable Credentials and attach them on the Providers tab, or configure them inline when you create the Provider. The Providers-tab flow walks you through a guided checklist and is the easiest first-time path.

OpenAI / Anthropic / Azure OpenAI (API key)

The simplest case — pick the provider and paste a key.

1. Click Add Credentials. The dialog opens with a Model Provider searchable picker at the top; everything else is disabled until you make a selection.
2. Pick the provider (OpenAI, Anthropic, Azure OpenAI, etc.). The Name field auto-fills with a sensible default (you can edit it), the Base URL populates with the catalog default, and provider-specific fields appear (for example Azure’s endpoint_mode and api_version).
3. Paste the API key.
4. Save. The key is stored in Barndoor’s encrypted secret store and is never returned to the browser.

Multiple providers can reference the same saved credential — useful for sharing one OpenAI key across several routes, or pinning a specific provider per team via Model Routes.

AWS Bedrock
Bedrock supports three authentication methods. IAM role federation is the recommended production setup; the others are useful for pilots or environments that can’t grant cross-account roles.

Fields common to every method:

• AWS Region — where Barndoor sends Bedrock Runtime requests (free text, e.g. us-east-1). Make sure the models you want are enabled in that region in AWS.
• Bedrock API Family — pick Claude / Anthropic Messages for Claude models on Bedrock, or Bedrock Converse for the broader Converse-API model set (Llama, Titan, etc.).

Setting up IAM Role federation

The Providers tab walks you through this end-to-end with a Bedrock setup checklist — recommended for first-time setup.

1. Open Providers → Add Provider → AWS Bedrock → Connect.
2. Fill in AWS Region, Customer IAM Role ARN, and Bedrock API Family. Barndoor auto-generates an External ID and shows you its own Barndoor Principal ARN for this environment in the same dialog.
3. Click Copy trust policy — Barndoor builds the JSON template for you, pre-filled with its principal ARN and your external ID.
4. In AWS IAM, create (or update) the role you named in step 2 and paste the copied trust policy into its trust relationship.
5. Grant the role permission to invoke Bedrock — at minimum bedrock:InvokeModel and bedrock:InvokeModelWithResponseStream. (The AWS-managed AmazonBedrockReadOnly-style policies do not include these actions.) For a POC, Resource: "*" is fine; for production, narrow Resource to the specific Bedrock model ARNs / inference profiles and regions your team actually routes to.
6. Back in Barndoor, click Validate role access. The portal attempts the exact STS assume-role chain it uses at runtime and surfaces the AWS error verbatim if something’s off — iterate on the trust policy / role permissions until it validates.
7. Click Save. The credentials are stored and the AWS Trust Info dialog opens; you can reopen it anytime from the credential’s row menu to recheck the principal or external ID.

Setting up Static AWS Keys

Paste the AWS Access Key ID, AWS Secret Access Key, and an optional AWS Session Token (if you’re using temporary credentials). Region and Bedrock API Family work the same as the role flow. There’s no Validate button for this mode — failures show up on the first real request.

Setting up a Bedrock API Key

Paste the Bedrock API Key issued by the AWS Bedrock console. Region and Bedrock API Family work the same as above.

If you want to expose Bedrock from multiple regions or model families, create one Provider per (region, family) combination and let Model Routes decide which alias points where.

Google Vertex AI

Vertex supports three authentication methods. Pick the one that matches your GCP posture:

Fields common to every method:

• GCP Project ID — your project.
• Vertex AI Location — region (default us-central1).
• Vertex API Family — Gemini Generate Content for Gemini models, or Claude / Anthropic Messages for Claude on Vertex.

Setup steps

1. In the portal, pick the auth method and fill in the fields.
2. In your GCP project, enable the Vertex AI API and any partner-model access (e.g. Claude on Vertex requires explicit model enablement).
3. Grant roles/aiplatform.user (or a more specific Vertex role) on the project to whichever principal will actually call Vertex — Barndoor’s runtime identity (Workload Identity / ADC), your target service account (impersonation), or the key’s service account.
4. For Service Account Impersonation only: grant roles/iam.serviceAccountTokenCreator on your target service account to Barndoor’s runtime principal.
5. Click Validate Vertex Access. Barndoor fetches a token via your chosen auth method and asks Vertex about a model in your chosen API family — confirming end-to-end that both auth and model access work.

The Service Account Key dialog asks for the email and private key as separate fields (the two values inside a downloaded JSON key file), plus an optional Token URI. Paste them into the form fields — raw JSON file upload is not supported.

Streaming on Vertex Gemini is not yet supported by the gateway — Gemini Generate Content responses come back non-streaming. Streaming on Claude on Vertex (Claude / Anthropic Messages family) works normally.

Anthropic OAuth passthrough (Claude Code subscribers)

Use this mode when your developers use Claude Code with personal or subscription Claude accounts and you want each request to bill against that user’s Anthropic subscription rather than a shared API key. Instead of storing a Claude API key, Barndoor authenticates itself with the standard bd-… gateway API key and forwards each caller’s Claude OAuth token (sk-ant-oat…) to Anthropic on the upstream request.

Anthropic OAuth passthrough is configured on the Providers tab, not Credentials — there’s nothing to save in Credentials.

What callers send

Every request carries two headers:

Claude Code emits both automatically — see the Claude Code accordion under Connect Your Tools for the exact env-var setup.

Smoke-test with curl

To verify the dual-header path end-to-end without Claude Code:

export BARNDOOR_LLM_GATEWAY_ENDPOINT="https://app.barndoor.ai/api/llm-gateway/v1"
export BD_API_KEY="bd-…"
export CLAUDE_OAUTH="sk-ant-oat…"   # from your local Claude login

curl -i "$BARNDOOR_LLM_GATEWAY_ENDPOINT/messages" \
  -H "content-type: application/json" \
  -H "x-api-key: $BD_API_KEY" \
  -H "authorization: Bearer $CLAUDE_OAUTH" \
  -d '{
    "model": "claude-opus-4-8",
    "max_tokens": 32,
    "messages": [{"role": "user", "content": "Say pong."}]
  }'

A 200 with a normal Anthropic response body confirms both headers flowed correctly. A 401 typically means one of the two headers is missing or malformed.

Limitations to know about

• Endpoint scope: OAuth tokens are forwarded only on POST /v1/messages (and Claude Code’s pre-flight /v1/messages/count_tokens). Hitting /v1/chat/completions against an Anthropic OAuth provider returns 401 with a message asking the caller to use the Messages endpoint.
• Token management: Barndoor never stores or refreshes Claude OAuth tokens. Token expiry and refresh are handled entirely by Claude Code on the caller’s machine.
• Failover: Missing-OAuth-token errors are treated as caller errors (401), not upstream failures, so they don’t trigger failover to other routes for the same alias.

Pairing OAuth with a fallback (worked example)

A common production setup is to put OAuth passthrough first and an AWS Bedrock provider second on the same alias, so Claude OAuth absorbs everyday traffic and Bedrock takes over if Anthropic is degraded.

1. Create the Anthropic Claude OAuth provider as described above.
2. Create an AWS Bedrock provider.
3. In Model Routes, make a single alias (e.g. claude-opus-4-8) with two entries:
   • Entry 1 — provider: Anthropic Claude OAuth, upstream model: the Anthropic public API model id (e.g. claude-opus-4-8).
   • Entry 2 — provider: AWS Bedrock, upstream model: the Bedrock model id (e.g. us.anthropic.claude-opus-4-8).
4. Callers send requests for claude-opus-4-8. The gateway tries OAuth first, and falls over to Bedrock on a failover-eligible upstream error.

Provider credentials are encrypted at rest and never leave Barndoor in the clear once saved. When you rotate a credential, update it in Barndoor so the gateway picks up the new value on the next request.

Step 2: Create a Provider

A Provider is the named upstream that uses one credential. From the Providers tab, click Add Provider to open the Add a Provider card grid:

1. Filter the catalog with All / Official / Custom at the top. Official is Barndoor’s vetted catalog (OpenAI, Anthropic, AWS Bedrock, Google Vertex, Azure OpenAI, and many more). Custom is for OpenAI-compatible providers you wire up yourself.
2. Click the card for the upstream you want to add — Anthropic shows two cards (the standard API-key path and the Anthropic OAuth path), most others show one. A dialog opens with the catalog defaults pre-filled.
3. Pick the Credentials to use — either an existing saved credential from the dropdown, or Enter API key on this provider to set up an inline credential as part of the save.
4. Give the provider a friendly Name (this is what shows up in audit logs and response observability headers).
5. Optionally override the Base URL.

You can create multiple providers backed by the same vendor.

Step 3: Enable Models

Open the Models tab and toggle on every upstream model your org should be able to call. These are the upstream model identifiers.

Step 4: 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:

• Spending budgets in LLM Controls
• estimated_cost values recorded on every per-request audit event
• Per-team / per-user / per-model attribution in the Reporting → LLM Usage Dashboard

Step 5: 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. It’s where you turn a logical name like gpt-4o-mini into a routing decision.

1. Open Model Routes and click Create Route.
2. Set the Route Name clients will use, e.g. gpt-4o-mini or team-coding-model. This is the name callers put in the model field.
3. Pick a Provider and check one or more of its Provider Models to use as targets. The first target is the primary; the rest are failover targets used if the primary returns a 5xx, network error, or exhausted 429.
4. Configure per-target 429 retry behavior (optional).

Any route you create here is bare-callable — clients can use the bare name (gpt-4o-mini) directly. (Models you merely toggle on in the Models tab without giving them a route are only reachable via the provider-prefixed form, openai/gpt-4o-mini.)

Step 6: Add Governance (optional)

Once routes are live, you’ll likely want to layer on usage policies — token budgets, rate limits, and model access. All of these live under the Controls group of LLM Management (Budgets, Rate Limits, Model Access).

• Token Budgets — daily / weekly / monthly token (and optional spending) caps with alert thresholds.
• Rate Limits — RPM / TPM caps.
• Model Access Policies — allowlist or denylist specific models, providers, or upstream-model combinations.

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

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 (e.g. 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.

Treat bd-… keys like passwords. Use environment variables to store them in your apps and editor configs.

Sending Requests

The gateway speaks two API dialects on the same port:

Both Authorization: Bearer <key> and x-api-key: <key> headers are accepted.

List Available Models

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-…"

Streaming Chat Completion

Set `