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
| 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, unless EMAIL_TRANSPORT=ses. |
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. 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.
| 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 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}/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.