Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.second.so/llms.txt

Use this file to discover all available pages before exploring further.

Second supports two authentication modes, controlled by the SECOND_AUTH_MODE environment variable.

​
none mode (local development)

Designed for local development and trusted internal networks. Identity is managed entirely within Second. How it works:
  1. User fills out /onboarding/identity (display name + email).
  2. A local signed session cookie is issued.
  3. Users without workspace memberships are redirected to /onboarding/workspace.
  4. Cookie signatures use an auto-generated process secret — no external config needed.
Do not expose none mode to the public internet. There is no real authentication — anyone who can reach the server can create an identity.
Local mode does not send real workspace invitations. The members UI still shows roles and governance state, but invitation actions explain that external authentication is required. For local multi-user testing, seed a second user into an existing workspace with scripts/local-workspace-member.mjs; the seeded user is added to the workspace’s default General team.

​
external mode (production)

For internet-facing deployments. Second delegates authentication to your own provider. Your provider must:
  • Resolve the authenticated actor on each request
  • Return a stable user identifier
  • Map the identity into Second’s users and membership model
  • Sync workspace memberships and roles into Second’s workspace_memberships
  • Send and reconcile workspace invitations when collaboration is enabled
If external mode is set but no provider extension is present, the app fails fast on startup — you’ll see a clear error rather than silent misbehavior. External providers should map each workspace to the provider’s organization or tenant concept. Accepted invitations must upsert the Second user, upsert the workspace membership with a validated role (owner, admin, or member), and ensure the user belongs to the workspace’s default General team.

​
How auth mode affects authorization

Authentication mode only changes where identity comes from. The authorization flow is the same regardless:
  1. Resolve actor (from session cookie or external provider)
  2. Verify workspace membership
  3. Check any route-level workspace permission
  4. Query scoped by workspaceId
See Guard and Tenancy for the full enforcement model.