Sign-in for apps (OAuth)

Tolgee includes an OAuth 2.1 authorization server. It lets apps sign a user in through the browser instead of asking for an API key. The user sees a consent screen in your Tolgee, clicks Allow, and the app gets a short-lived token. Sign in with Tolgee (OAuth) explains the user's side.

This page covers what you, the operator, need to know.

What is on by default

The authorization server is live as soon as Tolgee knows its own address. That is tolgee.back-end-url, or tolgee.front-end-url when the API and the web app share one origin. With one of them set, the following works without any new setting:

• tolgee login in the Tolgee CLI opens the browser and signs the user in against your instance.
• MCP clients such as Claude Code or VS Code can sign in when they connect to /mcp/developer. An MCP client identifies itself with a small JSON document at an HTTPS URL (a Client ID Metadata Document). Your Tolgee reads that document and shows the client on the consent screen as an unverified app.
• The Tolgee Tools browser extension needs one setting first. See below.

Nothing here gives an app more than the user already has. Every token is checked against the user's live permissions on every request.

Set back-end-url when the API has its own address

The sign-in endpoints live on the API. If your web app and API run on different origins, set tolgee.back-end-url to the API's public address. With only front-end-url set in such a setup, Tolgee publishes sign-in addresses that do not answer, and the apps fail to sign in. Tolgee does not fail at startup over this, so check it once.

Turn the browser extension on

The browser extension is off by default. Not every self-hosted instance wants anyone with the published extension to sign in. Turn it on, then restart Tolgee:

tolgee:
  oauth2:
    browser-extension-enabled: true

That is all for the Tolgee Tools extension from the Chrome Web Store and the Firefox add-on. Tolgee knows their redirect addresses. Only a custom build of the extension needs its own address, which contains the build's ID:

tolgee:
  oauth2:
    browser-extension-enabled: true
    browser-extension-redirect-uris:
      - https://<extension-id>.chromiumapp.org/

Keep the trailing slash. A list you set replaces the published addresses. An empty list keeps them.

Narrow it or turn parts off

Setting	Default	What it does
tolgee.oauth2.cli-enabled	true	Set to false on an instance that will never see the Tolgee CLI.
tolgee.oauth2.browser-extension-enabled	false	Set to true to let the Tolgee Tools browser extension sign users in.
tolgee.oauth2.cimd-enabled	true	Set to false to refuse every app your instance does not know. MCP clients then cannot sign in. Only the CLI and the browser extension can.
tolgee.oauth2.cimd-allowed-hosts	empty	A list of hosts whose documents you accept, for example claude.ai. Empty means any public host.

Why cimd-enabled has a switch: it is the one place where a visitor who is not logged in makes your server fetch a URL of their choosing. Tolgee limits that fetch in several ways. It allows only HTTPS, follows no redirects, caps the size and the time, pins the connection to the address it resolved, refuses private and loopback addresses, and rate limits the endpoint per IP. If you still do not want it, turn it off. The price is that no third-party app can connect without you registering it first, and today the only pre-registered apps are the CLI and the browser extension.

Token lifetimes

Setting	Default
tolgee.oauth2.access-token-validity-minutes	30
tolgee.oauth2.refresh-token-validity-days	30. Each use restarts the window, so this is an idle limit, not a total lifetime.
tolgee.oauth2.consent-validity-seconds	900. How long a user has to click Allow.

What to watch

Tolgee re-reads the document of a connected MCP client when one of its users refreshes a token, at most once every 15 minutes per client. A publisher who takes a document down retires that client. Its next refresh is refused, and an access token it already holds stops working within 30 minutes. One metric is worth a look:

• tolgee.oauth2.cimd.capacity_refusals: how often a document fetch was refused for lack of capacity. Single counts are normal. A steady stream means someone is holding the fetch pool and is worth a look. A refused fetch never counts against the app's publisher.

The full list of settings, including the check interval, the grace window and the per-user cap on connected apps, is in the configuration reference.