Authentication

CORTEX uses JWT-based authentication with access and refresh token pairs, combined with server-side session management for enhanced security.

How It Works

┌──────────┐       ┌──────────────┐       ┌──────────────┐
│  Client  │──────▶│   POST       │──────▶│   CORTEX     │
│          │       │  /auth/login │       │   Auth       │
│          │◀──────│              │◀──────│   Service    │
│          │       └──────────────┘       └──────────────┘
│          │                                     │
│          │  { accessToken, refreshToken }      │
│          │                                     │
│          │       ┌──────────────┐              │
│          │──────▶│  GET /users  │──────────────┘
│          │       │  + Bearer    │       Validates JWT
│          │◀──────│  token       │       Checks session
└──────────┘       └──────────────┘       Returns data

Token Architecture

Token	Lifetime	Storage	Purpose
Access Token	15 minutes	Memory/Cookie	Authenticates API requests
Refresh Token	7 days	HTTP-only cookie / Secure storage	Obtains new access tokens

Key Features

Token Rotation

Every time a refresh token is used, both access and refresh tokens are rotated. The old refresh token is invalidated, preventing token reuse attacks.

Session Management

Each login creates a server-side session. Users can view and manage active sessions, and administrators can terminate sessions remotely.

Account Lockout

After 5 failed login attempts within 15 minutes, the account is temporarily locked for 15 minutes. This prevents brute-force attacks while remaining user-friendly.

Password Policy

Passwords must meet these requirements:

• Minimum 8 characters
• At least 1 uppercase letter (A-Z)
• At least 1 lowercase letter (a-z)
• At least 1 number (0-9)
• At least 1 special character (!@#$%^&*)

Endpoints

Method	Endpoint	Auth Required	Description
POST	/auth/register	No	Register new user
POST	/auth/login	No	Authenticate user
POST	/auth/refresh	No	Refresh token pair
POST	/auth/logout	Yes	End session
GET	/auth/me	Yes	Get current user
POST	/auth/change-password	Yes	Change password
GET	/auth/sessions	Yes	List active sessions
DELETE	/auth/sessions/:id	Yes	Terminate session

Security Considerations

1. Stateless Access Tokens — Access tokens cannot be individually revoked. They remain valid until expiration. This is by design for performance.

2. Stateful Refresh Tokens — Refresh tokens are tracked server-side and can be revoked immediately.

3. Cross-Tenant Isolation — Authentication is tenant-scoped. A user in Tenant A cannot authenticate against Tenant B's resources.

4. No Information Leakage — Invalid email and wrong password return the same error message to prevent user enumeration.

JWT Payload Structure

{
  "sub": "550e8400-e29b-41d4-a716-446655440000",
  "email": "john.doe@acme.com",
  "tenantId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "iat": 1705312200,
  "exp": 1705313100
}

Field	Description
sub	User ID (UUID)
email	User's email address
tenantId	User's tenant ID
iat	Issued at timestamp
exp	Expiration timestamp