Auth Overview

PreviousNext

Overview of Zooly authentication system

What is Zooly Auth?

Zooly Auth is a centralized authentication and authorization system built on AWS Cognito. It provides single sign-on (SSO) across all *.zooly.ai applications, serving as the identity provider for the entire platform.

Key Features

  • Single Sign-On: One login works across all *.zooly.ai apps
  • Multiple Auth Methods: Email/password, Google and Apple (Google implemented)
  • Long-Lived Sessions: Users stay signed in for up to 3 months
  • Guest Checkout: Support for email-only purchases without registration
  • Role-Based Authorization: Flexible role management via DynamoDB
  • Popup Login: No-redirect login in a popup window for *.zooly.ai apps and localhost

Architecture Overview

Zooly Auth uses a centralized authentication app at auth.zooly.ai that handles all authentication flows. Other apps redirect unauthenticated users to this central app, which manages:

  • AWS Cognito User Pool: Identity provider for user authentication
  • DynamoDB: Stores user profiles, roles, and guest identities
  • Session Cookies: Shared across all *.zooly.ai subdomains
  • JWT Tokens: ID tokens for backend API authorization

How It Works

  1. User visits an app → If not authenticated, redirected to auth.zooly.ai?returnTo=<original-url>
  2. User authenticates → Cognito validates credentials (email/password or social login)
  3. Session created → Both ID token and refresh token stored in cookies with domain .zooly.ai
  4. User redirected back → Returns to original app with valid session
  5. Apps verify session → Backend validates JWT and checks roles from DynamoDB
  6. Automatic refresh → When ID token expires (24 hours), server automatically refreshes using refresh token (transparent to user)
  7. Long-lived sessions → Users stay logged in for up to 90 days without re-authentication

Apps that don't want a full-page redirect can instead open auth.zooly.ai/popup in a popup window (via loginWithPopup() from @zooly/auth-client); the popup runs the same Cognito flow and signals success back to the calling window instead of redirecting it.

Identity Storage

Identity data is split between two systems:

  • Cognito: Email (source of truth), authentication credentials
  • DynamoDB: Profile data (display_name, avatar_url, roles, guest_email)

This separation ensures email changes in Cognito are immediately reflected without stale data in DynamoDB.

Next Steps