Feature: Authentication

The API server provides a robust and flexible authentication system designed to handle various user scenarios securely. It uses a passwordless email and code flow, supports anonymous guest access, and manages sessions using JSON Web Tokens (JWT).

Key Authentication Flows

1. Passwordless Email + Code Sign-In

Instead of traditional passwords, the system uses a secure one-time code sent to the user’s email address.

• Requesting a Code (/api/v1/auth/request-code): The client sends the user’s email to this endpoint. The server generates a 6-digit code, stores it temporarily, and emails it to the user.
• Verifying a Code (/api/v1/auth/verify-code): The client sends the user’s email and the 6-digit code. The server validates the code. If correct, it either signs the user in (if they exist) or creates a new account and returns a JWT.

Dashboard Login

The request-code endpoint has a special mode for dashboard logins. If the request includes "isDashboardLogin": true, the server first verifies that the user exists and has the necessary admin or publisher role before sending a code. This prevents unauthorized users from attempting to access the dashboard.

2. Anonymous Guest Sign-In

• Creating a Guest Account (/api/v1/auth/anonymous): When a new user opens the app for the first time, the client can call this endpoint to create a temporary guest account. The server returns a new User object with a guestUser role and a JWT.
• Guest-to-Permanent Conversion: If a guest user decides to sign up with their email, the verify-code flow intelligently handles the conversion. The guest account’s data (like saved preferences) is preserved as the account is upgraded to a standardUser role with the verified email.

3. Session Management with JWT

All authenticated sessions are managed using JSON Web Tokens (JWT).

• Token Generation: Upon successful authentication, the server generates a JWT containing the user’s ID, roles, and an expiration time.
• Authenticated Requests: The client must include this token in the Authorization: Bearer <token> header for all subsequent requests to protected endpoints.
• Middleware: A dedicated authentication middleware on the server is responsible for validating the token on every incoming request.

4. Secure Sign-Out

• Token Invalidation (/api/v1/auth/sign-out): When a user signs out, the client calls this endpoint. The server adds the token’s unique identifier (JTI) to a blacklist, immediately invalidating it even before it naturally expires. This prevents the token from being reused.