Authentication

Session-Based Auth

Conduits uses NextAuth.js with JWT session tokens stored in cookies. When you log in through the dashboard, a session cookie is set automatically. All subsequent API requests include this cookie.

Sign In

POST /api/auth/callback/dev-credentials
Content-Type: application/x-www-form-urlencoded

email=you@example.com&callbackUrl=/dashboard

In development mode, this creates or finds a user with the given email and returns a session cookie. In production, use the email magic link flow instead.

Get Session

GET /api/auth/session

Returns the current session:

{
  "user": {
    "id": "clxxxxxxxxxxxxxxxxx",
    "email": "you@example.com",
    "name": null
  },
  "expires": "2026-04-20T00:00:00.000Z"
}

Returns {} if not authenticated.

Admin API Key

For the admin status endpoint, use a static API key passed as a query parameter:

GET /api/admin/status?key=YOUR_ADMIN_API_KEY

Set the ADMIN_API_KEY environment variable to enable this. The key is compared using crypto.timingSafeEqual to prevent timing attacks.

CSRF Protection

The HubSpot OAuth flow includes a state parameter stored in Redis with a 10-minute TTL, validated on callback to prevent CSRF attacks.

Telegram Auth Flow

Telegram authentication is a multi-step process handled through dedicated endpoints:

1. POST /api/telegram/connect — Send verification code to phone
2. POST /api/telegram/verify — Verify the code
3. POST /api/telegram/verify-2fa — Submit 2FA password (if enabled)

Each step requires an active session. The Telegram session is encrypted with AES-256-GCM before storage.