Home Docs Claude Documentation 22 Oct 2026

One change · claude-docs

Deploy Claude Desktop on 3P with an LLM gateway changedthird-party/claude-desktop/gateway

Nearest release: v2.1.309, published under an hour after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.

Upstream edited this page at 22 Oct 2026 20:16 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 22 Oct 2026 20:37 UTC.

Upstream edited 22 Oct 2026 20:16 UTC

Recorded here 22 Oct 2026 20:37 UTC

Lines+248added

Lines−47removed

From line 164 where the diff opens

First seen 14 Aug 2026 this site's first read of the page

Recorded edits36to this page, all time

#### `inferenceGatewayBaseUrl` #### `inferenceGatewayApiKey` #### `inferenceGatewayAuthScheme` #### `inferenceGatewayOidcAuthFlow` #### `inferenceGatewayOidc` #### `inferenceIdpAuthFlow` #### `inferenceIdpOidc` #### `inferenceStreamIdleTimeoutSec`

The whole hunk

from line 164, old and new numbered

lines

from line 164

164164

165165### Configuration keys

166166

168| - | - | - | - | - |

171| Gateway auth scheme `inferenceGatewayAuthScheme` | `enum` | MDM + Bootstrap Added in 1.3036.0 | `bearer` | How the gateway credential is sent on the wire (Authorization: Bearer vs x-api-key header). One of: `bearer`, `x-api-key`. Defaults to `bearer`. Deprecated: `inferenceGatewayAuthScheme: "sso"`; use inferenceCredentialKind: "interactive". The original spelling will keep working; no end date has been set. |

172| Gateway sign-in flow `inferenceGatewayOidcAuthFlow` | `enum` | MDM + Bootstrap Added in 1.25927.0 | — | How the IdP sign-in runs: system browser (default) or the OS Microsoft Entra broker. One of: `browser`, `broker`. Deprecated: `inferenceGatewayOidcAuthFlow`; use inferenceIdpAuthFlow together with inferenceIdpOidc once every desktop in the fleet is on a release that reads them. The original spelling will keep working; no end date has been set. |

173| Gateway SSO IdP (OIDC) `inferenceGatewayOidc` | `object` | MDM + Bootstrap Added in 1.6889.0 | — | External IdP for gateway sign-in. The user’s token from this issuer is sent to the gateway as the Bearer credential. Deprecated: `inferenceGatewayOidc`; use inferenceIdpOidc with inferenceCredentialKind: "external-idp" once every desktop in the fleet is on a release that reads them. The original spelling will keep working; no end date has been set. |

176| Stream idle timeout `inferenceStreamIdleTimeoutSec` | `integer` | MDM + Bootstrap Added in 1.44121.1 | — | Extra seconds to wait for model output on a streaming response that is sending only keep-alive pings. Gateway provider only. Default 300. Range: 300–1800. |

167[Entry labels](/docs/third-party/claude-desktop/configuration.md#entry-labels) says what each label means.

177168

178> **inferenceGatewayOidcAuthFlow details**

169#### `inferenceGatewayBaseUrl`

170

171string

172

173Consent required (A value that a bootstrap server or a self-hosted session host delivers applies only after the user approves it, unless machine-scoped device management set that server's address. For a bootstrap server, the trustBootstrapDelivery key overrides that default. A value set in an MDM profile, the local configuration file or the Enterprise Admin Console needs no approval.)

174

175Origin-pinned (A URL that a bootstrap server delivers must share the origin of bootstrapUrl, or Claude Desktop drops it. The limit is lifted when bootstrapOidc is set, and it does not apply to a value set in an MDM profile, the local configuration file or the Enterprise Admin Console.)

176

177Since 1.2581.0

178

179**Gateway base URL.** Full URL of the inference gateway endpoint.

180

181***

182

183#### `inferenceGatewayApiKey`

184

185stringSince 1.2581.0

186

187**Gateway API key.** API key for the configured inference gateway.

188

189***

190

191#### `inferenceGatewayAuthScheme`

192

193enumDefault: bearerSince 1.3036.0

194

195**Gateway auth scheme.** How the gateway credential is sent on the wire (Authorization: Bearer vs x-api-key header).

196

197One of: `bearer` (default), `x-api-key`

198

199> [!WARNING]

179200>

201> **Deprecated**

202>

203> * `inferenceGatewayAuthScheme: "sso"`; use inferenceCredentialKind: "interactive". The original spelling will keep working; no end date has been set.

204

205***

206

207#### `inferenceGatewayOidcAuthFlow`

208

209enumSince 1.25927.0

210

211**Gateway sign-in flow.** How the IdP sign-in runs: system browser (default) or the OS Microsoft Entra broker.

212

213One of: `browser`, `broker`

214

215> [!WARNING]

216>

217> **Deprecated**

218>

219> * Use inferenceIdpAuthFlow together with inferenceIdpOidc once every desktop in the fleet is on a release that reads them. The original spelling will keep working; no end date has been set.

220

221> **More detail**

222>

180223> * **`browser`** (default) — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. See the **IdP setup** notes on `inferenceGatewayOidc` for redirect-URI registration.

181224> * **`broker`** — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS). Requires the IdP to be **Microsoft Entra ID** — the `issuer` on `inferenceGatewayOidc` must be `https://login.microsoftonline.com/{tenant-id}/v2.0`. The broker satisfies Conditional Access policies that require a compliant/managed device or token protection, and needs no loopback redirect. The Entra app registration must include the broker redirect URIs `ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}` (Windows) and `msauth.com.anthropic.claudefordesktop://auth` (macOS) under the **Mobile and desktop applications** platform. Not supported on Linux.

182225>

183226> Broker mode mints a token in the customer's own Entra tenant with the customer-configured `scopes`, and forwards it to the customer's own gateway; both endpoints of that trust relationship are inside the customer's control. A desktop that has the `external-idp` kind reads this key, together with `inferenceGatewayOidc`, as that kind's sign-in flow; it stays readable.

184227

185> **inferenceGatewayOidc details**

228***

229

230#### `inferenceGatewayOidc`

231

232object

233

234Consent required (A value that a bootstrap server or a self-hosted session host delivers applies only after the user approves it, unless machine-scoped device management set that server's address. For a bootstrap server, the trustBootstrapDelivery key overrides that default. A value set in an MDM profile, the local configuration file or the Enterprise Admin Console needs no approval.)

235

236Since 1.6889.0

237

238**Gateway SSO IdP (OIDC).** External IdP for gateway sign-in. The user’s token from this issuer is sent to the gateway as the Bearer credential.

239

240> [!WARNING]

186241>

242> **Deprecated**

243>

244> * Use inferenceIdpOidc with inferenceCredentialKind: "external-idp" once every desktop in the fleet is on a release that reads them. The original spelling will keep working; no end date has been set.

245

246> **More detail**

247>

187248> **External IdP mode.** The app discovers `<issuer>/.well-known/openid-configuration`, runs an OIDC authorization-code-with-PKCE sign-in in the system browser with `clientId`, and sends the resulting token as `Authorization: Bearer` on every inference request. Leave this unset for a gateway that hosts its own RFC 8414 metadata at `<baseUrl>/.well-known/oauth-authorization-server`. A desktop that has the `external-idp` kind reads this block as that kind's identity-provider key; it stays readable, so a fleet keeps this spelling until every desktop is on such a release.

188249>

189250> **Bearer token type.** `id_token` (the default) sends the OIDC ID token; the gateway validates signature, `iss`, and `aud` (the `clientId` configured here). `access_token` sends the OAuth access token, for gateways that validate as a resource server (Portkey, Kong, Envoy JWT filter, AWS API Gateway authorizers); `scopes` must then name the gateway's registered API scope. Either way the gateway must check `aud`, not just signature and issuer, or it accepts any token from your tenant.

from line 252

191252> **IdP setup.** The callback is `http://127.0.0.1:<port>/callback` by default (`http://localhost:<port>/callback` with `redirectHost: "localhost"`); register exactly the one you use and include `/callback`. **Entra:** a public-client app with a *Mobile and desktop applications* redirect URI of `http://127.0.0.1/callback` (any port; omitting the path fails with `AADSTS50011`); in `access_token` mode also grant the gateway API's delegated permission, or sign-in fails with `AADSTS65001`. **Okta:** a *Native* app with the exact URI `http://127.0.0.1:<port>/callback` and that port in `redirectPort`.

192253>

193254> **Refresh.** With `offline_access` the app renews the token silently and prompts a browser sign-in only when refresh fails. Google never returns an `id_token` on refresh, so a Google Workspace-backed gateway in `id_token` mode re-prompts about hourly; `access_token` mode is unaffected.

255

256> **Child attributes (11)**

194257>

196> | - | - | - | - |

258> **clientId** `string` *required*

259>

260> OAuth client ID of the desktop app registration at your identity provider (public client, PKCE).

261>

262> **issuer** `string`

263>

264> HTTPS issuer with OIDC discovery. Set this, or set the authorization and token URLs instead.

265>

266> **authorizationUrl** `string`

267>

268> HTTPS authorization endpoint. Used with the token URL when no issuer is set.

269>

270> **tokenUrl** `string`

271>

272> HTTPS token endpoint. Used with the authorization URL when no issuer is set.

273>

274> **bearerTokenType** `enum` (default: id\_token)

275>

276> Which token to send as the bearer. Use access token for a gateway or proxy that validates as an OAuth resource server.

277>

278> One of: `id_token` (default), `access_token`

279>

280> > **More detail**

281> >

282> > In **access-token** mode the token's audience must be your gateway or proxy. On IdPs where the requested scopes decide the audience (**Entra ID**), include its API resource scope in `scopes` — `api://<gateway-app-id>/.default`, or a named delegated scope you exposed via *Expose an API*. With only the standard OIDC scopes (`openid profile email offline_access`) Entra returns a v1.0 Microsoft Graph token whose issuer (`https://sts.windows.net/<tenant>/`) doesn't match the v2.0 issuer configured here, so a gateway that validates `iss` rejects it. On IdPs that set the access-token audience out-of-band (Keycloak audience mapper, Auth0 default audience, Okta custom authorization server), a resource scope in `scopes` isn't required — the audience comes from the IdP-side configuration.

283>

284> **scopes** `string`

285>

286> Space-separated scopes. Required in access-token mode: set the gateway or proxy API scope. offline\_access is appended automatically unless disabled below.

287>

288> **appendOfflineAccess** `boolean` (default: true)

289>

290> Automatically append offline\_access to scopes so the IdP returns a refresh token for silent refresh.

291>

292> > **More detail**

293> >

294> > Turn off only if your authorization server rejects `offline_access` as an unknown scope; include the server’s own refresh-token scope in **Scopes** instead.

295>

296> **resource** `string`

297>

298> Access-token audience of the gateway or proxy: an https URL or an AD FS relying-party identifier, sent as the RFC 8707 resource. Leave unset for Entra ID.

299>

300> > **More detail**

301> >

302> > Set this only for an IdP that implements RFC 8707 resource indicators. The app then sends `resource=<value>` on the authorization, token and refresh requests, so the access token the IdP issues is audience-restricted to the gateway or proxy rather than to the IdP's own APIs. Use it with `bearerTokenType: access_token`; in `id_token` mode the ID token's audience is always `clientId`. Ignored with the OS-broker sign-in flow (the sign-in flow key set to `broker`), which is Entra-only.

303> >

304> > **Microsoft Entra ID:** leave unset — the v2.0 endpoint rejects `resource`; request the API scope in `scopes` instead (`api://<gateway-app-id>/.default`). **AD FS:** enter one of the relying-party trust's identifiers, spelled as it is registered there. A value with no scheme (a host name with or without a port or path, a single name, or a GUID; `name:digits` also reads as a host name with a port) is sent as `https://<value>`; an identifier with a scheme of its own (`urn:…`, or an organization-defined one such as `VENDOR:URI:…`) is sent exactly as written. A trust whose only identifier is a bare name or GUID will not match, because those are sent as `https://<value>`: add an `https://…` or `urn:…` identifier to the trust and enter that one here. With any other identity provider, use an absolute URI without a fragment (RFC 8707 — the IdP rejects one as `invalid_target`). Changing it signs users in again.

305>

306> **redirectPort** `integer`

307>

308> Fixed loopback port for the sign-in redirect. Leave unset to use a free port each time.

309>

310> **redirectHost** `enum`

311>

312> Use localhost only if your IdP’s registered redirect URI specifies it.

313>

314> One of: `127.0.0.1`, `localhost`

315>

316> **additionalRedirectReferrerHosts** `string`

317>

318> Space-separated hostnames also accepted as the referrer of the sign-in callback. Only needed when the IdP completes sign-in from a different host.

319>

320> > **More detail**

321> >

322> > Only needed when the IdP completes sign-in from a host other than the authorization URL’s. When a callback is rejected for a referrer mismatch, the rejected host is named in the app log — add that hostname here.

208323

209> **inferenceIdpAuthFlow details**

324***

325

326#### `inferenceIdpAuthFlow`

327

328enumSince 2.7032.0

329

330**Identity provider sign-in flow.** How the identity-provider sign-in runs: system browser (default) or the OS Microsoft Entra broker.

331

332One of: `browser`, `broker`

333

334> **More detail**

210335>

211336> * **`browser`** (default) — opens the system browser for an authorization-code (PKCE) sign-in on a loopback redirect URI. See the **IdP setup** notes on `inferenceIdpOidc` for redirect-URI registration.

212337> * **`broker`** — signs in through the OS identity broker (Web Account Manager on Windows, Company Portal on macOS). Requires the IdP to be **Microsoft Entra ID** — the `issuer` on `inferenceIdpOidc` must be `https://login.microsoftonline.com/{tenant-id}/v2.0`. The broker satisfies Conditional Access policies that require a compliant/managed device or token protection, and needs no loopback redirect. The Entra app registration must include the broker redirect URIs `ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}` (Windows) and `msauth.com.anthropic.claudefordesktop://auth` (macOS) under the **Mobile and desktop applications** platform. Not supported on Linux.

from line 338

213338>

214339> Broker mode mints a token in the customer's own Entra tenant with the customer-configured `scopes` and forwards it to the customer's own gateway or proxy; both endpoints of that trust relationship are inside the customer's control.

215340

216> **inferenceIdpOidc details**

341***

342

343#### `inferenceIdpOidc`

344

345object

346

347Consent required (A value that a bootstrap server or a self-hosted session host delivers applies only after the user approves it, unless machine-scoped device management set that server's address. For a bootstrap server, the trustBootstrapDelivery key overrides that default. A value set in an MDM profile, the local configuration file or the Enterprise Admin Console needs no approval.)

348

349Since 2.7032.0

350

351**Identity provider (OIDC).** Your organization’s OpenID Connect identity provider. The user’s token is sent as the Bearer credential to the gateway or the Bedrock proxy.

352

353> **More detail**

217354>

218355> Used with `inferenceCredentialKind: "external-idp"`. The app discovers `<issuer>/.well-known/openid-configuration`, runs an OIDC authorization-code (PKCE) sign-in in the browser with `clientId` (or through the OS broker, see `inferenceIdpAuthFlow`) and sends the token as `Authorization: Bearer` on every inference request: to `inferenceGatewayBaseUrl` on the gateway provider, or on Bedrock to `inferenceBedrockBaseUrl`, which is then required: only a proxy that validates the token accepts it, never Amazon Bedrock itself (to sign in straight to Bedrock use `interactive`, AWS IAM Identity Center). On Bedrock this kind has no model discovery: list the models in `inferenceModels`.

219356>

from line 361

224361> **Refresh.** With `offline_access` the app renews the token silently and asks for a browser sign-in only when refresh fails (Google returns no `id_token` on refresh, so `id_token` mode there re-prompts about hourly).

225362>

226363> **Older names.** Gateway configurations written before this key use `inferenceGatewayOidc` / `inferenceGatewayOidcAuthFlow` with the `interactive` kind; they stay readable and mean the same sign-in.

364

365> **Child attributes (11)**

227366>

229> | - | - | - | - |

367> **clientId** `string` *required*

368>

369> OAuth client ID of the desktop app registration at your identity provider (public client, PKCE).

370>

371> **issuer** `string`

372>

373> HTTPS issuer with OIDC discovery. Set this, or set the authorization and token URLs instead.

374>

375> **authorizationUrl** `string`

376>

377> HTTPS authorization endpoint. Used with the token URL when no issuer is set.

378>

379> **tokenUrl** `string`

380>

381> HTTPS token endpoint. Used with the authorization URL when no issuer is set.

382>

383> **bearerTokenType** `enum` (default: id\_token)

384>

385> Which token to send as the bearer. Use access token for a gateway or proxy that validates as an OAuth resource server.

386>

387> One of: `id_token` (default), `access_token`

388>

389> > **More detail**

390> >

391> > In **access-token** mode the token's audience must be your gateway or proxy. On IdPs where the requested scopes decide the audience (**Entra ID**), include its API resource scope in `scopes` — `api://<gateway-app-id>/.default`, or a named delegated scope you exposed via *Expose an API*. With only the standard OIDC scopes (`openid profile email offline_access`) Entra returns a v1.0 Microsoft Graph token whose issuer (`https://sts.windows.net/<tenant>/`) doesn't match the v2.0 issuer configured here, so a gateway that validates `iss` rejects it. On IdPs that set the access-token audience out-of-band (Keycloak audience mapper, Auth0 default audience, Okta custom authorization server), a resource scope in `scopes` isn't required — the audience comes from the IdP-side configuration.

392>

393> **scopes** `string`

394>

395> Space-separated scopes. Required in access-token mode: set the gateway or proxy API scope. offline\_access is appended automatically unless disabled below.

396>

397> **appendOfflineAccess** `boolean` (default: true)

398>

399> Automatically append offline\_access to scopes so the IdP returns a refresh token for silent refresh.

400>

401> > **More detail**

402> >

403> > Turn off only if your authorization server rejects `offline_access` as an unknown scope; include the server’s own refresh-token scope in **Scopes** instead.

404>

405> **resource** `string`

406>

407> Access-token audience of the gateway or proxy: an https URL or an AD FS relying-party identifier, sent as the RFC 8707 resource. Leave unset for Entra ID.

408>

409> > **More detail**

410> >

411> > Set this only for an IdP that implements RFC 8707 resource indicators. The app then sends `resource=<value>` on the authorization, token and refresh requests, so the access token the IdP issues is audience-restricted to the gateway or proxy rather than to the IdP's own APIs. Use it with `bearerTokenType: access_token`; in `id_token` mode the ID token's audience is always `clientId`. Ignored with the OS-broker sign-in flow (the sign-in flow key set to `broker`), which is Entra-only.

412> >

413> > **Microsoft Entra ID:** leave unset — the v2.0 endpoint rejects `resource`; request the API scope in `scopes` instead (`api://<gateway-app-id>/.default`). **AD FS:** enter one of the relying-party trust's identifiers, spelled as it is registered there. A value with no scheme (a host name with or without a port or path, a single name, or a GUID; `name:digits` also reads as a host name with a port) is sent as `https://<value>`; an identifier with a scheme of its own (`urn:…`, or an organization-defined one such as `VENDOR:URI:…`) is sent exactly as written. A trust whose only identifier is a bare name or GUID will not match, because those are sent as `https://<value>`: add an `https://…` or `urn:…` identifier to the trust and enter that one here. With any other identity provider, use an absolute URI without a fragment (RFC 8707 — the IdP rejects one as `invalid_target`). Changing it signs users in again.

414>

415> **redirectPort** `integer`

416>

417> Fixed loopback port for the sign-in redirect. Leave unset to use a free port each time.

418>

419> **redirectHost** `enum`

420>

421> Use localhost only if your IdP’s registered redirect URI specifies it.

422>

423> One of: `127.0.0.1`, `localhost`

424>

425> **additionalRedirectReferrerHosts** `string`

426>

427> Space-separated hostnames also accepted as the referrer of the sign-in callback. Only needed when the IdP completes sign-in from a different host.

428>

429> > **More detail**

430> >

431> > Only needed when the IdP completes sign-in from a host other than the authorization URL’s. When a callback is rejected for a referrer mismatch, the rejected host is named in the app log — add that hostname here.

241432

242> **inferenceStreamIdleTimeoutSec details**

433***

434

435#### `inferenceStreamIdleTimeoutSec`

436

437integerRange: 300–1,800Since 1.44121.1

438

439**Stream idle timeout.** Extra seconds to wait for model output on a streaming response that is sending only keep-alive pings. Gateway provider only. Default 300.

440

441> **More detail**

243442>

244443> Raises how long Cowork, Chat and Code sessions wait for the next model event on an open streaming response (Claude Code's `CLAUDE_STREAM_IDLE_TIMEOUT_MS`). It only helps when the gateway writes SSE keep-alive `ping` events (or `:` comment lines) into the response while the upstream model is silent — for example a LiteLLM proxy with keep-alive pings enabled in front of Amazon Bedrock. With pings arriving, Claude Code accepts at least about five minutes of keep-alives and then waits this many seconds more for real model output before abandoning the request. Gateway provider only; the other providers keep Claude Code's defaults.

245444>

246445> A response on which nothing at all arrives — no pings — still fails after about 5 minutes regardless of this key, because at the device a silent connection cannot be told apart from a dead one. If long generations fail behind a gateway that does not send pings, configure the gateway to send them rather than raising this value. A common case is automatic compaction, in which a session sends its whole conversation in one streaming request and waits for a long summary; when that request fails, the error reads `Prompt is too long · automatic compaction failed:` followed by the cause. While this key is set, the app's value takes precedence over `CLAUDE_STREAM_IDLE_TIMEOUT_MS` in Claude Code's own managed settings for sessions the app starts; when it is unset, that setting still applies. Values outside 300–1800 are rejected at parse time (the error is listed in the diagnostics report) and the default applies.

247446

447***

448

248449To send additional HTTP headers on every inference request (tenant routing, org IDs, and similar), set [`inferenceCustomHeaders`](/docs/third-party/claude-desktop/configuration#inferencecustomheaders). It applies to all providers, not just gateways.

249450

250451### Single sign-on configuration keys

from line 478

277478

278479> [!WARNING]

279480>

280> `inferenceGatewayOidc` is **one MDM key whose value is a JSON string** — not separate keys like `inferenceGatewayOidc.clientId`. See [how object-typed keys are encoded](/docs/third-party/claude-desktop/configuration.md#value-types). The in-app **Export** produces the correct format automatically.

481> `inferenceGatewayOidc` is **one MDM key whose value is a JSON string** — not separate keys like `inferenceGatewayOidc.clientId`. See [how object-typed keys are encoded](/docs/third-party/claude-desktop/configuration-format.md#value-types). The in-app **Export** produces the correct format automatically.

281482

282483In a macOS `.mobileconfig` payload (Okta example):

283484

This page’s history 36 edits

22 Oct 2026 +248 −47 · this one
22 Oct 2026 +12 −12
22 Oct 2026 +7 −7
14 Oct 2026 +140 −144
14 Oct 2026 +3 −3
13 Oct 2026 +1 −1

The page’s own history →

Where it came from

The captureclaude-docs
Upstream pageclaude.com

Around it

Every changethe ledger
That day22 Oct 2026