LLM Proxy Authentication

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.
• 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.
• 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.

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 still works, but the logs cannot name you.

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 pick LLM Proxy under What will it reach?. Then pick how it signs in:

Call as the App

For a bot or a nightly job with no person behind it.

1. Pick As itself, then a provider key for each provider.

2. On Budget, pick the team that pays for it. This is optional.

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.

• The billing team's costs and limits count the client's spend. A spend cap on Budget limits the client itself.
• Map a metered API key. A personal subscription cannot serve an app.
• See the complete example app.

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, and add your app's redirect URIs. Each person pays for their own use. A spend cap on Budget 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.

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.