> ## Documentation Index
> Fetch the complete documentation index at: https://docs.barndoor.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get the most out of your Claude subscription

> Run Claude Code on your Claude subscription through the Barndoor LLM Gateway and keep working past your rate limit with automatic failover, so each developer gets the full value of the seat you pay for.

A Claude subscription is a flat per-seat price, which makes it far cheaper per
token than the API for heavy coding. The catch is the rate limit: hit your cap
mid-task and you are blocked until the window resets.

The Barndoor LLM Gateway lets each developer run Claude Code on **their own**
subscription as the primary path, and automatically spill to a cheaper fallback
model the moment they hit the cap. The seat you already pay for does the bulk of
the work, the session never stalls on a rate limit, and you pay marginal cost
only on the overflow. That is the full value of the subscription without the
leash: cheap-flat economics as your floor, graceful overflow on top.

### How it works

<Steps>
  <Step title="Request enters the gateway">
    Claude Code talks to the gateway using the Anthropic Messages API. Your Claude
    subscription token is forwarded through to Anthropic (OAuth passthrough), so
    the request is served on your subscription.
  </Step>

  <Step title="Primary target is tried first">
    The gateway resolves the model to a route. The highest-priority target is your
    Claude subscription.
  </Step>

  <Step title="Failover on a cap">
    If Anthropic returns a rate-limit error (HTTP 429), the gateway reroutes the
    same request to the next target in the route, such as an open model, with no
    action from the developer. The response comes back on the fallback and the
    session continues.
  </Step>
</Steps>

### Prerequisites

<Note>
  You need a Barndoor account with admin privileges, the LLM Gateway enabled for
  your organization, and an active Claude subscription for the developer using it.
</Note>

### 1. Configure the providers

In the Barndoor web UI, go to **Admin** > **LLM Management** > **Providers**.

1. Add an **Anthropic** provider and choose the **Claude OAuth** auth method. This
   is the passthrough provider: it stores no API key and forwards the caller's
   subscription token.
2. Add a **fallback** provider for the model you want to overflow to (for example
   an open model on a cloud you already use). Give it whatever credentials that
   provider needs.

### 2. Create a route with failover

Go to **Model Routes** and create a route under a single model name (the alias
Claude Code will target). Add two targets, in priority order:

| Priority    | Target                   | Purpose                                        |
| :---------- | :----------------------- | :--------------------------------------------- |
| 1 (highest) | Anthropic (Claude OAuth) | Primary, served on your subscription           |
| 2           | Fallback provider        | Overflow when the subscription is rate-limited |

<img src="https://mintcdn.com/barndoor/FOxx1F5NIxLmngoh/images/llm-gateway-failover-route.png?fit=max&auto=format&n=FOxx1F5NIxLmngoh&q=85&s=c401abc5db1ae381378aa47bbf79e04d" alt="A model route with two priority-ordered targets, a primary and a fallback" width="1600" height="419" data-path="images/llm-gateway-failover-route.png" />

<Note>
  Targets are tried top to bottom. Set the primary's **retry-on-429** count if you
  want the gateway to briefly retry the subscription before spilling; leave it at 0
  to fail over immediately.
</Note>

### 3. Create a gateway API key

Go to **API Keys** and create a key. This authenticates Claude Code *to the
gateway*; it is separate from your Claude subscription token, which the gateway
forwards to Anthropic.

### 4. Point Claude Code at the gateway

Stay logged into Claude Code with your Claude subscription so it sends its OAuth
token, then set these environment variables and launch `claude`:

<CodeGroup>
  ```bash Environment theme={null}
  # Do NOT set ANTHROPIC_API_KEY — that switches Claude Code to API-key mode
  unset ANTHROPIC_API_KEY

  export ANTHROPIC_BASE_URL="https://<your-gateway-host>/api/llm-gateway"
  export ANTHROPIC_CUSTOM_HEADERS="x-api-key: <your-gateway-api-key>"

  # Point Claude Code's models at your route's alias.
  # (The ANTHROPIC_DEFAULT_*_MODEL variables don't work here — they only apply
  # to provider configs like Bedrock/Vertex, not ANTHROPIC_BASE_URL gateways.)
  export ANTHROPIC_MODEL="<your-route-alias>"
  export ANTHROPIC_SMALL_FAST_MODEL="<your-route-alias>"
  ```
</CodeGroup>

The split is the key detail: the **`x-api-key`** header authenticates you to the
gateway, while Claude Code's **`Authorization: Bearer`** subscription token is
what the gateway forwards to Anthropic.

### 5. Verify

Run a normal Claude Code request. It should complete on your subscription. To see
the failover, drive the seat until Anthropic rate-limits it: the gateway logs the
429 and reroutes to the fallback, and the request still returns a completion.

<Warning>
  Subscription terms. Provider subscriptions are intended for individual,
  interactive use. Route each developer's own seat and keep usage interactive.
  Pooling seats behind a shared gateway, or driving them as shared automated
  capacity, may violate the provider's terms of service. Review your model
  provider's terms before enabling this pattern, especially at scale.
</Warning>