OAuth Configuration#

KaisouMail uses same-origin /api callbacks for GitHub and LinuxDO login / registration. In production, configure OAuth callbacks on the control-plane domain, not the direct API domain.

Recommended callback URLs#

Open /users?section=registration in the control plane and expand GitHub or LinuxDO to copy the callback for the current instance:

Provider	Callback URL
GitHub	https://<control-plane-domain>/api/auth/github/callback
LinuxDO	https://<control-plane-domain>/api/auth/linuxdo/callback

If one deployment has multiple control-plane aliases, each alias has its own same-origin callback. Register only the domain users should use, or add every live control-plane callback when multiple aliases must support login.

GitHub OAuth App#

Configure the GitHub OAuth App with:

• Homepage URL: the control-plane home page, for example https://km.example.com
• Authorization callback URL: https://km.example.com/api/auth/github/callback

Then save the GitHub client values in the control plane:

• /users?section=registration -> GitHub -> Client ID
• /users?section=registration -> GitHub -> Client Secret
• The default scope is read:user; extend it only when the deployment policy requires more profile data

Worker runtime variables remain available as fallback configuration:

• GITHUB_CLIENT_ID
• GITHUB_CLIENT_SECRET
• GITHUB_OAUTH_SCOPES

Settings saved in the control plane take precedence over runtime variables. Saved secrets are never echoed back.

LinuxDO OAuth Client#

Configure the LinuxDO OAuth Client with:

• Application home / Redirect base: the control-plane home page, for example https://km.example.com
• Callback / Redirect URI: https://km.example.com/api/auth/linuxdo/callback

Then save the LinuxDO client values in the control plane:

• /users?section=registration -> LinuxDO -> Client ID
• /users?section=registration -> LinuxDO -> Client Secret

The system uses the default LinuxDO OAuth service URL, https://connect.linux.do. It is not editable in the control plane; deployers only need to override it through Worker runtime variables when targeting a compatible environment or if LinuxDO changes the OAuth issuer.

Worker runtime variables remain available as fallback configuration:

• LINUXDO_CLIENT_ID
• LINUXDO_CLIENT_SECRET
• LINUXDO_OAUTH_BASE_URL

Why the callback uses the control-plane origin#

The KaisouMail Pages control plane forwards /api/* to the API Worker through a same-origin proxy. OAuth state, session cookies, and registration completion redirects all follow the same origin the user opened, so the callback should stay under the control-plane domain:

• It avoids bouncing the browser between the control-plane domain and direct API domain
• It reduces cookie, CORS, and preview-domain mistakes
• It matches the redirect_uri generated by /api/auth/{provider}/start

Keep direct API domains for automation or compatibility clients, but do not use them as the default first-party browser OAuth callback.