Authentication
Establish 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 flow through the same public backend origin.
Required auth boundary
| Variable | Requirement |
|---|---|
AUTH_SECRET | A stable random value of at least 32 characters. Generate with openssl rand -hex 32. |
AUTH_BASE_URL | The public HTTPS backend origin users and providers can reach. |
AUTH_ALLOWED_ORIGINS | Optional comma-separated extra browser origins. Keep this list narrow. |
SMTP_CONNECTION_URL | Required for email verification, password reset, and invitation email delivery. |
EMAIL_FROM_ADDRESS | The sender address for transactional email. |
AUTH_SECRET protects sessions and encrypted auth material. Do not generate a
new value on every deploy. Rotating it can invalidate sessions and prevent
existing encrypted signing keys from being read; treat rotation as a planned
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
rely on a consistent origin.
Email and password
Email/password sign-in is available by default. Configure SMTP before inviting a team so verification, invitation, and password-reset messages leave the deployment reliably.
With SMTP and EMAIL_FROM_ADDRESS set, new email/password accounts verify
their address before they can sign in. An unverified account that signs in is
sent a fresh link. Resetting a password also verifies the address, and signs
out the account's other sessions. Without SMTP, messages are only logged, so
verification is 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 enabled conditionally - if the corresponding client ID and secret are set in the backend environment, the sign-in option appears.
| Provider | Env vars required |
|---|---|
| GitHub | GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET |
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET | |
| Microsoft | MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET |
GitHub social sign-in credentials are separate from the deployment-owned GitHub App used for repositories and connector writes.
Register each provider callback under AUTH_BASE_URL. Test sign-in through the
same public origin users will 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 are origin-bound.
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.
Configure the client with:
{AUTH_BASE_URL}/mcpEach 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.
| Token | Lifetime |
|---|---|
| Browser session | 30 days |
| OAuth access token | 4 hours, renewed with the refresh token (offline_access) |
OAuth access token with ctxpipe:write | 1 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_SECRETis stable across backend instances and deploys.AUTH_BASE_URLexactly 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.