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, and map the provider keys it may use. Set Expires if the app is temporary.

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

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

• 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.
• To share a key with a team, open its Permissions tab.

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, and OpenCode. 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 this client access?. Then pick a grant type:

Call as the App

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

1. Pick Application as the Grant type, and map the provider keys.

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

3. 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'
   

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

• 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 On behalf of users as the Grant type, and add your app's redirect URIs.
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 Licensing.

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.