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