This document covers the authentication and authorization systems in the Sim platform, including user identity management, OAuth integrations, session handling, role-based access control, and security policies. The platform uses better-auth as its core authentication framework with support for multiple authentication methods and a comprehensive OAuth integration system.
For information about API endpoint authentication patterns, see API Layer. For workspace-level permissions and usage limits, see Rate Limiting & Usage Quotas.
The Sim platform implements a multi-layered authentication and authorization system:
Sources: apps/sim/lib/auth/auth.ts1-81 apps/sim/next.config.ts1-11
The platform uses better-auth v1.3.12 as its authentication framework, configured in apps/sim/lib/auth/auth.ts145-165 The auth instance includes:
| Configuration | Value | Purpose |
|---|---|---|
| Base URL | getBaseUrl() | Application URL for redirects apps/sim/lib/auth/auth.ts146 |
| Database | Drizzle adapter (PostgreSQL) | User and session persistence apps/sim/lib/auth/auth.ts153-156 |
| Session Expiry | 30 days | Maximum session lifetime apps/sim/lib/auth/auth.ts162 |
| Session Update Age | 24 hours | Frequency of session refresh apps/sim/lib/auth/auth.ts163 |
| Session Fresh Age | 1 hour | Period before revalidation needed apps/sim/lib/auth/auth.ts164 |
| Cookie Cache | 24 hours | Client-side session cache duration apps/sim/lib/auth/auth.ts158-161 |
Plugins Enabled apps/sim/lib/auth/auth.ts10-21:
organization - Multi-tenant organization support.customSession - Extended session data.emailOTP - One-time password authentication.jwt - JSON Web Token generation.oidcProvider - OpenID Connect provider capabilities.genericOAuth - Custom OAuth provider support.oneTimeToken - Magic link authentication.sso - SAML/SSO integration.stripe - Billing integration hooks.Sources: apps/sim/lib/auth/auth.ts145-165 apps/sim/lib/auth/auth.ts10-21
The following diagram illustrates how various authentication methods interface with the core betterAuth system and the underlying database schema defined via Drizzle ORM in packages/db/schema.ts.
Sources: apps/sim/lib/auth/auth.ts145-165 apps/sim/lib/auth/auth.ts80 packages/db/schema.ts32-114
Controlled by the isEmailPasswordEnabled feature flag apps/sim/lib/core/config/feature-flags.ts71 When enabled, users can register via SignupFormContent apps/sim/app/(auth)/signup/signup-form.tsx72 and sign in via LoginPage apps/sim/app/(auth)/login/login-form.tsx72 Registration includes domain blocking logic in the user.create.before hook apps/sim/lib/auth/auth.ts168-177
Email Verification: Controlled by isEmailVerificationEnabled apps/sim/lib/core/config/feature-flags.ts36 When enabled, the useVerification hook manages the OTP flow apps/sim/app/(auth)/verify/use-verification.ts32
Sources: apps/sim/lib/core/config/feature-flags.ts36-71 apps/sim/lib/auth/auth.ts168-177 apps/sim/app/(auth)/signup/signup-form.tsx72 apps/sim/app/(auth)/verify/use-verification.ts32
The platform supports over 50 OAuth providers through the genericOAuth plugin. Each provider is configured in the OAUTH_PROVIDERS registry apps/sim/lib/oauth/oauth.ts57-210
Major Provider Categories:
Sources: apps/sim/lib/oauth/oauth.ts57-210 apps/sim/lib/oauth/types.ts1-53
This diagram bridges the visual UI components like OAuthRequiredModal to the backend OAUTH_PROVIDERS configuration and token storage in the account table.
Sources: apps/sim/app/workspace/[workspaceId]/w/[workflowId]/components/panel/components/editor/components/sub-block/components/credential-selector/components/oauth-required-modal.tsx:37-127, apps/sim/lib/oauth/oauth.ts57-60 apps/sim/lib/auth/auth.ts74 apps/sim/lib/oauth/utils.ts13-142
The platform implements custom logic for complex identity providers:
getMicrosoftRefreshTokenExpiry to ensure continuous connectivity apps/sim/lib/auth/auth.ts84Sources: apps/sim/lib/auth/auth.ts92-130 apps/sim/lib/auth/auth.ts84
The customSession plugin extends standard session data with organization and workspace context apps/sim/lib/auth/auth.ts14 This allows the application to track the activeOrganizationId in the session table packages/db/schema.ts61
Sources: apps/sim/lib/auth/auth.ts14-21 packages/db/schema.ts48-70
For features like public chat deployments or form triggers, the system supports anonymous sessions via createAnonymousSession and ensureAnonymousUserExists apps/sim/lib/auth/auth.ts80
Sources: apps/sim/lib/auth/auth.ts80
The platform implements route-specific CSP policies defined in apps/sim/lib/core/security/csp.ts apps/sim/next.config.ts4-9
| Route Pattern | CSP Policy Function | Purpose |
|---|---|---|
| Main App | getMainCSPPolicy() | Standard application security apps/sim/next.config.ts7 |
| Workflow Execution | getWorkflowExecutionCSPPolicy() | Relaxed for dynamic tool execution apps/sim/next.config.ts8 |
| Form Embed | getFormEmbedCSPPolicy() | Security for embedded forms apps/sim/next.config.ts6 |
| Chat Embed | getChatEmbedCSPPolicy() | Security for embedded AI chat apps/sim/next.config.ts5 |
Sources: apps/sim/next.config.ts4-9
API routes include comprehensive CORS headers to support cross-origin execution and tool interaction apps/sim/next.config.ts145-230
/api/workflows/:id/execute allow cross-origin requests (Access-Control-Allow-Origin: *) to enable external triggers apps/sim/next.config.ts222-224Access-Control-Allow-Credentials: false for security when using wildcard origins apps/sim/next.config.ts176-186Sources: apps/sim/next.config.ts145-230
| Code Entity | File Path | Role |
|---|---|---|
auth | apps/sim/lib/auth/auth.ts145 | Main Better-Auth server-side instance |
OAUTH_PROVIDERS | apps/sim/lib/oauth/oauth.ts57 | Registry of all supported OAuth integrations |
user | packages/db/schema.ts32 | User table schema definition |
session | packages/db/schema.ts48 | Session table schema definition |
account | packages/db/schema.ts72 | OAuth account/token storage schema |
reinitializeAfterLogin | apps/sim/stores/index.ts159 | Resets client-side Zustand stores after login |
Sources: apps/sim/lib/auth/auth.ts1-165 apps/sim/lib/oauth/oauth.ts57-60 packages/db/schema.ts32-98 apps/sim/stores/index.ts159-182
Refresh this wiki