Skip to main content
LTV.ai uses a multi-layer JWT-based authentication system with distinct token types for different user roles. Each token type has its own signing key and guard.

​
Token Types

Algorithm: HS256 Secret: RETAILER_JWT_PRIVATE_KEY Guard: RetailerAuthGuardClaims:
ClaimDescription
subRetailer ID
aud['retailer']
Stored in cookies via RETAILER_ACCESS_TOKEN_COOKIE_NAME.
Algorithm: HS256 Secret: ADMIN_JWT_PRIVATE_KEY Guard: AdminAuthGuardClaims:
ClaimDescription
fullAccessAdmin privileges flag
aud['retailer']
act.subImpersonated retailer ID (optional)
Admin tokens can impersonate retailers via the act.sub claim.
Guard: ReactivateAuthGuardUsed for all Reactivate module endpoints. The Reactivate module also has its own API key guard (ReactivateApiKeyGuard) for marketing endpoints.
Secret: BRIDGE_JWT_PRIVATE_KEYUsed for cross-service authentication. Exchanged for access/refresh tokens via POST /auth/bridge.
Secret: PORTAL_JWT_PRIVATE_KEY Guard: PortalAuthGuardUsed for merchant portal SSO authentication.

​
API Key Authentication

For service-to-service and reporting API access:
  • Guard: ApiKeyAuthGuard
  • API keys are stored as ApiKey entities linked to a Retailer
  • Used by the Reporting API and external integrations
The Reactivate module has its own API key guard (ReactivateApiKeyGuard) for marketing endpoints.

​
OAuth Integrations

ProviderServicePurpose
ShopifyShopifyOAuthServiceApp installation and merchant auth
BigCommerceCustom OAuth flowApp installation and merchant auth
MicrosoftMSALModuleOutlook/Office365 email account linking
GoogleGoogleOauthServiceGoogle email account linking

​
Password Authentication

  • Algorithm: bcryptjs
  • Use Case: UserRegistersWithPasswordUseCase

​
Multi-Factor Authentication

  • OTP via email - One-time passwords sent to customer email
  • Magic links - Auto-generated authentication links for admin access

​
Auth Flow Diagram

Client Request
    │
    ▼
┌──────────────────┐
│  NestJS Guard    │ ← Validates JWT / API Key
├──────────────────┤
│ RetailerAuthGuard│ → Retailer endpoints
│ AdminAuthGuard   │ → Admin endpoints
│ ApiKeyAuthGuard  │ → Reporting API
│ PortalAuthGuard  │ → Portal endpoints
│ ReactivateAuth   │ → Email automation
└──────────────────┘
    │ (valid)
    ▼
  Controller → Use Case → Response

​
Token Refresh

Tokens are refreshed via POST /auth/refresh. The refresh flow validates the existing token and issues a new access token with an updated expiry.