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

# Claude on TrueFoundry: FAQ

> Answers to the most common questions about running Claude Code, Claude Desktop, and claude.ai through the AI Gateway: billing, auth, errors, governance.

These are the billing and authentication questions that come up most often in support tickets and onboarding calls. Configuration questions live on each interface's page: [Claude Code](/docs/ai-gateway/claude-code#faqs), [Claude Desktop](/docs/ai-gateway/claude-desktop#faqs), and [Claude Web](/docs/ai-gateway/claude-web#faqs).

## Billing and plans

<AccordionGroup>
  <Accordion title="Does routing Claude through the gateway use our Claude Enterprise or Team seats, or create a separate API bill?">
    It depends on which credential reaches Anthropic, and that is decided by the model account on the gateway:

    * **Model account has an Anthropic API key** → every request is billed per token to that key. The user's seat is not involved. This is the only option for Claude Desktop / Cowork, and one of two options for Claude Code.
    * **Model account has no API key** (subscription passthrough) → the gateway forwards the user's own Claude login token, and usage draws from their seat or subscription. Only Claude Code can do this, because it is the only client with a Claude login flow.

    Whether per-token spend on a key issued from your Enterprise organization counts toward your Enterprise contract is a commercial question for your Anthropic account team; the gateway doesn't change it. See the [overview](/docs/ai-gateway/claude-code#authentication-and-who-pays) for the side-by-side.
  </Accordion>

  <Accordion title="We're on Pro, Max, or Team. Can Claude Code use our subscription through the gateway?">
    Yes. Create the Anthropic model account with the API key left empty, leave `ANTHROPIC_AUTH_TOKEN` unset, and put your TrueFoundry key in `ANTHROPIC_CUSTOM_HEADERS` as `x-tfy-api-key`. The user signs in with their Claude account when Claude Code starts; the gateway authenticates them with the TrueFoundry key and forwards their Claude token to Anthropic. Usage draws from the subscription, and the gateway still records every request per user.

    Setup is under [Authentication and who pays](/docs/ai-gateway/claude-code#authentication-and-who-pays).
  </Accordion>

  <Accordion title="Does Claude Desktop / Cowork in third-party mode use the user's seat?">
    No. In third-party inference mode the app never signs in to claude.ai. The "Gateway API key" field takes a TrueFoundry token, inference goes through the gateway's model account, and Anthropic bills that account's API key per token. The seat's usage allowance is never consumed by anything that happens inside Desktop.

    Two consequences worth planning around: a user who only uses Desktop through the gateway doesn't need a Claude seat at all, and a user who has a seat for claude.ai or Claude Code pays for that seat plus per-token Desktop usage, with no overlap between the two. If you want seats to pay for Desktop, keep Desktop first-party and govern it with [Anthropic Inference Hooks](/docs/ai-gateway/anthropic-inference-hooks) instead, accepting that the gateway then has no cost visibility. See [Claude Desktop](/docs/ai-gateway/claude-desktop).
  </Accordion>

  <Accordion title="What happens when a subscription user hits their rate limit mid-session?">
    Requests start failing. To avoid that, route Claude Code through a virtual model with the subscription (empty-key) account at priority `0` and a pay-per-token Anthropic account as the fallback. The gateway uses the subscription until it is rate-limited, then routes overflow to the API key. Only one target in a virtual model can be a passthrough account, since there is only one `Authorization` header to forward.

    Steps are under [Fall back from the subscription to the Anthropic API](/docs/ai-gateway/claude-code#fall-back-from-the-subscription-to-the-anthropic-api).
  </Accordion>

  <Accordion title="Is the cost shown in Analytics a bill?">
    No. The gateway counts the tokens in each request and multiplies by the model's list price so you can attribute spend to users and teams, enforce budgets, and watch trends. TrueFoundry does not charge for tokens. The only token bill is Anthropic's (or your cloud provider's), by whichever route the credential took. On subscription passthrough the Analytics figure is an estimate of what the usage would cost at API rates; the seat is flat, so nobody is invoiced that amount.
  </Accordion>

  <Accordion title="Can Claude apps use Bedrock, Vertex, or Microsoft Foundry instead of Anthropic directly?">
    Yes. The model account then holds your cloud credentials, the gateway always calls the provider with those, and usage is billed per token to your cloud account. Claude plans and subscription passthrough don't apply; every interface is API-key mode.

    The trade-off is fidelity. On Anthropic direct, `anthropic-beta` headers and new request fields pass through unfiltered. On other providers the gateway checks each beta against a per-provider allowlist and drops the rest, Anthropic's server-side tools (built-in web search) don't run, and model ids differ. Claude Code and Desktop work, but some of their newest features arrive later or not at all. See [Forwarding Anthropic beta features](/docs/ai-gateway/claude-code#forwarding-anthropic-beta-features).
  </Accordion>
</AccordionGroup>

## Authentication and identity

<AccordionGroup>
  <Accordion title="How does the gateway know which user a request came from?">
    From the TrueFoundry credential on the request, sent either as `Authorization: Bearer <token>` or in the `x-tfy-api-key` header. The gateway recognises three kinds: tokens it issued (Personal Access Tokens, Virtual Account tokens, and the short-lived tokens `tfy-local-ai-setup` mints from a device login), JWTs from an [identity provider](/docs/platform/identity-providers) you have registered, and, in SWG mode, an `X-Authenticated-User` assertion from a trusted upstream proxy.

    The identity is as good as the token. One Personal Access Token pasted into a shared `managed-settings.json` makes the whole fleet look like one user. The MDM binary mints a separate token per user from their own SSO login, which is what gives per-user attribution at scale. See [Enforce with MDM](/docs/ai-gateway/claude-mdm).
  </Accordion>

  <Accordion title="Why does the Claude Code config sometimes have the key in ANTHROPIC_AUTH_TOKEN and sometimes in x-tfy-api-key?">
    Because two different credentials may need to travel on the same request. `ANTHROPIC_AUTH_TOKEN` becomes the `Authorization` header. In API-key mode that header carries your TrueFoundry key and nothing else is needed. On subscription passthrough Claude Code reserves `Authorization` for the user's Claude login token, so the TrueFoundry key moves to `x-tfy-api-key` in `ANTHROPIC_CUSTOM_HEADERS`. The gateway checks both locations.
  </Accordion>

  <Accordion title="When does the gateway forward the client's Authorization header to Anthropic?">
    Only when the model account has no API key. If a key is stored, the gateway authenticates the inbound request, then builds its own outbound request with the stored key; the client's `Authorization` header never leaves the gateway. If no key is stored, the gateway forwards the inbound `Authorization` header to Anthropic as-is.

    So "empty API key" is an instruction to pass the client's bearer through. It only works when that bearer is a real Anthropic token, which today means Claude Code after `/login`. Point Claude Desktop at an empty-key account and Anthropic receives a TrueFoundry token and returns `401 Invalid bearer token`.
  </Accordion>

  <Accordion title="If MDM pushes the Desktop config, can we still track cost per user?">
    Yes. The thing that is shared is the Anthropic API key, and it lives on the gateway's model account, never on devices. What MDM pushes is the TrueFoundry credential, and `tfy-local-ai-setup --claude-desktop` mints that per user: it runs the device login as the signed-in user, writes that user's token into the per-user managed preferences, locks the file, and refreshes it on every run. Each Desktop request then carries that user's identity and appears under their name in Analytics, exactly as Claude Code does. See [Claude Desktop → MDM](/docs/ai-gateway/claude-desktop#enforce-fleet-wide-via-mdm-managed-preferences).
  </Accordion>

  <Accordion title="Can the gateway authenticate users with their Claude login token instead of a TrueFoundry token?">
    No. Anthropic tokens are opaque to TrueFoundry; there is no way to validate one or learn who it belongs to, and on passthrough the gateway forwards it without reading it. Every request needs a credential the gateway can verify, which is why passthrough sends both tokens. If you want to avoid minting TrueFoundry tokens, register your IdP and have clients send its JWTs; the gateway validates those directly. See [Identity providers](/docs/platform/identity-providers).
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.