CLI Setup for Developers

You’ve been granted access by your FoundryGate admin. This guide connects Claude Code or Codex CLI to the gateway using each tool’s official Azure/Foundry support — no wrappers, no proxies on your machine.

What you need

From the “Configure your AI CLI” panel on your FoundryGate /me page:

• Your APIM subscription key
• Your gateway URL (e.g. https://ai.yourcompany.com)
• The model aliases your tier allows (e.g. sonnet, haiku, gpt)

Note

If you don’t see a key on /me, ask your admin to provision one for your account.

Put the alias in `model`, not the deployment name

The gateway’s per-tier alias map is also its allowlist: sonnet, haiku, gpt and friends are the names it accepts in model / ANTHROPIC_DEFAULT_*_MODEL, and anything else — including the underlying Foundry deployment name — is refused with 403 model_not_permitted (infra/main.bicep, productModelAliases). Aliases also let an admin rotate the deployment underneath you without you editing a single env var. /me lists the aliases you have, and the deployment each one currently resolves to for reference.

---

Verify your key

The gateway exposes two API paths — Anthropic-format for Claude models, OpenAI-format for GPT/Codex models. Smoke-test whichever you’ll use:

# Claude path (Anthropic Messages API) — note: x-api-key, matching what
# Claude Code itself sends in Foundry mode (verified by wire capture)
curl https://<gateway-url>/anthropic/v1/messages \
  -H "x-api-key: <your-key>" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"<claude-alias>","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

# OpenAI path (Responses API)
curl https://<gateway-url>/openai/v1/responses \
  -H "api-key: <your-key>" \
  -H "content-type: application/json" \
  -d '{"model":"<openai-alias>","input":"ping"}'

Expected: a JSON response containing generated content. A 401 means the key is wrong or your account is deactivated; a 403 means either your monthly token budget is spent (see Manage your quota) or the model you asked for isn’t in your tier’s alias map (model_not_permitted — check the alias list on /me); a 429 means you’re over your per-minute rate — wait and retry.

---

Configure your tool

Claude Code

Claude Code has first-class Microsoft Foundry support. Set these environment variables (shell profile, or .claude/settings.json env block):

export CLAUDE_CODE_USE_FOUNDRY=1
export ANTHROPIC_FOUNDRY_BASE_URL=https://<gateway-url>/anthropic
export ANTHROPIC_FOUNDRY_API_KEY=<your-key>

# Pin models to your gateway's aliases (shown on /me).
# Pinning matters: unpinned names resolve to Anthropic's defaults, which
# are not in your tier's alias map and come back 403 model_not_permitted.
export ANTHROPIC_DEFAULT_SONNET_MODEL=<sonnet-alias>
export ANTHROPIC_DEFAULT_OPUS_MODEL=<opus-alias>
export ANTHROPIC_DEFAULT_HAIKU_MODEL=<haiku-alias>

Then run claude as normal. Prompt caching is enabled automatically — and cache reads don’t count against the platform’s input-token rate limits, so long sessions are cheaper than they look.

Codex CLI

Codex CLI supports Azure endpoints via ~/.codex/config.toml:

model = "<openai-alias>"     # e.g. gpt — the gateway ALIAS, not the deployment name
model_provider = "azure"

[model_providers.azure]
name = "Azure via FoundryGate"
base_url = "https://<gateway-url>/openai/v1"
wire_api = "responses"
# REQUIRED: send the key as the api-key header. env_key alone sends
# "Authorization: Bearer", which the gateway rejects with 401 (verified live).
env_http_headers = { "api-key" = "FOUNDRYGATE_API_KEY" }

Then export the key the config references:

export FOUNDRYGATE_API_KEY=<your-key>

Codex authenticates with the API key only (it has no Entra ID support), so keep the key in your shell profile or a secret manager — never in the config file itself.

curl / SDKs

Any client that speaks the Anthropic Messages API or the OpenAI Responses/Chat Completions API works. The key facts:

	Claude models	GPT / Codex models
Base path	https://<gateway-url>/anthropic	https://<gateway-url>/openai/v1
API shape	Anthropic Messages (/v1/messages)	OpenAI Responses / Chat Completions
Auth header	x-api-key: <your-key>	api-key: <your-key>
Extra header	anthropic-version: 2023-06-01	—
model field	Claude alias from /me	OpenAI alias from /me

Anthropic’s Foundry SDKs (anthropic Python with AnthropicFoundry, @anthropic-ai/foundry-sdk, Anthropic.Foundry for .NET) accept a base URL and API key and work unchanged against the gateway.

---

Understand your limits

Every response from the gateway carries live budget headers:

Header	Meaning
x-fg-remaining-quota	Tokens left in your monthly budget (estimate; tightens as you approach the limit)
x-fg-remaining-tpm	Tokens left in your current per-minute window
retry-after	Present on 429 — seconds to wait before retrying

Three distinct “slow down” signals, three different meanings:

• 429 from the gateway — your per-minute cap. Your CLI backs off automatically; no action needed.
• 403 from the gateway — your monthly budget is exhausted. Request an increase (below); no amount of retrying helps until the month resets.
• Elevated latency without errors — the shared deployment may be saturated and the gateway is rerouting your traffic to a backup deployment. Normal during peak hours.

Manage your quota

Your token budget resets at the start of each calendar month (UTC), automatically. You can:

• Check current usage on the /me page (quota gauge shows tokens used / allocated).
• Request a quota increase via the “Request Quota Increase” button on /me.
• Rotate your key from /me if you suspect it’s been compromised.