# Authentication Flows {#authentication-flows}


Detailed documentation of all authentication flows, including login, passwordless sign-in, workspace switching, and social account linking.


## Login (`POST /auth/login`) {#login-post-authlogin}


The standard email/password login flow includes several security hardening measures:

1. Fetches **all** users matching the email (multi-tenant support).
2. Performs **constant-time password comparison** (`timingSafeEqual`) — prevents timing attacks.
3. **Progressive hash migration** — Legacy bcrypt hashes are automatically re-hashed to scrypt on successful login.
4. Validates employee status (active, not archived).
5. Returns `null` (generic `UnauthorizedException`) if no match — **prevents user enumeration**.
6. Generates both access and refresh tokens on success.



> [!WARNING]
> The login endpoint never reveals whether an email exists in the system. Failed attempts always return a generic `UnauthorizedException`.




## Workspace Sign-In by Email/Password (`POST /auth/signin.email.password`) {#workspace-sign-in-by-emailpassword-post-authsigninemailpassword}


1. Validates email + password against all matching user records.
2. Returns **workspace list** (multi-tenant) instead of direct login.
3. User selects a workspace, then signs in with a workspace-scoped JWT.
4. Rate limited: **5 requests per 60 seconds**.


## Workspace Sign-In by Social (`POST /auth/signin.email.social`) {#workspace-sign-in-by-social-post-authsigninemailsocial}


1. Validates the OAuth token against the provider's API (Google, GitHub, Twitter, Facebook).
2. Looks up linked social accounts to find matching users.
3. Returns workspace list for selection.
4. Rate limited: **5 requests per 60 seconds**.


## Magic Code Sign-In (`POST /auth/signin.email` → `POST /auth/signin.email/confirm`) {#magic-code-sign-in-post-authsigninemail--post-authsigninemailconfirm}


Magic login codes provide passwordless authentication using cryptographically secure codes:

1. Generates a **CSPRNG magic code** (`crypto.randomInt()`, 8-char alphanumeric, 36⁸ ≈ 2.8T combinations).
2. Sends the code via email.
3. User confirms with the code; code is **invalidated after first use**.
4. Configurable expiry via `MAGIC_CODE_EXPIRATION_TIME`.
5. Rate limited: **3 requests per 60 seconds** (send), **5 requests per 60 seconds** (confirm).


### Magic Code Security Properties {#magic-code-security-properties}


- **`crypto.randomInt()`** (CSPRNG) — not `Math.random()`
- **8-character alphanumeric** codes (36⁸ ≈ 2.8 trillion combinations)
- **Configurable expiration** via `MAGIC_CODE_EXPIRATION_TIME` (seconds)
- **Single-use**: Codes are invalidated after first successful verification
- **Per-user scoping**: Codes are set individually per user record
- Magic codes and links are **never logged** in server output


## Workspace Sign-In by Token (`POST /auth/signin.workspace`) {#workspace-sign-in-by-token-post-authsigninworkspace}


1. Validates the short-lived workspace JWT.
2. Checks user/employee status (active, not archived).
3. Generates new access + refresh tokens with full organization context.
4. Updates `lastLoginAt` timestamp.
5. Rate limited: **5 requests per 60 seconds**.


## Social Account Linking (`POST /auth/signup.link.account`) {#social-account-linking-post-authsignuplinkaccount}


1. Validates the OAuth token against the provider.
2. Links the social account to the authenticated user.
3. Rate limited: **3 requests per 60 seconds** (stricter).


## Workspace Switching (`POST /auth/switch-workspace`) {#workspace-switching-post-authswitch-workspace}


1. Validates the user has access to the target workspace/tenant.
2. Verifies user and employee status in the target context.
3. Generates new tokens scoped to the target workspace.
4. Authenticated endpoint (requires valid JWT).


## Organization Switching (`POST /auth/switch-organization`) {#organization-switching-post-authswitch-organization}


1. Validates the user has an active `UserOrganization` record for the target.
2. Verifies employee status in the target organization.
3. Generates new tokens scoped to the target organization.
4. Authenticated endpoint (requires valid JWT).


## Email Verification {#email-verification}


- Verification codes are validated against expiration timestamps.
- Codes are **invalidated** after successful use (cannot be reused).
- Already-verified emails are rejected with a clear error.


## OAuth / Social Login Security {#oauth--social-login-security}


Supported providers: **Google**, **GitHub**, **Twitter/X**, **Facebook**.

- OAuth tokens are **validated server-side** against each provider's API before granting access.
- Social accounts are linked to users via a dedicated `SocialAccountService`.
- Email addresses from OAuth providers are verified before creating or linking accounts.
- The `POST /auth/signup.provider.social` endpoint checks if a user exists by social ID before signup (rate limited: 5/min).


## Related Pages {#related-pages}


- [Token Lifecycle](https://sourcey-gauzy.pages.dev/security/token-lifecycle/index.md) — JWT payload, validation, rotation
- [Password Security](https://sourcey-gauzy.pages.dev/security/password-security/index.md) — hashing, policy, reset flow
- [Rate Limiting](https://sourcey-gauzy.pages.dev/security/rate-limiting/index.md) — per-endpoint limits
- [Security Overview](https://sourcey-gauzy.pages.dev/security/security-overview/index.md) — architecture overview
- [Social Auth Setup](https://sourcey-gauzy.pages.dev/authentication/social-auth/index.md) — OAuth provider configuration