Architecture | Optional module: Claude Code and Desktop through a Foundry AI gateway

Chapter 2 of 6

Architecture at a glance#

Claude Code obtains an Entra access token through an Azure CLI helper. Desktop signs in through the browser with authorization code and PKCE, then sends an Entra ID token. Both clients call the same HTTPS gateway base URL.

Claude Code / Claude Desktop
  -> optional Application Gateway WAF
  -> APIM: validate client -> resolve budget -> enforce token quota
  -> Foundry /anthropic/v1/messages, authenticated with APIM managed identity

Entra authenticates the user. APIM validates the issued token against the exact tenant and application, requires Gateway.Invoke, and uses normalized upn plus model as the monthly counter key. The policy removes client key headers and replaces Authorization before forwarding to Foundry.

The backend is https://<foundry-resource>.services.ai.azure.com/anthropic. If the APIM API suffix is foundry, both clients use https://<gateway-hostname>/foundry. APIM removes its API suffix when it builds the backend path, so /foundry/v1/messages reaches /anthropic/v1/messages. Application Gateway, when used, must preserve that mapping and the query string.

Design choices and tradeoffs#

Decision	Chosen approach	Benefits	Costs and limitations
Protocol	Native Anthropic Messages passthrough	Preserves tools, beta fields, and streaming	OpenAI-compatible import is a different protocol
Caller tokens	Separate Code access-token and Desktop ID-token validators	Each audience has its own claim contract	Desktop ID-token acceptance is specific to this documented gateway integration
Backend identity	APIM managed identity	No provider keys on developer devices	APIM acts as a shared principal; Foundry does not authorize the end user
Budgets	API-included fragment with defaults and UPN overrides	Applies without relying on product policy selection	UPN changes can create a new balance; counters are gateway-local
Network	Existing approved path, optional WAF	Avoids deploying a second gateway just for this module	Public APIM must be restricted if WAF is the approved sole entry point

The token policy limits prompt and completion usage. Streaming counts are estimated, and concurrent calls can exceed a quota before their responses are processed. A token quota is not a hard currency budget. Cache-related usage and billed Claude Consumption Units need separate cost reconciliation.

Architecture guidance#

Deploy Claude models in Foundry defines the hosting choices, deployment names, endpoint, and Entra authentication.
APIM token limits explains Anthropic support on v2 tiers and counter limits.
APIM subscriptions and policy context explains why these budgets are included at API scope.