Auth

Active contributors: Romit, Sean, Pedro

Purpose

Cal.diy uses NextAuth.js for the web app's authentication: email/password, magic links, Google, GitHub, and (in upstream Cal.com) SAML. The Cal.diy fork removes the EE SSO providers but keeps the core flows. The API v2 (NestJS) has its own auth surface for API keys, OAuth clients, and JWT.

Where it lives

Concern	Code
NextAuth options	packages/features/auth/lib/next-auth-options.ts
Custom Prisma adapter	packages/features/auth/lib/next-auth-custom-adapter.ts
Server session helpers	packages/features/auth/lib/getServerSession.ts, getSession.ts, ensureSession.ts
Identity providers config	packages/features/auth/lib/identityProviders.ts
Outlook OAuth helper	packages/features/auth/lib/outlook.ts
JWT signing	packages/features/auth/lib/signJwt.ts
Password helpers	packages/features/auth/lib/{validPassword,verifyPassword,passwordResetRequest,sendVerificationRequest,verifyEmail,verifyCodeUnAuthenticated}.ts
Permission helpers	packages/features/auth/lib/checkAdminOrOwner.ts
Locale resolution	packages/features/auth/lib/getLocale.ts, getLocaleFromRequest.ts
Auth UI	apps/web/app/auth/, apps/web/modules/auth/, packages/features/auth/signup
API v2 auth	apps/api/v2/src/modules/auth/, apps/api/v2/src/modules/jwt/, apps/api/v2/src/modules/oauth-clients/, apps/api/v2/src/modules/tokens/
API keys (legacy + current)	packages/features/api-keys-legacy, apps/api/v2/src/modules/api-keys

Web (NextAuth) auth flow

sequenceDiagram
    participant Browser
    participant Web as apps/web
    participant NextAuth as NextAuth handler
    participant Adapter as Custom Prisma adapter
    participant DB as PostgreSQL
    participant Email as packages/emails

    Browser->>Web: POST /api/auth/signin
    Web->>NextAuth: handle credentials provider
    NextAuth->>Adapter: getUserByEmail
    Adapter->>DB: SELECT user
    DB-->>Adapter: user row
    NextAuth->>NextAuth: verifyPassword
    alt success
        NextAuth->>Adapter: createSession
        Adapter->>DB: INSERT Session
        NextAuth-->>Browser: Set-Cookie
    else email not verified
        NextAuth->>Email: sendVerificationRequest
        NextAuth-->>Browser: 401
    end

The custom adapter (next-auth-custom-adapter.ts) overrides the default NextAuth adapter to integrate with Cal.diy's User, Session, Account, and Profile models. It enforces email-verification-required behavior, organization auto-acceptance, and the org-aware lookup needed when the same email exists across different tenants.

Sessions in tRPC

packages/trpc/server/createContext.ts calls getServerSession() (packages/features/auth/lib/getServerSession.ts) to populate ctx.session. Authenticated procedures use authedProcedure from packages/trpc/server/procedures/.

Permissions and PBAC

PBAC (permission-based access control) is the model for team and organization permissions. Implementation:

• SQL helpers in packages/prisma/sql/
• Memberships + roles in packages/features/membership
• checkAdminOrOwner.ts for the simple admin/owner check
• More nuanced checks live alongside the resource (e.g., event-type ownership)

API v2 auth

apps/api/v2/src/modules/auth/ implements three flows for the REST API:

• API key — long-lived bearer (Authorization: Bearer cal_...). The legacy package packages/features/api-keys-legacy keeps backward compatibility with v1.
• OAuth 2.0 — for Platform tenants ("OAuth clients"). The oauth-clients and tokens modules implement client registration, token issuance, and refresh.
• JWT — short-lived service-to-service auth.

The RawBodyMiddleware is applied to /v2/auth/oauth2/token because OAuth requires application/x-www-form-urlencoded parsing; this is wired in apps/api/v2/src/app.module.ts.

Integration points

• Cookies — packages/lib/default-cookies.ts standardizes the cookie attributes (samesite, secure, prefix).
• Email — magic-link, verification, and password-reset emails come from packages/emails.
• 2FA — TOTP helpers in packages/lib/totp.ts.
• Watchlist + bot detection on signup — packages/features/watchlist (the famous 4,768-line free-email-domains list) and packages/features/bot-detection.

Entry points for modification

• Add an OAuth provider: append to identityProviders.ts and the next-auth-options.ts providers array.
• Change password rules: edit validPassword.ts.
• Add a permission: extend the membership/role checks in packages/features/membership and packages/prisma/sql/.
• Add an API v2 auth scope: edit apps/api/v2/src/modules/auth/ and update the OAuth-client model.

Related pages

• API v2 — REST auth surface
• Web — NextAuth mount point
• Primitives → User