Quickstart Guide

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.

• 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

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

​

Setting up a Bedrock API Key

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

​

Setup

1. Providers → Add Provider and pick the Anthropic OAuth card (the second of the two Anthropic catalog cards).
2. Name the provider (e.g. Anthropic via Claude OAuth) and click Save — no API key field appears.
3. Add this provider to a Model Route alongside the Claude models you want to expose (typically claude-sonnet-5, claude-opus-4-8, etc.).

​

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 "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."}]
  }'

​

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)

1. Create the Anthropic Claude OAuth provider as described above.
2. Create an AWS Bedrock provider — see the Bedrock accordion.
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. The response’s model field tells you which route served any given request without inspecting headers.

• Confirm the header is Authorization: Bearer bd-… (with a space after Bearer) or x-api-key: bd-….
• Make sure the key has not been revoked (check Settings → My API Keys or LLM Management → API Keys).
• The gateway only accepts keys created in your organization. Keys from a trial environment will not work against your production environment and vice versa.

• Call GET /v1/models to see exactly which aliases your key can use.
• If you expected to see an alias, verify with an admin that it has at least one enabled route in Model Routes and that the model is toggled on in the Models tab.
• If you’re using a bare name and two providers back it, try the prefixed form (provider/model) instead.

• Model-access denials look like model 'foo' is not allowed for this caller. Check LLM Management → Model Access for the policy that applies to your role/group.

• Barndoor’s rate-limit and token-budget checks can return 429 before the request reaches the upstream provider. The response body explains which limit fired.
• Upstream provider 429s are retried in-place per the route’s retry policy and may eventually fail over. Check the x-bd-provider-retry-count and x-bd-provider-failover-count headers to see what happened.

• Make sure your HTTP client supports SSE and doesn’t buffer (curl -N, requests.post(..., stream=True), fetch(..., { ... }) with manual reader, etc.).
• The gateway will close the stream cleanly with a final [DONE] chunk. A premature close usually means the upstream provider closed first — check the response headers and audit logs for the failover trail.

• The Anthropic SDK appends /v1/messages itself; set the base URL to https://app.barndoor.ai/api/llm-gateway (without /v1).
• Use x-api-key for the Barndoor token. If your client only knows ANTHROPIC_API_KEY, the gateway still accepts it through the same header.

• User keys (Settings → My API Keys) are tied to the calling user. Usage and audit events attribute back to that user.
• Org keys (LLM Management → API Keys) are typically used for service accounts and CI. They have an org scope but no individual user.