LLM Proxy Authentication

Every call to the proxy carries an Archestra credential, so each request in the logs names an app or a person. A call with only a provider key is rejected.

First, add your provider keys on Model Providers. They stay in Archestra. Then pick how each app or person signs in to the proxy, by what your client supports:

Standard Virtual Keys

Give each app its own key. To cut off one app, delete its key. Other apps keep working.

1. Go to LLM Proxy and click Create standard virtual key.

2. Name it. Every provider starts with its primary key. Change a key or remove a provider if the app needs less.

3. Optionally pick who pays for it, who can access it, and when it expires. Then create it.

4. Copy the key. It shows only once. The dialog then shows a request with your key filled in.

5. Use the key wherever the app expects a provider API key:

   bash

   curl "https://<archestra-host>/v1/openai/chat/completions" \
     -H "Authorization: Bearer $ARCHESTRA_VIRTUAL_KEY" \
     -H "Content-Type: application/json" \
     -d '{"model":"gpt-5.4","messages":[{"role":"user","content":"Hello"}]}'
   

The request shows under Logs → LLM Proxy, with the key's name.

• With Selected providers, the key needs a mapping for the route's provider. An OpenAI route needs an OpenAI key. On the Model Router, the model's prefix picks the mapping.
• The key also works on provider endpoints Archestra forwards unchanged, such as /v1/openai/moderations. Archestra adds the provider key the virtual key maps to, so the app never holds one. A provider key that has its own Base URL is not forwarded. Each forwarded call appears under Logs → LLM Proxy with its endpoint path. Moderation and token-count calls record $0; other forwarded calls record no cost, because the provider reports none. Under a hard spend limit, only listings, uploads, cancellations, token counts, and OpenAI moderations are forwarded. Other forwarded calls, such as creating a batch, return 422.
• Self-hosted providers can map several endpoints. Archestra sends each request to the endpoint that serves the model. You can edit a virtual key to add providers or endpoints without changing its token.
• Choose Current and future providers to automatically use each provider's shared Primary API key, including providers added later. Personal and subscription keys are excluded. You can optionally select a different key for an existing provider. Connect settings apply this option to newly issued keys.
• After you confirm, deleting a provider key or disconnecting a subscription also deletes the virtual keys and OAuth clients that map only that key. A key or client that also maps other providers keeps those. Knowledge base settings that used the key are cleared.
• To share a key with a team, add the team under its permissions, when you create the key or later.
• To bill a team, pick it as the payer. The key's spend then counts toward that team's costs and limits, not its creator's. A spend cap there limits the key itself.
• A key reaches a model pool when it maps one of the pool's members. To give it a pool without mapping a member, add the pool under Model pools.

Passthrough Virtual Keys

Use your own subscription or key, and still show up in costs and logs. Claude Code on a Claude subscription is the common case.

Connect sets this up for Claude Code, Claude Desktop, Codex, OpenCode, and Kilo Code. For any other client:

1. Go to LLM Proxy and click Create passthrough virtual key. Copy the key.

2. Send it in X-Archestra-Virtual-Key, next to the provider's own credential:

   bash

   curl "https://<archestra-host>/v1/openai/chat/completions" \
     -H "Authorization: Bearer $OPENAI_API_KEY" \
     -H "X-Archestra-Virtual-Key: $ARCHESTRA_PASSTHROUGH_KEY" \
     -H "Content-Type: application/json" \
     -d '{"model":"gpt-5.4","messages":[{"role":"user","content":"Hello"}]}'
   

• The passthrough key only says who you are. It gives no access to Archestra's provider keys.
• It belongs to one person.
• Without it, the call is rejected with 401. A provider key alone is not accepted. See Allow Requests Without a Virtual Key.

OAuth Clients

Use OAuth when your app should get short-lived tokens, not a key that never expires.

Go to Settings → OAuth Clients → Create OAuth Client, and select LLM Proxy under What can it access?. Select MCP Gateway or A2A as well if the application also needs tools or agents. One client ID and secret covers the selected APIs. Then pick how it signs in:

Call as the App

For a bot or a nightly job with no person behind it. Select Service account (optional) under Access → Advanced to use that account’s permissions and attribute LLM spend to it. Enable MCP Gateway or A2A on the same client for shared A2A run ownership.

1. Pick As itself. On Access, choose Selected providers to fix the allowed providers and keys, or Current and future providers to follow shared Primary keys automatically. If you enabled tools or agents, select their gateways and agents too.

2. Under Advanced → Budget on the same step, optionally pick the team that pays for it or set a spend cap.

3. Save the client ID and secret. The secret shows only once.

4. Get a token. It lasts one hour.

   bash

   curl --request POST "https://<archestra-host>/api/auth/oauth2/token" \
     --data-urlencode 'grant_type=client_credentials' \
     --data-urlencode "client_id=$CLIENT_ID" \
     --data-urlencode "client_secret=$CLIENT_SECRET" \
     --data-urlencode 'scope=llm:proxy'
   

5. Send Authorization: Bearer <access_token> on a provider route or the Model Router.

• When editing a client, use Access to change capabilities and provider keys, and Budget to change its payer or spend cap.
• The billing team's costs and limits count the client's spend. A spend cap limits the client itself.
• Current and future providers uses shared Primary keys at request time, including later providers and changes to the Primary key. Personal and subscription keys are excluded. Under LLM API keys, you can override the key for a provider. Enabling this mode requires a Can use grant on all current and future provider keys (*); access to each current key separately is insufficient.
• Existing OAuth clients keep Selected providers until you change their mode.
• To let the client use a model pool without mapping one of its members, add the pool under Model pools on Access.
• Map a metered API key. A personal subscription cannot serve an app.
• See the complete example app.

For a combined client, request a space-separated subset such as scope=llm:proxy mcp. See token scopes for scope selection and changes to an existing client.

Call for a Person

For an app where people sign in. Each call uses that person's provider keys, cost limits, and policies.

1. Pick For its users. On Access, add your app's redirect URIs. Each person pays for their own use. An optional spend cap limits the whole client.
2. In your app, run the authorization code flow with PKCE. Ask for scope=llm:proxy. Add offline_access to get a refresh token.
3. Send the person's access token on a provider route or the Model Router.

• A public app can register itself, with no secret. To allow only clients you register, set ARCHESTRA_AUTH_DCR_ENABLED=false.
• Set how long tokens last under Settings → Auth → OAuth token lifetime.
• See the complete example app.

Identity Provider JWT

Already signed in to Okta or Entra ID? Send that token. Each call uses that person's provider keys. Identity providers are an Enterprise feature. See Pricing Model.

1. Add your OIDC provider under Settings → Identity Providers.
2. On LLM Proxy, under Identity provider, pick it. You need llmProxy:update.
3. Send the JWT as Authorization: Bearer on a provider route. The Model Router does not take it.

Archestra checks the signature and issuer, then matches the email claim to an Archestra user. If either fails, the request is rejected.

Allow Requests Without a Virtual Key

Keep this off unless a client cannot send any Archestra credential. When it is on, a call with only a provider key, or no key, reaches the provider.

Turn on Allow requests without a virtual key under Settings → LLM. You need organizationSettings:update.

• These calls are not tied to a person, so per-person limits and attribution do not apply.
• A self-hosted provider with no key of its own, such as Ollama or vLLM, becomes open to anyone who can reach the proxy.
• Providers whose credentials Archestra holds, such as Vertex AI or Bedrock with IAM, still need an Archestra credential.

What to Know

• Logs name a person only for a personal virtual key, a passthrough key, user OAuth, or an identity provider JWT. A shared key names the key, and an app's token names the app. Give each budget its own credential.
• Which provider key a call uses and per-key Base URL settings are on Model Providers.