REST Authentication & Sessions

BehaviorSim API implements two orthogonal authentication schemes:

• Browser Sessions: Powered by OAuth (Google, GitHub) issuing an encrypted behaviorsim_session HttpOnly cookie.
• Programmatic API Keys: Bearer tokens starting with bs_live_ for backend scripts and CLI clients.

Dual Authentication Model

Protected routes (like /v1/account or /v1/simulations) accept either an authenticated browser session cookie or an Authorization Bearer header.

OAuth 2.0 Web Flow

1. Initiation: Navigating to GET /v1/auth/{provider} (where provider is google or github) generates a CSRF state token and redirects to the identity provider.
2. Callback: Provider redirects back to GET /v1/auth/{provider}/callback with state and code.
3. Session Resolution: API exchanges code for user profile, seeds account if new, creates database session record, and sets behaviorsim_session cookie.
4. Landing Redirect: Redirects browser to the configured frontend destination (/account).

Session Cookie Specifications

Terminating Sessions (Logout)

Issuing POST /v1/auth/logout invalidates the database session and clears the client cookie:

curl -X POST https://api.behavioursim.vedaangsharma.in/v1/auth/logout \
  -H "Accept: application/json" \
  --cookie "behaviorsim_session=..."