Turn on OAuth so AI tools connect with just the address.
Checked on Izumi 0.5.7, 2026-11-21 (code and production, read only).With OAuth turned on, ChatGPT, claude.ai and Claude Code connect to <TB_PUBLIC_URL>/mcp without a personal token. The person signs in to Izumi in the browser, approves the client on the Izumi consent page, and the client gets an OAuth token that acts as that person. The scope is read and, when the person ticks it, propose. Izumi is its own authorization server. The steps for each client are in the AI tools tab: Overview.
Not checked live yet on this page: changing the switch in .env, key rotation and pre-registered clients. OAuth is turned on in production and was checked by reading the public addresses. Signing in with a Microsoft account through OAuth has not been checked (HC-OA-10).
What you need
A public HTTPS address. TB_OAUTH=on needs TB_PUBLIC_URL with https and no path (for example https://brain.example.com) and TB_MASTER_KEY (the server’s signing and cookie keys are stored encrypted with it).
ChatGPT and claude.ai call the server from their own clouds, so the address must be reachable from the internet. Claude Code on the same network as the server needs only that network.
An http address is allowed only for localhost and 127.0.0.1 (tests).
Three switches
Set them in .env, then docker compose up -d.
Variable
Default
What it does
TB_OAUTH
off
on mounts the authorization server (/oauth/* and the discovery documents) into the app.
TB_OAUTH_CIMD
on
Read only with TB_OAUTH=on. A client whose client_id is an address on claude.ai or chatgpt.com is recognized by the metadata document at that address (CIMD). off for a closed egress.
TB_OAUTH_DCR
on
Read only with TB_OAUTH=on. Dynamic client registration at /oauth/register: a client without a CIMD document, or any client when CIMD is off, registers itself. The consent page marks such a client as unverified.
What the server calls and when (from the code)
Only with TB_OAUTH=on and TB_OAUTH_CIMD on, and only when a client whose client_id is an address on claude.ai or chatgpt.com starts connecting, the server fetches that client’s metadata document and the JWKS the document names.
No other host is ever called: the two hosts are fixed in the code.
The call is https only, does not follow redirects, does not go to private addresses, stops after 5 seconds, takes at most 5 KB for the document and 64 KB for the JWKS, and the response is cached for an hour.
When the call fails (for example in a closed network), the connection is refused (invalid_client). Nothing else is affected.
With TB_OAUTH_CIMD=off the server calls nobody: claude.ai and Claude Code then connect through DCR (when it is on) or through a pre-registered client.
With TB_OAUTH=off OAuth does not exist.
Check that it works
Production has OAuth turned on. These addresses are public and need no sign-in:
The first response has issuer with your https address, authorization_endpoint, registration_endpoint, code_challenge_methods_supported with S256 and grant_types_supported with authorization_code and refresh_token.
The second has resource equal to <TB_PUBLIC_URL>/mcp and the scopes read and propose.
POST /mcp without a token returns 401.
Turning it off
Set TB_OAUTH=off and run docker compose up -d. The /oauth routes and the discovery documents disappear, and /mcp accepts only personal tokens: connected apps stop working right away. Their rows stay on the My tokens and profile page: revoke them there if the switch stays off. To keep OAuth but stop every outside call, set TB_OAUTH_CIMD=off.
The command adds a new signing key and a new cookie key. The old cookie key is valid for another 24 hours, and the old signing key stays in the JWKS for another 7 days, so nobody is signed out.After TB_MASTER_KEY changes, the old keys cannot be read. Then:
--reset withdraws all old keys at once (consents in progress start over).
Pre-registered clients
For a client that supports neither CIMD nor DCR, or when both are off, register a public client (PKCE, no secret) and give its client_id to the client.
--label is the name the consent page shows (at most 60 characters).
--redirect-uri accepts https, or http on localhost, 127.0.0.1 or [::1]. Repeat it for more addresses.
client list also lists clients that registered themselves through DCR.
Limits
A shared key for the whole company is not supported: each person connects their own client and approves it with their own sign-in, and the connection reads only what that person reads.
(From the install guide, not checked live.) ChatGPT Free, Plus and Pro only read (whoami, search, get_document, who_knows). propose_note from ChatGPT needs a Business or Enterprise workspace.
Approving clients for the whole company through the identity provider’s administrator (Enterprise-Managed Authorization) comes later.
Before OAuth is offered to a company with Microsoft 365, the whole flow with Entra sign-in must pass live. That has not been done for this release.
A connection lasts 90 days from the last approval, then the client asks for a new connection. A client’s refresh token is valid for 30 days: a client that is not used for 30 days has to reconnect earlier (from the code).
Troubleshooting
What you see
What to check
The app does not start with TB_OAUTH=on, the log says TB_OAUTH=on needs an https TB_PUBLIC_URL, ... without a path, ... needs TB_PUBLIC_URL or ... needs TB_MASTER_KEY (from the code)
TB_PUBLIC_URL must be https without a path, and TB_MASTER_KEY must exist. TB_OAUTH must be exactly on or off.
A client reports invalid_client
The CIMD call failed (closed network, or the address is not on claude.ai or chatgpt.com). Turn on DCR or pre-register the client.
A connected client suddenly asks to connect again
It was not used for 30 days (the refresh token expires) or 90 days have passed since the approval. Also: Every refresh gives the client a new refresh token. If an already used (rotated) refresh token shows up again, the whole connection is cut and the person connects the client again. Or the connection was revoked on the My tokens and profile page.
Connecting fails after TB_MASTER_KEY was changed
Run ./tb admin oauth rotate-keys --reset and restart app.
A client in a closed network cannot connect
TB_OAUTH_CIMD=off, then DCR or a pre-registered client.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Izumi","colors":{"primary":"#ff6b35","light":"#ff6b35","dark":"#0b0c0e"},"logo":{"light":"https://mintcdn.com/akia-consulting/-l5XLI7ftc2U1SZX/logo/light.svg?fit=max\u0026auto=format\u0026n=-l5XLI7ftc2U1SZX\u0026q=85\u0026s=96af7cf3d62f98290e82d9b350a9e3f9","dark":"https://mintcdn.com/akia-consulting/-l5XLI7ftc2U1SZX/logo/dark.svg?fit=max\u0026auto=format\u0026n=-l5XLI7ftc2U1SZX\u0026q=85\u0026s=c30d00f6d1a891b28bff5b756eb7e523","href":"https://izumi.akiaconsulting.com"},"favicon":"https://mintcdn.com/akia-consulting/UfDKk95B0JApANc6/favicon.svg?fit=max\u0026auto=format\u0026n=UfDKk95B0JApANc6\u0026q=85\u0026s=a74575c718248bf0aceb8785ebfd9868","navbar":{"primary":{"type":"button","label":"Prijava / Sign in","href":"https://izumi.akiaconsulting.com"}},"footer":{"links":[{"header":"Izumi","items":[{"label":"izumi.akiaconsulting.com","href":"https://izumi.akiaconsulting.com"},{"label":"Akia Consulting","href":"https://akiaconsulting.com"}]}]},"search":{"prompt":"Pretraga / Search..."},"seo":{"metatags":{"canonical":"https://docs.izumi.akiaconsulting.com"}},"contextual":{"options":["copy","view","chatgpt","claude"],"display":"header"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"akia-consulting","hasAudioNarration":false,"actualSubdomain":"akia-consulting","customDomains":["docs.izumi.akiaconsulting.com"],"gitSource":{"type":"github","owner":"vuuribica","repo":"izumi-docs","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":"","_id":"6b004ee7d53e418143901602"},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6b01968c0d13a27bf2848752","clientVersion":"0.0.4270","searchFilterCounts":[{"language":"default","tag":"Installation","count":11},{"language":"default","tag":"Setting up","count":11},{"language":"default","tag":"Instalacija","count":11},{"language":"default","tag":"Postavljanje","count":11},{"language":"default","tag":"Administration","count":9},{"language":"default","tag":"Managing","count":9},{"language":"default","tag":"Administracija","count":9},{"language":"default","tag":"Upravljanje","count":9},{"language":"default","tag":"Using Izumi","count":8},{"language":"default","tag":"Everyday use","count":8}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"site-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[]}
{"page":{"pagePath":"en/install/oauth","slug":"/en/install/oauth","pageMetadata":{"title":"OAuth for MCP clients","description":"Turn on OAuth so AI tools connect with just the address.","href":"/en/install/oauth"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Turn on OAuth so AI tools connect with just the address.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,li:`li`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,Table,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Table)_missingMdxReference(`Table`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(_components.p,{children:`Checked on Izumi 0.5.7, 2026-11-21 (code and production, read only).`}),`\n`,_jsxs(_components.p,{children:[`With OAuth turned on, ChatGPT, claude.ai and Claude Code connect to `,_jsx(_components.code,{children:`\u003cTB_PUBLIC_URL>/mcp`}),` without a personal token. The person signs in to Izumi in the browser, approves the client on the Izumi consent page, and the client gets an OAuth token that acts as that person. The scope is `,_jsx(_components.code,{children:`read`}),` and, when the person ticks it, `,_jsx(_components.code,{children:`propose`}),`. Izumi is its own authorization server. The steps for each client are in the AI tools tab: `,_jsx(_components.a,{href:`/en/ai-tools/overview`,children:`Overview`}),`.`]}),`\n`,_jsx(Warning,{children:_jsxs(_components.p,{children:[`Not checked live yet on this page: changing the switch in `,_jsx(_components.code,{children:`.env`}),`, key rotation and pre-registered clients. OAuth is turned on in production and was checked by reading the public addresses. Signing in with a Microsoft account through OAuth has not been checked (HC-OA-10).`]})}),`\n`,_jsx(Heading,{level:`2`,id:`what-you-need`,children:`What you need`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`A public HTTPS address. `,_jsx(_components.code,{children:`TB_OAUTH=on`}),` needs `,_jsx(_components.code,{children:`TB_PUBLIC_URL`}),` with `,_jsx(_components.code,{children:`https`}),` and no path (for example `,_jsx(_components.code,{children:`https://brain.example.com`}),`) and `,_jsx(_components.code,{children:`TB_MASTER_KEY`}),` (the server’s signing and cookie keys are stored encrypted with it).`]}),`\n`,_jsx(_components.li,{children:`ChatGPT and claude.ai call the server from their own clouds, so the address must be reachable from the internet. Claude Code on the same network as the server needs only that network.`}),`\n`,_jsxs(_components.li,{children:[`An `,_jsx(_components.code,{children:`http`}),` address is allowed only for `,_jsx(_components.code,{children:`localhost`}),` and `,_jsx(_components.code,{children:`127.0.0.1`}),` (tests).`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`three-switches`,children:`Three switches`}),`\n`,_jsxs(_components.p,{children:[`Set them in `,_jsx(_components.code,{children:`.env`}),`, then `,_jsx(_components.code,{children:`docker compose up -d`}),`.`]}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Variable`}),_jsx(_components.th,{children:`Default`}),_jsx(_components.th,{children:`What it does`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`TB_OAUTH`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`off`})}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`on`}),` mounts the authorization server (`,_jsx(_components.code,{children:`/oauth/*`}),` and the discovery documents) into the app.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`TB_OAUTH_CIMD`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`on`})}),_jsxs(_components.td,{children:[`Read only with `,_jsx(_components.code,{children:`TB_OAUTH=on`}),`. A client whose `,_jsx(_components.code,{children:`client_id`}),` is an address on `,_jsx(_components.code,{children:`claude.ai`}),` or `,_jsx(_components.code,{children:`chatgpt.com`}),` is recognized by the metadata document at that address (CIMD). `,_jsx(_components.code,{children:`off`}),` for a closed egress.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`TB_OAUTH_DCR`})}),_jsx(_components.td,{children:_jsx(_components.code,{children:`on`})}),_jsxs(_components.td,{children:[`Read only with `,_jsx(_components.code,{children:`TB_OAUTH=on`}),`. Dynamic client registration at `,_jsx(_components.code,{children:`/oauth/register`}),`: a client without a CIMD document, or any client when CIMD is off, registers itself. The consent page marks such a client as unverified.`]})]})]})]}),`\n`,_jsx(Heading,{level:`2`,id:`what-the-server-calls-and-when-from-the-code`,children:`What the server calls and when (from the code)`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`Only with `,_jsx(_components.code,{children:`TB_OAUTH=on`}),` and `,_jsx(_components.code,{children:`TB_OAUTH_CIMD`}),` on, and only when a client whose `,_jsx(_components.code,{children:`client_id`}),` is an address on `,_jsx(_components.code,{children:`claude.ai`}),` or `,_jsx(_components.code,{children:`chatgpt.com`}),` starts connecting, the server fetches that client’s metadata document and the JWKS the document names.`]}),`\n`,_jsx(_components.li,{children:`No other host is ever called: the two hosts are fixed in the code.`}),`\n`,_jsxs(_components.li,{children:[`The call is `,_jsx(_components.code,{children:`https`}),` only, does not follow redirects, does not go to private addresses, stops after 5 seconds, takes at most 5 KB for the document and 64 KB for the JWKS, and the response is cached for an hour.`]}),`\n`,_jsxs(_components.li,{children:[`When the call fails (for example in a closed network), the connection is refused (`,_jsx(_components.code,{children:`invalid_client`}),`). Nothing else is affected.`]}),`\n`,_jsxs(_components.li,{children:[`With `,_jsx(_components.code,{children:`TB_OAUTH_CIMD=off`}),` the server calls nobody: claude.ai and Claude Code then connect through DCR (when it is on) or through a pre-registered client.`]}),`\n`,_jsxs(_components.li,{children:[`With `,_jsx(_components.code,{children:`TB_OAUTH=off`}),` OAuth does not exist.`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`check-that-it-works`,children:`Check that it works`}),`\n`,_jsx(_components.p,{children:`Production has OAuth turned on. These addresses are public and need no sign-in:`}),`\n`,_jsx(CodeBlock,{numberOfLines:`4`,language:`text`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`text`,children:_jsxs(_components.code,{language:`text`,numberOfLines:`4`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`curl -s https://brain.example.com/.well-known/oauth-authorization-server`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`curl -s https://brain.example.com/.well-known/oauth-protected-resource`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`curl -s -o /dev/null -w \"%{http_code}\\\\n\" -X POST https://brain.example.com/mcp`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})})]})})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`The first response has `,_jsx(_components.code,{children:`issuer`}),` with your `,_jsx(_components.code,{children:`https`}),` address, `,_jsx(_components.code,{children:`authorization_endpoint`}),`, `,_jsx(_components.code,{children:`registration_endpoint`}),`, `,_jsx(_components.code,{children:`code_challenge_methods_supported`}),` with `,_jsx(_components.code,{children:`S256`}),` and `,_jsx(_components.code,{children:`grant_types_supported`}),` with `,_jsx(_components.code,{children:`authorization_code`}),` and `,_jsx(_components.code,{children:`refresh_token`}),`.`]}),`\n`,_jsxs(_components.li,{children:[`The second has `,_jsx(_components.code,{children:`resource`}),` equal to `,_jsx(_components.code,{children:`\u003cTB_PUBLIC_URL>/mcp`}),` and the scopes `,_jsx(_components.code,{children:`read`}),` and `,_jsx(_components.code,{children:`propose`}),`.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`POST /mcp`}),` without a token returns 401.`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`turning-it-off`,children:`Turning it off`}),`\n`,_jsxs(_components.p,{children:[`Set `,_jsx(_components.code,{children:`TB_OAUTH=off`}),` and run `,_jsx(_components.code,{children:`docker compose up -d`}),`. The `,_jsx(_components.code,{children:`/oauth`}),` routes and the discovery documents disappear, and `,_jsx(_components.code,{children:`/mcp`}),` accepts only personal tokens: connected apps stop working right away. Their rows stay on the `,_jsx(_components.strong,{children:`My tokens and profile`}),` page: revoke them there if the switch stays off. To keep OAuth but stop every outside call, set `,_jsx(_components.code,{children:`TB_OAUTH_CIMD=off`}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`key-rotation`,children:`Key rotation`}),`\n`,_jsx(CodeBlock,{numberOfLines:`3`,language:`text`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`text`,children:_jsxs(_components.code,{language:`text`,numberOfLines:`3`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`./tb admin oauth rotate-keys`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`docker compose restart app`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})})]})})}),`\n`,_jsx(_components.p,{children:`The command adds a new signing key and a new cookie key. The old cookie key is valid for another 24 hours, and the old signing key stays in the JWKS for another 7 days, so nobody is signed out.`}),`\n`,_jsxs(_components.p,{children:[`After `,_jsx(_components.code,{children:`TB_MASTER_KEY`}),` changes, the old keys cannot be read. Then:`]}),`\n`,_jsx(CodeBlock,{numberOfLines:`3`,language:`text`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`text`,children:_jsxs(_components.code,{language:`text`,numberOfLines:`3`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`./tb admin oauth rotate-keys --reset`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`docker compose restart app`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})})]})})}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`--reset`}),` withdraws all old keys at once (consents in progress start over).`]}),`\n`,_jsx(Heading,{level:`2`,id:`pre-registered-clients`,children:`Pre-registered clients`}),`\n`,_jsxs(_components.p,{children:[`For a client that supports neither CIMD nor DCR, or when both are off, register a public client (PKCE, no secret) and give its `,_jsx(_components.code,{children:`client_id`}),` to the client.`]}),`\n`,_jsx(CodeBlock,{numberOfLines:`4`,language:`text`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light-default dark-plus`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#0B0C0E`,color:`#1f2328`,\"--shiki-dark\":`#D4D4D4`},language:`text`,children:_jsxs(_components.code,{language:`text`,numberOfLines:`4`,children:[_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`./tb admin oauth client add --label \"Team tool\" --redirect-uri https://tool.example.com/callback`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`./tb admin oauth client list`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{children:`./tb admin oauth client remove \u003cclient_id>`})}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{})})]})})}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`--label`}),` is the name the consent page shows (at most 60 characters).`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`--redirect-uri`}),` accepts `,_jsx(_components.code,{children:`https`}),`, or `,_jsx(_components.code,{children:`http`}),` on `,_jsx(_components.code,{children:`localhost`}),`, `,_jsx(_components.code,{children:`127.0.0.1`}),` or `,_jsx(_components.code,{children:`[::1]`}),`. Repeat it for more addresses.`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`client list`}),` also lists clients that registered themselves through DCR.`]}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`limits`,children:`Limits`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:`A shared key for the whole company is not supported: each person connects their own client and approves it with their own sign-in, and the connection reads only what that person reads.`}),`\n`,_jsxs(_components.li,{children:[`(From the install guide, not checked live.) ChatGPT Free, Plus and Pro only read (`,_jsx(_components.code,{children:`whoami`}),`, `,_jsx(_components.code,{children:`search`}),`, `,_jsx(_components.code,{children:`get_document`}),`, `,_jsx(_components.code,{children:`who_knows`}),`). `,_jsx(_components.code,{children:`propose_note`}),` from ChatGPT needs a Business or Enterprise workspace.`]}),`\n`,_jsx(_components.li,{children:`Approving clients for the whole company through the identity provider’s administrator (Enterprise-Managed Authorization) comes later.`}),`\n`,_jsx(_components.li,{children:`Before OAuth is offered to a company with Microsoft 365, the whole flow with Entra sign-in must pass live. That has not been done for this release.`}),`\n`,_jsx(_components.li,{children:`A connection lasts 90 days from the last approval, then the client asks for a new connection. A client’s refresh token is valid for 30 days: a client that is not used for 30 days has to reconnect earlier (from the code).`}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`troubleshooting`,children:`Troubleshooting`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`What you see`}),_jsx(_components.th,{children:`What to check`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsxs(_components.td,{children:[`The app does not start with `,_jsx(_components.code,{children:`TB_OAUTH=on`}),`, the log says `,_jsx(_components.code,{children:`TB_OAUTH=on needs an https TB_PUBLIC_URL`}),`, `,_jsx(_components.code,{children:`... without a path`}),`, `,_jsx(_components.code,{children:`... needs TB_PUBLIC_URL`}),` or `,_jsx(_components.code,{children:`... needs TB_MASTER_KEY`}),` (from the code)`]}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`TB_PUBLIC_URL`}),` must be `,_jsx(_components.code,{children:`https`}),` without a path, and `,_jsx(_components.code,{children:`TB_MASTER_KEY`}),` must exist. `,_jsx(_components.code,{children:`TB_OAUTH`}),` must be exactly `,_jsx(_components.code,{children:`on`}),` or `,_jsx(_components.code,{children:`off`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsxs(_components.td,{children:[`A client reports `,_jsx(_components.code,{children:`invalid_client`})]}),_jsxs(_components.td,{children:[`The CIMD call failed (closed network, or the address is not on `,_jsx(_components.code,{children:`claude.ai`}),` or `,_jsx(_components.code,{children:`chatgpt.com`}),`). Turn on DCR or pre-register the client.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`A connected client suddenly asks to connect again`}),_jsxs(_components.td,{children:[`It was not used for 30 days (the refresh token expires) or 90 days have passed since the approval. Also: Every refresh gives the client a new refresh token. If an already used (rotated) refresh token shows up again, the whole connection is cut and the person connects the client again. Or the connection was revoked on the `,_jsx(_components.strong,{children:`My tokens and profile`}),` page.`]})]}),_jsxs(_components.tr,{children:[_jsxs(_components.td,{children:[`Connecting fails after `,_jsx(_components.code,{children:`TB_MASTER_KEY`}),` was changed`]}),_jsxs(_components.td,{children:[`Run `,_jsx(_components.code,{children:`./tb admin oauth rotate-keys --reset`}),` and restart `,_jsx(_components.code,{children:`app`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`A client in a closed network cannot connect`}),_jsxs(_components.td,{children:[_jsx(_components.code,{children:`TB_OAUTH_CIMD=off`}),`, then DCR or a pre-registered client.`]})]})]})]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"OAuth for MCP clients","description":"Turn on OAuth so AI tools connect with just the address.","href":"/en/install/oauth"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"What you need","slug":"what-you-need","depth":2,"children":[]},{"title":"Three switches","slug":"three-switches","depth":2,"children":[]},{"title":"What the server calls and when (from the code)","slug":"what-the-server-calls-and-when-from-the-code","depth":2,"children":[]},{"title":"Check that it works","slug":"check-that-it-works","depth":2,"children":[]},{"title":"Turning it off","slug":"turning-it-off","depth":2,"children":[]},{"title":"Key rotation","slug":"key-rotation","depth":2,"children":[]},{"title":"Pre-registered clients","slug":"pre-registered-clients","depth":2,"children":[]},{"title":"Limits","slug":"limits","depth":2,"children":[]},{"title":"Troubleshooting","slug":"troubleshooting","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":[],"subdomain":"akia-consulting","siteName":"Izumi","title":"OAuth for MCP clients - Izumi","navMaps":{"firstHrefInVersion":{"Srpski":{"href":"/sr/upoznaj/sta-je-izumi","matchLevel":4},"English":{"href":"/en/install/oauth","matchLevel":0}},"firstHrefInLanguage":{}},"lastModified":"2026-11-21T12:41:29.962Z","originalFileLocation":"en/install/oauth.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Turn on OAuth so AI tools connect with just the address.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Izumi\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/akia-consulting/IZKlsOdu96JblZDm/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/akia-consulting/IZKlsOdu96JblZDm/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/akia-consulting/IZKlsOdu96JblZDm/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/akia-consulting/IZKlsOdu96JblZDm/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/akia-consulting/IZKlsOdu96JblZDm/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/akia-consulting/IZKlsOdu96JblZDm/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/akia-consulting/IZKlsOdu96JblZDm/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/akia-consulting/IZKlsOdu96JblZDm/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/akia-consulting/IZKlsOdu96JblZDm/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"OAuth for MCP clients - Izumi\">\u003cmeta data-mint-head property=\"og:description\" content=\"Turn on OAuth so AI tools connect with just the address.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Izumi\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.izumi.akiaconsulting.com/en/install/oauth\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://akia-consulting.mintlify.site/_mintlify/api/og/v2?division=Setting+up\u0026amp;title=OAuth+for+MCP+clients\u0026amp;description=Turn+on+OAuth+so+AI+tools+connect+with+just+the+address.\u0026amp;theme=12c8ef4e20932cca09adf228\u0026amp;signature=ec4ab53cc312f57a971474efd8256ae4437ff7e9eeee3ce6d300c8af5b6b90ab\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"OAuth for MCP clients - Izumi\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Turn on OAuth so AI tools connect with just the address.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://akia-consulting.mintlify.site/_mintlify/api/og/v2?division=Setting+up\u0026amp;title=OAuth+for+MCP+clients\u0026amp;description=Turn+on+OAuth+so+AI+tools+connect+with+just+the+address.\u0026amp;theme=12c8ef4e20932cca09adf228\u0026amp;signature=ec4ab53cc312f57a971474efd8256ae4437ff7e9eeee3ce6d300c8af5b6b90ab\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/akia-consulting/IZKlsOdu96JblZDm/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Izumi\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#ff6b35\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.izumi.akiaconsulting.com/en/install/oauth\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/en/install/oauth.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.izumi.akiaconsulting.com/#organization\",\"name\":\"Izumi\",\"url\":\"https://docs.izumi.akiaconsulting.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/akia-consulting/-l5XLI7ftc2U1SZX/logo/light.svg?fit=max\u0026auto=format\u0026n=-l5XLI7ftc2U1SZX\u0026q=85\u0026s=96af7cf3d62f98290e82d9b350a9e3f9\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.izumi.akiaconsulting.com#website\",\"name\":\"Izumi\",\"url\":\"https://docs.izumi.akiaconsulting.com\",\"publisher\":{\"@id\":\"https://docs.izumi.akiaconsulting.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.izumi.akiaconsulting.com/en/install/oauth#webpage\",\"url\":\"https://docs.izumi.akiaconsulting.com/en/install/oauth\",\"name\":\"OAuth for MCP clients\",\"description\":\"Turn on OAuth so AI tools connect with just the address.\",\"dateModified\":\"2026-11-21T12:41:29.962Z\",\"isPartOf\":{\"@id\":\"https://docs.izumi.akiaconsulting.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.izumi.akiaconsulting.com/en/install/oauth#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.izumi.akiaconsulting.com/en/install/oauth#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Setting up\",\"item\":\"https://docs.izumi.akiaconsulting.com/en/install/requirements\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"OAuth for MCP clients\",\"item\":\"https://docs.izumi.akiaconsulting.com/en/install/oauth\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.izumi.akiaconsulting.com/en/install/oauth#article\",\"headline\":\"OAuth for MCP clients\",\"name\":\"OAuth for MCP clients\",\"description\":\"Turn on OAuth so AI tools connect with just the address.\",\"url\":\"https://docs.izumi.akiaconsulting.com/en/install/oauth\",\"mainEntityOfPage\":{\"@id\":\"https://docs.izumi.akiaconsulting.com/en/install/oauth#webpage\"},\"dateModified\":\"2026-11-21T12:41:29.962Z\",\"publisher\":{\"@id\":\"https://docs.izumi.akiaconsulting.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.izumi.akiaconsulting.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Izumi\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Izumi\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/en/install/oauth.md","siteName":"Izumi","nav":{"global":null,"versions":[{"version":"Srpski","default":true,"pages":[{"title":"Srpski","href":"/sr/upoznaj/sta-je-izumi"}]},{"version":"English","tabs":[{"tab":"Meet Izumi","pages":[{"title":"Meet Izumi","href":"/en/overview/what-is-izumi"}]},{"tab":"Using Izumi","pages":[{"title":"Using Izumi","href":"/en/using/search"}]},{"tab":"AI tools (MCP)","pages":[{"title":"AI tools (MCP)","href":"/en/ai-tools/overview"}]},{"tab":"Administration","pages":[{"title":"Administration","href":"/en/admin/people"}]},{"tab":"Installation","groups":[{"group":"Setting up","pages":[{"title":"Requirements","href":"/en/install/requirements"},{"title":"Install","href":"/en/install/install"},{"title":"First sign-in and admin","href":"/en/install/first-admin"},{"title":"Sign-in (Google, Entra)","href":"/en/install/sign-in"},{"title":"Connectors (Google Cloud, Microsoft Graph)","description":"Set up the connectors for sources.","href":"/en/install/connectors"},{"title":"OAuth for MCP clients","href":"/en/install/oauth"},{"title":"TLS","description":"Certificate and HTTPS.","href":"/en/install/tls"},{"title":"Backup and restore","href":"/en/install/backup"},{"title":"Upgrade","href":"/en/install/upgrade"},{"title":"Monitoring","href":"/en/install/monitoring"},{"title":"Running offline","href":"/en/install/offline"}]}]}]}]},"basePath":"","title":"OAuth for MCP clients - Izumi","deploymentId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","buildId":"dpl_DyXGnKeCjZyA3sUdfMJ7FjkdBefg","dynamics":[],"chunks":[]}