Authentication

Overview

The Form Platform uses Stytch for user authentication in the dashboard and API keys for programmatic access.

Authentication Methods

1. Stytch Session Authentication (Dashboard)

Used For: Dashboard UI access

Flow:

  1. User logs in via Stytch

  2. Stytch returns session token

  3. Token stored in cookies/localStorage

  4. Token included in API requests

Implementation:

  • Next.js Stytch SDK

  • Session management via cookies

  • Automatic token refresh

  • Protected route groups

2. API Key Authentication (Programmatic)

Used For: Server-side API access

Key Types:

  • Secret Keys: sk_live_... or sk-live-... (legacy)

  • Publishable Keys: pk-live-... (optional, for public forms)

Usage:

Authorization: Bearer sk_live_...

Stytch Integration

Dashboard Authentication

Login Flow:

  1. User visits /login

  2. Stytch authentication UI

  3. User authenticates (email, OAuth, etc.)

  4. Session created

  5. Redirect to dashboard

Session Management:

  • Session stored in cookies

  • Automatic refresh

  • Logout revokes session

User Resolution

Flow:

  1. Session token extracted from request

  2. Stytch API validates token

  3. User data retrieved

  4. Remote user record created/updated

  5. User context available in app

API Key Authentication

Secret Keys

Generation:

  • Created via API or dashboard

  • KMS-encrypted storage

  • Hashed for fast lookup

  • One active key per user/environment

Validation:

  • Lambda authorizer validates key

  • Hash-based lookup (O(1))

  • Returns user ID and environment

  • IAM policy generated

Publishable Keys

Usage:

  • Optional for public form submissions

  • No authentication required

  • Rate limited by IP

  • Format: pk-live-...

Authorization

User Ownership

Resources are scoped by user:

  • Forms belong to users

  • Submissions belong to form owners

  • API keys belong to users

Environment Scoping

All resources are environment-scoped:

  • Forms in specific environments

  • API keys per environment

  • Queries filtered by environment

Session Management

Token Extraction

From Headers:

const authHeader = headers.authorization;
const token = authHeader?.startsWith('Bearer ') 
  ? authHeader.substring(7) 
  : null;

From Cookies:

const cookies = parseCookies(cookieHeader);
const token = cookies['stytch_session'];

Token Validation

Stytch Validation:

const session = await stytchClient.sessions.authenticate({
  session_token: token
});

Next Steps

  • Authorization - Authorization details

  • Security - Security best practices

PreviousSpam ProtectionNextAuthorization

Last updated