Authentication

Overview

All products use AWS Cognito (User Pool: us-east-1_75Rp4zNBg) with two token delivery mechanisms:

• httpOnly cookies -- primary mechanism for browser-based dashboards
• Bearer tokens -- used by mobile apps, API clients, and testing

Token Validation

• Algorithm: RS256
• JWKS endpoint rate-limited (5 req/min)
• Token expiration enforced (ID tokens: 1 hour)
• User pool ID verified
• Cognito client: 2u986rkhchk6mur28sgpt0bm8p

httpOnly Cookie Auth

The primary browser auth mechanism uses httpOnly cookies to prevent XSS-based token theft:

Cookie	Purpose	Max-Age	Settings
statux_id_token	JWT identity token	1 hour	httpOnly, Secure, SameSite=Lax
statux_refresh_token	Token refresh	30 days	httpOnly, Secure, SameSite=Lax

Cookie domain: .statux.io (accessible to all product subdomains)

Auth Endpoints

AuthCookieController is registered on all 5 APIs:

Endpoint	Method	Description
/auth/set-cookie	POST	Store tokens in httpOnly cookies (requires valid JWT in body)
/auth/me	GET	Get current user from session (cookie or Bearer)
/auth/refresh	POST	Refresh tokens using refresh cookie
/auth/logout	POST	Clear httpOnly auth cookies

Token Extraction Priority

JwtStrategy extracts tokens in this order:

1. httpOnly cookie statux_id_token (browser requests)
2. Authorization: Bearer header (API clients, mobile, testing)

Token Refresh Flow

1. Browser sends POST /auth/refresh with httpOnly refresh cookie
2. API calls Cognito admin-initiate-auth with REFRESH_TOKEN_AUTH flow
3. Cognito returns new ID token
4. API sets updated statux_id_token cookie

Bearer Token Auth

Mobile apps and API clients use the standard Authorization: Bearer <token> header. The token is a Cognito ID token obtained via:

• Cognito hosted UI (web sign-in)
• Cognito SDK (mobile app)
• admin-initiate-auth (CLI/testing)

Impersonation

Platform admins can impersonate any user by setting the x-impersonate-user-id header on API requests. When impersonating:

• user.userId and user.email reflect the impersonated user
• user.originalUserId and user.originalEmail preserve the admin's real identity
• Requires membership in the Cognito PlatformAdmins group

This enables debugging user-specific issues without sharing credentials.

SCIM Token Auth

SCIM 2.0 provisioning endpoints use a separate auth mechanism:

• Bearer tokens generated via the Platform API and stored as SHA256 hashes in core.scim_tokens
• ScimAuthGuard validates tokens by hashing the incoming token and looking up the hash
• Tokens can be revoked (checked via revokedAt column)
• Each token is scoped to a specific organization

Security Notes

• Cognito client has ALLOW_ADMIN_USER_PASSWORD_AUTH enabled for CI/testing use only (requires AWS IAM credentials, not internet-exposed)
• Refresh tokens expire after 30 days
• Frontend auth (shared/js/auth.js) uses httpOnly cookies exclusively -- no tokens in localStorage or sessionStorage
• All cookie-based auth uses credentials: 'include' for cross-origin requests

Implementation

See API Authentication for code details and guard usage.