Configuration

Authentication

Set the public auth origin, protect signing secrets, and choose sign-in methods for self-hosted ctxpipe.

ctxpipe uses Better Auth for identity management. All browser sign-in, provider callbacks, sessions, and MCP OAuth go through the same public backend origin.

Required auth boundary

VariableRequirement
AUTH_SECRETA stable random value of at least 32 characters. Generate with openssl rand -hex 32.
AUTH_BASE_URLThe public HTTPS backend origin users and providers can reach.
AUTH_ALLOWED_ORIGINSOptional comma-separated extra browser origins. Keep this list narrow.
SMTP_CONNECTION_URLRequired for email verification, password reset, and invitation email delivery, unless EMAIL_TRANSPORT=ses.
EMAIL_FROM_ADDRESSThe sender address for transactional email.

AUTH_SECRET protects sessions and encrypted auth material. Do not generate a new value on every deploy. A rotation can invalidate sessions. It can also prevent ctxpipe from reading the encrypted signing keys that you have. Plan each rotation as an operational change.

One public origin

Open the product through AUTH_BASE_URL. Do not send browser users directly to the private UI service. Provider callbacks, MCP OAuth, cookies, and the API need one consistent origin.

Email and password

Email/password sign-in is available by default. Set up SMTP before you invite a team. Then verification, invitation, and password-reset messages leave the deployment reliably.

When you set SMTP and EMAIL_FROM_ADDRESS, a new email/password account must verify its address before it can sign in. ctxpipe sends a fresh link to an unverified account that signs in. A password reset also verifies the address. It signs out the other sessions of the account. Without SMTP, ctxpipe only logs the messages. Verification is then not required, and the backend logs a warning at startup.

Social providers (OAuth)

ctxpipe supports GitHub, Google, and Microsoft social sign-in. Each provider is on only when you set its client ID and secret in the backend environment. Then the sign-in option shows.

ProviderEnv vars required
GitHubGITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET
GoogleGOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
MicrosoftMICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET

GitHub social sign-in credentials are separate from the GitHub App that your deployment owns. That App gives access to repositories and writes connector content.

Register each provider callback under AUTH_BASE_URL. Test sign-in through the same public origin that users use in production.

Passkeys and two-factor authentication

Passkeys are available on compatible browsers and platforms. Users can also enable TOTP two-factor authentication with a standard authenticator app. Verify both through your production TLS domain. WebAuthn credentials belong to one origin.

MCP OAuth and API keys

ctxpipe is an OAuth provider for downstream MCP clients. It supports discovery, dynamic client registration, and device authorization for compatible headless clients.

Give the client this URL:

{AUTH_BASE_URL}/mcp

Each OAuth grant holds a set of organizations. The user selects the organizations on the consent screen, and the user can change the set later on the Connected apps page (/.auth/account/connected-apps). Each tool call names one organization with the org argument. The server allows the call only when the organization is in the grant set and the user is still a member of it.

For the old ?orgSlug= URL parameter, see MCP.

OAuth is the normal MCP flow for people. The consent screen grants ctxpipe:read and offline_access. It also offers Also allow changes (ctxpipe:write) when a client asks for it. The MCP tools need only ctxpipe:read. API keys never hold ctxpipe:write.

TokenLifetime
Browser session30 days
OAuth access token4 hours, renewed with the refresh token (offline_access)
OAuth access token with ctxpipe:write1 hour

API keys are stored in the database of this deployment, so there is no operator secret to configure. For personal and organization keys, the headers, and the client setup, see API keys. When discovery or authorization fails, see MCP diagnostics.

Production checks

  • AUTH_SECRET is stable across backend instances and deploys.
  • AUTH_BASE_URL exactly matches the browser origin.
  • Provider callbacks use HTTPS and the same host.
  • Extra trusted origins are explicit rather than wildcarded.
  • SMTP can deliver invitation and reset messages.
  • Passkey registration and TOTP sign-in work on the production domain.
  • An MCP client can discover OAuth and complete authorization.