This document covers the authentication API endpoints provided by the Sim platform. These APIs handle user registration, login, session management, email verification, password reset, and OAuth/SSO integration. The authentication system is built on Better Auth with support for multiple authentication methods.
For information about authorization and workspace permissions, see Authentication & Authorization (2.6)
Sources: apps/sim/app/(auth)/login/login-form.tsx1-100 apps/sim/app/(auth)/signup/signup-form.tsx1-100 apps/sim/lib/auth/auth.ts145
The platform uses better-auth as the authentication provider, with additional plugins for SSO (@better-auth/sso), Stripe integration (@better-auth/stripe), and JWT support apps/sim/lib/auth/auth.ts2-21 The authentication core is initialized in lib/auth/auth.ts using a drizzleAdapter connected to the PostgreSQL database via Drizzle ORM apps/sim/lib/auth/auth.ts153-156
The following diagram bridges the Natural Language Space of user actions to the Code Entity Space of better-auth endpoints and components.
Sources: apps/sim/lib/auth/auth.ts145-165 apps/sim/lib/auth/auth.ts178-199 apps/sim/app/(auth)/login/login-form.tsx17 apps/sim/app/(auth)/signup/signup-form.tsx10
Client Method: client.signUp.email(credentials, options) apps/sim/app/(auth)/signup/signup-form.tsx244-250
Creates a new user account. The system validates the email domain against BLOCKED_SIGNUP_DOMAINS before creation in a before hook apps/sim/lib/auth/auth.ts170-175 Upon successful creation, the after hook initializes user stats via handleNewUser and triggers telemetry apps/sim/lib/auth/auth.ts178-199
Password Requirements:
PASSWORD_VALIDATIONS regex in the signup form apps/sim/app/(auth)/signup/signup-form.tsx20-35Sources: apps/sim/app/(auth)/signup/signup-form.tsx114-138 apps/sim/lib/auth/auth.ts167-200 apps/sim/lib/core/config/env.ts27
Client Method: client.signIn.email(credentials, options) apps/sim/app/(auth)/login/login-form.tsx167-172
Authenticates a user. If EMAIL_VERIFICATION_ENABLED is true and the user is not verified, they are redirected to the /verify route apps/sim/app/(auth)/login/login-form.tsx177-180
Sources: apps/sim/app/(auth)/login/login-form.tsx162-210 apps/sim/lib/core/config/env.ts81
Sim Studio features a hierarchical OAuth system defined in OAUTH_PROVIDERS. This maps base providers (e.g., Google) to specific services (e.g., Gmail, Google Drive) with distinct scopes apps/sim/lib/oauth/oauth.ts57-140
| Provider | Services | Example Scopes |
|---|---|---|
| Gmail, Drive, Docs, Sheets, Calendar, Ads, BigQuery | https://www.googleapis.com/auth/drive.file, gmail.modify | |
| Microsoft | Outlook, OneDrive, Excel, Teams, SharePoint | offline_access, Files.ReadWrite, Mail.Send |
| Slack | Slack | channels:read, chat:write, files:write |
Sources: apps/sim/lib/oauth/oauth.ts58-210 apps/sim/lib/oauth/oauth.ts530-650
The system automatically handles OAuth token expiration via refreshAccessTokenIfNeeded apps/sim/app/api/auth/oauth/utils.ts205-209 If a token is expired and a refresh token exists, it calls refreshOAuthToken and updates the account table apps/sim/app/api/auth/oauth/utils.ts145-173
Sources: apps/sim/app/api/auth/oauth/utils.ts110-196 apps/sim/app/api/auth/oauth/utils.ts205-230
SSO integration uses the @better-auth/sso plugin apps/sim/lib/auth/auth.ts2 It supports OIDC and SAML providers. Trusted providers are managed via SSO_TRUSTED_PROVIDERS apps/sim/lib/auth/auth.ts79
For Microsoft OAuth, the system includes a specialized getMicrosoftUserInfoFromIdToken function to extract user details directly from the ID token, avoiding 403 errors in multi-tenant scenarios apps/sim/lib/auth/auth.ts92-130
Sources: apps/sim/lib/auth/auth.ts1-22 apps/sim/lib/auth/auth.ts79 apps/sim/lib/auth/auth.ts92-130
Sessions are configured in lib/auth/auth.ts with the following parameters:
When DISABLE_AUTH is set to true (self-hosted only), the system creates anonymous sessions via createAnonymousSession apps/sim/lib/auth/auth.ts80 This is blocked on the hosted environment for security apps/sim/lib/core/config/feature-flags.ts42-51
Sources: apps/sim/lib/auth/auth.ts157-165 apps/sim/lib/core/config/feature-flags.ts42-61
| Path | Method | Description |
|---|---|---|
/api/auth/sign-up/email | POST | Register new user via Better Auth |
/api/auth/sign-in/email | POST | Authenticate user via Better Auth |
/api/auth/email-otp/verify-email | POST | Verify email using 6-digit OTP apps/sim/app/(auth)/verify/use-verification.ts96-102 |
/api/auth/forget-password | POST | Trigger reset email apps/sim/app/(auth)/login/login-form.tsx303-375 |
/api/auth/reset-password | POST | Update password with token apps/sim/app/(auth)/reset-password/reset-password-form.tsx88-142 |
/api/auth/callback/:provider | GET | OAuth provider redirect target |
Sources: apps/sim/lib/auth/auth.ts145-156 apps/sim/app/(auth)/verify/use-verification.ts87-102
The quickValidateEmail utility performs syntax checks and disposable email domain detection apps/sim/lib/messaging/email/validation.ts1-50 It is used in both login and signup forms apps/sim/app/(auth)/login/login-form.tsx37-40 apps/sim/app/(auth)/signup/signup-form.tsx64-67
The system provides resolveOAuthAccountId to bridge the gap between high-level credential IDs and underlying account records apps/sim/app/api/auth/oauth/utils.ts33-58 This ensures that tool execution always uses the correct authorized account.
Sources: apps/sim/lib/messaging/email/validation.ts1-50 apps/sim/app/api/auth/oauth/utils.ts33-58
Refresh this wiki