Authentication Flow

This document describes the end-to-end authentication flow from user login through API access.

Flow overview

1. User initiates login — client redirects to Cognito hosted UI or custom auth screen
2. Cognito authenticates — validates credentials, MFA if required, returns tokens
3. Client stores tokens — access token, ID token, and refresh token in secure storage
4. API requests — client sends Bearer access token with each request
5. Backend validates — middleware verifies token signature, expiry, and scopes
6. Token refresh — client uses refresh token before access token expires

Token lifecycle

// Client-side token refresh
async function getValidToken() {
  const session = await fetchAuthSession();
  if (session.tokens?.accessToken) {
    return session.tokens.accessToken.toString();
  }
  await signInWithRedirect();
}

Service-to-service auth

Internal services use IAM roles or service account tokens — never user credentials:

curl "$INTERNAL_API/v1/health" \
  -H "Authorization: Bearer $SERVICE_TOKEN"

Security boundaries

• User tokens are scoped to their permissions — never escalate
• Service tokens are scoped to specific internal endpoints
• Admin actions require additional MFA verification
• All auth events are logged for audit