Quickstart Guide

1. Click Add Credentials. The dialog opens with a Model Provider picker at the top; the rest of the form is disabled until you pick one.
2. Pick the provider. The Base URL fills in with the catalog default, and any provider-specific fields appear.
3. Give the credentials a Name (for example Production Anthropic Key) — this is how you’ll find them when creating a provider.
4. Paste the API key.
5. Click Create. The key is stored in Barndoor’s encrypted secret store and is never returned to the browser.

​

Setting up an AWS IAM Role

1. Pick AWS IAM Role as the Bedrock Auth Method.
2. Fill in AWS Region and your Customer IAM Role ARN. Barndoor generates an External ID and shows its own Barndoor Principal ARN for this environment in the same dialog.
3. Click Copy trust policy — Barndoor builds the JSON 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 read-only Bedrock policies do not include these actions.) For a proof of concept, Resource: "*" is fine; for production, narrow Resource to the specific Bedrock model ARNs / inference profiles and regions you route to.
6. Back in Barndoor, click Validate role access. The portal attempts the same assume-role chain it uses at runtime and shows the AWS error verbatim if something’s off — adjust the trust policy or role permissions until it validates.
7. Click Create. The AWS Trust Info dialog opens; you can reopen it any time from the credentials’ row menu (AWS trust info) to recheck the principal or external ID.

​

Setting up Static AWS Keys

​

Setting up a Bedrock API Key

• GCP Project ID — your project.
• Vertex AI Location — the region (default us-central1).

​

Setup steps

1. Pick the auth method and fill in the fields.
2. In your GCP project, enable the Vertex AI API and any partner-model access (for example, Claude on Vertex requires explicit model enablement).
3. Grant roles/aiplatform.user (or a narrower Vertex role) on the project to whichever principal actually calls 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 with your chosen method and asks Vertex about a model, confirming that both auth and model access work.

​

Setup

1. Go to Providers → Add Provider and pick the Anthropic OAuth card (one of the two Anthropic cards).
2. Name the provider (for example Anthropic via Claude OAuth). Credentials shows Claude OAuth passthrough — no stored credential, and no API key field appears.
3. Click Create, and enable the Claude models you want to expose.
4. Add those models to a Model Route.

​

What callers send

​

Smoke-test with curl

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 "anthropic-version: 2023-06-01" \
  -H "x-api-key: $BD_API_KEY" \
  -H "authorization: Bearer $CLAUDE_OAUTH" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 32,
    "messages": [{"role": "user", "content": "Say pong."}]
  }'

​

Limitations to know about

• Endpoint scope: the Claude OAuth token is forwarded only on POST /v1/messages. A request that reaches an Anthropic OAuth provider through any other endpoint — for example /v1/chat/completions — fails with 401 and the message Anthropic provider requires an incoming Claude OAuth bearer token. (/v1/messages/count_tokens is answered by the gateway itself and never reaches Anthropic.)
• Token management: Barndoor never stores or refreshes Claude OAuth tokens. Expiry and refresh are handled by Claude Code on the developer’s machine.
• A missing token doesn’t fail over. It’s treated as a caller error (401), not an upstream failure, so the gateway doesn’t move on to the route’s other targets.

​

Pairing OAuth with a fallback

• Confirm the header is Authorization: Bearer bd-… (with a space after Bearer) or x-api-key: bd-….
• Make sure the key hasn’t been revoked or disabled (check Settings → My Models → API Keys or LLM Management → API Keys).
• Keys only work in the organization and environment they were created in. A key from a trial environment won’t work against production, and vice versa.
• A 401 that names a provider (for example Anthropic provider requires an incoming Claude OAuth bearer token) is about the upstream side — see the OAuth passthrough limitations in Step 1.

• Call GET /v1/models to see exactly which names your key can use.
• If you expected a name to be there, check with an admin that the route exists in Model Routes with at least one enabled target, and that the model is enabled on its provider.
• model '…' not found for provider '…' means a provider-prefixed name didn’t match. The part after / must be an upstream model enabled on that provider — not a route name. Call a route by its plain name.

• Model access denials read Model '…' is not allowed by access policy. Check LLM Management → Model Access for the policy that applies to the key’s user, group, or role. See Configuring LLM Controls.

• Barndoor’s rate limits (type: rate_limit_error, with a Retry-After header) and budgets (type: budget_exhausted) can return 429 before the request reaches any provider. The message says which limit fired.
• Upstream 429s are retried per the route’s retry settings and may then fail over. Check the x-bd-provider-retry-count and x-bd-provider-failover-count headers to see what happened.

• When every target on a route fails, the message lists the providers tried and the last failure, and error.metadata.attempts has the detail for each attempt. The status matches the upstream failure where they all agree (for example 401 if every provider rejected its credentials), 429 if every attempt was rate limited, and 502 otherwise.
• An attempt that timed out has a code starting with upstream_timeout_ (for example upstream_timeout_first_byte when a streaming request got no response within 60 seconds).
• Check the providers’ status pills in Providers — see Provider health.

• Gemini on Google Vertex AI doesn’t support streaming, tool calls, or structured response_format through the gateway yet. Send a non-streaming request, or route to a Google AI (Gemini) provider or a Claude model instead.

• Make sure your HTTP client supports SSE and doesn’t buffer (curl -N, requests.post(..., stream=True), fetch with a manual reader, and so on).
• A premature close usually means the upstream provider closed first. Check the failover headers and the LLM Usage Dashboard for that request.

• The Anthropic SDK appends /v1/messages itself: set its base URL to https://app.barndoor.ai/api/llm-gateway (without /v1). Both forms are on the Gateway Endpoint card.
• Send the Barndoor key in x-api-key. If your client only knows ANTHROPIC_API_KEY, set that to your bd-… key — it’s sent in the same header.

• User keys (Settings → My Models → API Keys, or an admin key assigned to a user) are tied to one user. Usage and policies attribute to that user.
• Group keys (assigned to a group in LLM Management → API Keys) share that group’s budgets, rate limits, and model access.
• Org keys (no user or group) are typically used for services and CI. They have an organization scope but no individual user.