Authentication Methods

Email/password sign-in uses Better Auth with Argon2 hashing. Signup requires email verification, and password rules are enforced on the server from resolved template settings.

One-time codes

The Better Auth emailOTP plugin sends six-digit codes, stores hashed codes, permits five attempts and expires codes after two hours. The existing UI uses codes for passwordless login, signup verification and password recovery.

Password recovery

1. Request recovery at /auth/forgot-password.
2. The forgotPassword email contains a code and a link to /auth/otp with the recovery type and email identifier.
3. Submit the code and new password on the OTP form. Successful reset revokes existing sessions and returns to /auth/login.

The flow does not use a standalone /auth/reset-password page. Keep the verification and reset mutation together; do not treat a successful code check as a general-purpose authenticated session.

Google and GitHub sign-in

Set GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET or GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET. Callback URLs use the final site origin:

• /api/auth/callback/google
• /api/auth/callback/github

The visible buttons are controlled by build-time NEXT_PUBLIC_AUTH_GOOGLE_ENABLED and NEXT_PUBLIC_AUTH_GITHUB_ENABLED. Next config derives them from credentials unless explicitly set; rebuild after changing those values. The server still requires valid provider credentials.

Apple and Microsoft sign-in

Apple: create a Services ID associated with an App ID that supports Sign in with Apple. Register your domain and exact HTTPS return URL, /api/auth/callback/apple, using the final NEXT_PUBLIC_SITE_URL origin. Set APPLE_CLIENT_ID to the Services ID and APPLE_CLIENT_SECRET to an ES256 client-secret JWT signed with your Apple private key. The JWT needs your Team ID, Key ID, Services ID, Apple audience, issue time and expiry. Follow Apple's client-secret instructions; expiry cannot exceed roughly six months. Rotate the secret before it expires. Register your sending domains/addresses for Apple private email relay and verify mail delivery to relay addresses.

Microsoft: register a Web application in Microsoft Entra with /api/auth/callback/microsoft on the final site origin. Set MICROSOFT_CLIENT_ID and MICROSOFT_CLIENT_SECRET. Match the registration's supported account types to MICROSOFT_TENANT_ID: common (default) for organizational and personal accounts, organizations for work/school, consumers for personal accounts, or a tenant UUID for a single tenant. Keep the client secret's expiry and rotation schedule with the deployment configuration.

Set NEXT_PUBLIC_AUTH_APPLE_ENABLED=true or NEXT_PUBLIC_AUTH_MICROSOFT_ENABLED=true before building when credentials arrive only at container runtime. Next config otherwise derives the flags from credentials present during the build. The flags contain no secrets and do not replace server credentials. Both credentials must be present before the server registers a provider.

These flows use Better Auth's existing account linking and require a usable email claim. Accounts without one receive the provider's sign-in error; the application does not invent an email address. Before launch, test first and returning sign-ins, canceled authorization, the selected Microsoft account types, and Apple relay mail on the final HTTPS domain. Local configuration checks do not prove those external flows.

See Roles & Permissions.