Skip to main content
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.

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.

Key rotation

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