How Token Authentication Works

1. When you successfully log in or register, the server generates a secure opaque access token.
2. This token must be included in the Authorization header as a Bearer token for all protected endpoints.
3. The token is validated against active sessions stored in the database.
4. Access tokens have an expiration time of 30 minutes from issuance.
5. Refresh tokens are valid for 6 months and can be used to obtain new access tokens.
6. When an access token expires, you can use the refresh token endpoint to obtain a new valid token.
7. Sessions persist across server restarts, ensuring uninterrupted authentication.

Example authorization header:

Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...

How CSRF Protection Works

1. When you log in or register, the server returns a CSRF token along with your authentication token.
2. You must include this CSRF token in the x-csrf-token header for all subsequent mutation requests.
3. Requests without a valid CSRF token will be rejected with a 403 Forbidden response.
4. The CSRF token is validated against the token stored in your active session in the database.
5. CSRF tokens are tied to your session validity and will become invalid when your session expires or you log out.
6. Authentication endpoints themselves are exempt from CSRF protection.

Example authentication response with CSRF token:

{
    "token": "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...",
    "refreshToken": "XYZABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn...",
    "csrfToken": "a8d7f9c6e5b4a3c2d1e0f9a8d7f6c5b4a3",
    "expiresIn": 1800,
    "user": {
        "id": 1,
        "username": "John Doe",
        "email": "john@example.com",
        "typeCode": "SUBS",
        "typeName": "Subscribed",
        "firstName": "John",
        "lastName": "Doe",
        "isActive": true,
        "createdAt": "2023-01-15T08:30:00Z",
        "verifiedAt": "2023-01-15T08:35:00Z",
        "updatedAt": "2023-01-15T08:30:00Z",
        "subscription": null
    }
}

Example request with CSRF protection:

// Request headers
Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...
x-csrf-token: a8d7f9c6e5b4a3c2d1e0f9a8d7f6c5b4a3
Content-Type: application/json

Handle Google OAuth callback and exchange authorization code for tokens

Request Body:

{
    "code": "4/0AfJohXlxxx...",
    "mode": "login",
    "redirectUri": "http://localhost:3000/auth/google/callback"
}

Field Descriptions:

• code (required) - Authorization code received from Google OAuth flow
• mode (required) - Authentication mode, either "login" or "register"
• redirectUri (required) - Redirect URI that must match the one configured in Google Cloud Console

Response (200 OK):

{
    "googleIdToken": "eyJzdWIiOiIxMjM0NTY3ODkw...",
    "message": "Google authentication successful"
}

Error Responses:

{
    "error": "Missing required parameters",
    "message": "code, mode, and redirectUri are required",
    "code": "GOOGLE_AUTH_MISSING_PARAMS"
}

{
    "error": "Invalid mode",
    "message": "mode must be 'login' or 'register'",
    "code": "GOOGLE_AUTH_INVALID_MODE"
}

{
    "error": "Failed to exchange authorization code",
    "message": "Google authentication failed",
    "code": "GOOGLE_AUTH_TOKEN_EXCHANGE_FAILED"
}

{
    "error": "Failed to retrieve user information",
    "message": "Could not get user profile from Google",
    "code": "GOOGLE_AUTH_USER_INFO_FAILED"
}

Notes:

• This endpoint handles the server-side OAuth flow for PWA compatibility
• Exchanges the authorization code for Google tokens and retrieves user information
• Returns a base64-encoded user payload that can be used with existing Google auth endpoints
• The returned googleIdToken can be passed to /api/auth/google/login or /api/auth/google/register
• Requires proper Google Cloud Console configuration with matching redirect URIs
• Client ID and Client Secret must be configured in environment variables

Authenticate with Google ID token

Request Body:

{
    "googleIdToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6..."
}

Response (200 OK):

{
    "token": "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...", // Valid for 30 minutes
    "refreshToken": "XYZABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn...", // Valid for 6 months
    "csrfToken": "a8d7f9c6e5b4a3c2d1e0f9a8d7f6c5b4a3",
    "expiresIn": 1800, // 30 minutes in seconds
    "user": {
        "id": 1,
        "username": "John Doe",
        "email": "john@gmail.com",
        "typeCode": "SUBS",
        "typeName": "Subscribed",
        "firstName": "John",
        "lastName": "Doe",
        "isActive": true,
        "createdAt": "2023-01-15T08:30:00Z",
        "verifiedAt": "2023-01-15T08:35:00Z",
        "updatedAt": "2023-01-15T08:30:00Z",
        "subscription": null
    }
}

Error Responses:

{
    "message": "Invalid Google ID token",
    "code": "AUTH_INVALID_GOOGLE_TOKEN"
}

{
    "message": "No account found with this Google email. Please register first.",
    "code": "AUTH_GOOGLE_USER_NOT_FOUND"
}

Notes:

• Requires a valid Google ID token obtained from Google OAuth2 flow
• User must already have an account with the email from Google profile
• Google users are automatically verified since Google handles email verification
• If user's email is not verified, it will be automatically verified during login
• Last login time is tracked and updated on each successful authentication

Register a new user account with Google ID token

Request Body:

{
    "googleIdToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6..."
}

Response (201 Created):

{
    "token": "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...", // Valid for 30 minutes
    "refreshToken": "XYZABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn...", // Valid for 6 months
    "csrfToken": "f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3",
    "expiresIn": 1800, // 30 minutes in seconds
    "user": {
        "id": 2,
        "username": "John Doe",
        "email": "john@gmail.com",
        "typeCode": "SUBS",
        "typeName": "Subscribed",
        "firstName": "John",
        "lastName": "Doe",
        "isActive": true,
        "createdAt": "2023-01-15T08:30:00Z",
        "verifiedAt": "2023-01-15T08:30:00Z",
        "updatedAt": null,
        "subscription": null
    }
}

Error Responses:

{
    "message": "Invalid Google ID token",
    "code": "AUTH_INVALID_GOOGLE_TOKEN"
}

{
    "message": "Email address is already registered. Please use login instead.",
    "code": "AUTH_EMAIL_EXISTS"
}

Notes:

• Requires a valid Google ID token obtained from Google OAuth2 flow
• User profile data (name, email) is extracted from Google profile
• Google users are automatically verified since Google handles email verification
• No password is required as authentication is handled by Google
• If user already exists with the email, use the login endpoint instead
• Account type is automatically set to 'GOOG' (Google OAuth) for Google registrations
• Last login time is tracked and updated on each successful authentication

Log in with email and password

Request Body:

{
    "email": "user@example.com",
    "password": "yourpassword"
}

Response (200 OK):

{
    "token": "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...", // Valid for 30 minutes
    "refreshToken": "XYZABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn...", // Valid for 6 months
    "csrfToken": "a8d7f9c6e5b4a3c2d1e0f9a8d7f6c5b4a3",
    "expiresIn": 1800, // 30 minutes in seconds
    "user": {
        "id": 1,
        "username": "John Doe",
        "email": "john@example.com",
        "typeCode": "SUBS",
        "typeName": "Subscribed",
        "firstName": "John",
        "lastName": "Doe",
        "isActive": true,
        "createdAt": "2023-01-15T08:30:00Z",
        "verifiedAt": "2023-01-15T08:35:00Z",
        "updatedAt": "2023-01-15T08:30:00Z",
        "subscription": null
    }
}

Error Responses:

{
    "message": "Invalid credentials",
    "code": "AUTH_INVALID_CREDENTIALS"
}

{
    "message": "Your email address has not been verified. A verification code has been sent to your email address.",
    "code": "AUTH_EMAIL_NOT_VERIFIED"
}

Log out the current user (invalidate token)

Headers (Optional):

Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...

Note: Authorization header is optional. If provided, the specific session will be invalidated. If not provided, logout will still succeed.

Response (200 OK):

{
    "success": true,
    "message": "Logged out successfully"
}

Refresh authentication token when the current one is about to expire or has expired. Both endpoints are supported for compatibility.

Headers (Optional):

Authorization: Bearer [current_access_token_or_refresh_token]

Request Body (Optional - takes priority if provided):

{
    "refreshToken": "XYZABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn..."
}

Notes:

• If refreshToken is provided in the request body, it will be used instead of the token from the Authorization header
• If no request body is provided, the Authorization header token will be used
• The endpoint accepts both access tokens and refresh tokens
• Does not require CSRF token - auth endpoints are exempt from CSRF protection
• /api/auth/refresh-token is the legacy endpoint, /api/auth/refresh is preferred

Response (200 OK):

{
    "token": "DEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstu...", // New token valid for 30 minutes
    "refreshToken": "XYZABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn...", // New refresh token valid for 6 months
    "csrfToken": "f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3", // New CSRF token
    "expiresIn": 1800, // 30 minutes in seconds
    "user": {
        "id": 1,
        "username": "John Doe",
        "email": "john@example.com",
        "typeCode": "SUBS",
        "typeName": "Subscribed",
        "firstName": "John",
        "lastName": "Doe",
        "isActive": true,
        "createdAt": "2023-01-15T08:30:00Z",
        "verifiedAt": "2023-01-15T08:35:00Z",
        "updatedAt": "2023-01-15T08:30:00Z",
        "subscription": null
    }
}

Error Responses:

{
    "message": "No token provided",
    "code": "AUTH_NO_TOKEN"
}

{
    "message": "Invalid token format",
    "code": "AUTH_INVALID_TOKEN_FORMAT"
}

{
    "message": "No active session found. Please log in again.",
    "code": "AUTH_SESSION_NOT_FOUND",
    "requiresLogout": true
}

{
    "message": "Your session has been revoked. Please log in again.",
    "code": "AUTH_SESSION_REVOKED",
    "requiresLogout": true
}

{
    "message": "Your session has expired. Please log in again.",
    "code": "AUTH_REFRESH_EXPIRED",
    "requiresLogout": true
}

{
    "message": "User account issue. Please log in again.",
    "code": "AUTH_USER_NOT_FOUND",
    "requiresLogout": true
}

{
    "message": "Authentication error. Please log in again.",
    "code": "AUTH_ERROR",
    "requiresLogout": true
}

Register a new user account

Request Body:

{
    "username": "johnsmith",
    "email": "john@example.com",
    "password": "securePassword123",
    "firstName": "John",
    "lastName": "Smith"
}

Field Descriptions:

• username (required) - User's display name, will be trimmed of whitespace
• email (required) - Valid email address, must be unique
• password (required) - Must be at least 8 characters long
• firstName (optional) - User's first name, max 50 characters
• lastName (optional) - User's last name, max 50 characters

Response (201 Created):

{
    "token": "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...", // Valid for 30 minutes
    "refreshToken": "XYZABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmn...", // Valid for 6 months
    "csrfToken": "f9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3",
    "expiresIn": 1800, // 30 minutes in seconds
    "user": {
        "id": 2,
        "username": "johnsmith",
        "email": "john@example.com",
        "typeCode": "SUBS",
        "typeName": "Subscribed",
        "firstName": "John",
        "lastName": "Smith",
        "isActive": true,
        "createdAt": "2023-01-15T08:30:00Z",
        "verifiedAt": null,
        "updatedAt": null,
        "subscription": null
    }
}

Error Responses:

{
    "message": "Email address is already registered",
    "code": "AUTH_EMAIL_EXISTS"
}

{
    "message": "Validation error",
    "code": "VALIDATION_ERROR",
    "errors": [
        {
            "type": "field",
            "value": "",
            "msg": "Username is required",
            "path": "username",
            "location": "body"
        }
    ]
}

Notes:

• After successful registration, a verification email is sent to the provided address
• Users must verify their email before they can log in
• All field validation is performed server-side with detailed error messages
• The response includes immediate access tokens for authenticated API calls
• Account type is automatically set to 'EMAI' (Email) for traditional registrations
• Last login time is tracked and updated on each successful authentication

Request a password reset code

Request Body:

{
    "email": "user@example.com"
}

Response (200 OK):

{
    "message": "Password reset code has been sent to your email address"
}

Error Responses:

{
    "message": "Email address not found"
}

Notes:

• If the email address is not found, the endpoint returns a 400 error
• For security, the response message doesn't explicitly reveal if an email exists in the system
• A 6-digit verification code is sent to the email address if found
• Previous reset requests for the user are cleared when a new request is made

Verify user's current password (requires authentication and CSRF token)

Headers:

Authorization: Bearer ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqr...
x-csrf-token: a8d7f9c6e5b4a3c2d1e0f9a8d7f6c5b4a3

Request Body:

{
    "password": "currentUserPassword"
}

Response (200 OK):

{
    "message": "Password verified successfully"
}

Error Responses:

{
    "message": "Authentication required"
}

{
    "message": "Password is required"
}

{
    "message": "Invalid password"
}

{
    "message": "Account has been deactivated"
}

{
    "message": "Password verification is not available for Google accounts"
}

Notes:

• This endpoint is useful for confirming user identity before sensitive operations
• Requires both authentication (Bearer token) and CSRF token
• Google OAuth users cannot use this endpoint as they don't have passwords
• Useful for password change workflows, account deletion confirmation, etc.

Verify a registration with the verification code

Request Body:

{
    "email": "user@example.com",
    "verificationCode": "123456"
}

Response (200 OK):

{
    "message": "Email verified successfully"
}

Error Responses:

{
    "message": "Invalid email address"
}

{
    "message": "No verification request found"
}

{
    "message": "Maximum attempts exceeded"
}

{
    "message": "Verification code has expired"
}

{
    "message": "Invalid verification code"
}

Notes:

• Verification codes expire after 1 week from creation
• Maximum of 5 attempts allowed per verification request
• Once verified, the user can log in without restrictions

Reset password using verification code

Reset password using verification code

Request Body:

{
    "email": "user@example.com",
    "verificationCode": "123456",
    "newPassword": "newSecurePassword"
}

Response (200 OK):

{
    "message": "Password has been successfully reset"
}

Error Responses:

{
    "message": "Password must be at least 8 characters long"
}

{
    "message": "Invalid email address"
}

{
    "message": "No password reset request found"
}

{
    "message": "Maximum attempts exceeded. Please request a new verification code"
}

{
    "message": "Verification code has expired. Please request a new one"
}

{
    "message": "Invalid verification code"
}

Notes:

• Password must be at least 8 characters long
• Verification codes expire after 1 week from creation
• Maximum of 5 attempts allowed per reset request
• After successful password reset, all existing sessions for the user are invalidated
• The reset request is cleared after successful password change