Frontend Session And Auth Routes

​

Purpose

​

Terms

​

Deployment host

• frontend.gokboru.in
• 6tumlz9k81r7vzob.fapi.trywacht.xyz

​

Frontend session

​

Active sign-in

• current user
• current organization context
• current workspace context
• JWT tokens returned by GET /session/token

​

Middleware prerequisites

• resolving the deployment from the request host
• reading __session or __dev_session__
• creating a new session when no session exists
• refreshing expired session tokens
• attaching deployment and session data to request locals

​

Session transport

​

Production

• if deployment.BackendHost starts with frontend., that prefix is stripped before setting the cookie domain
• example: frontend.gokboru.in sets cookie Domain=gokboru.in
• example: frontend.x.example.com sets cookie Domain=x.example.com

​

Non-production

• incoming development session can be provided through __dev_session__
• refreshed development session is returned through X-Development-Session

​

Route inventory

​

GET /session

• no backend bearer token is required
• the request must resolve to a valid deployment and session transport

• 200 with the current session in data

• if there is no valid existing session, the request prelude creates one before the handler runs
• this endpoint therefore always reflects the current browser session, not a backend principal

​

GET /session/token

​

Query params

• template: optional JWT template name. Defaults to default

​

Success requirements

• current session exists
• current session has an active sign-in

​

Default token contents

• iss: https://<deployment.BackendHost>
• sub: active user ID
• sid: current session ID
• organization: active organization ID when present
• workspace: active workspace ID when present
• permissions: grouped organization and workspace permissions
• metadata: rendered JWT template metadata when configured

​

Success response

{
  "data": {
    "token": "<signed jwt>",
    "expires": 1770000000000
  },
  "status": 200,
  "message": "",
  "errors": null,
  "session": null
}

​

Failure cases

• 404 template not found
• 404 session not found
• 400 no active sign in
• 500 token rendering or signing failure

​

Important distinction

• __session is the browser session token
• /session/token returns the signed auth JWT used by server-side verification

​

POST /session/switch-sign-in

​

Query params

• sign_in_id required

​

Success behavior

• the sign-in must already belong to the current session
• on success, the session cache is invalidated and the updated session is returned

​

Failure cases

• 400 invalid sign in ID
• 400 sign in ID not found in the current session

​

POST /session/sign-out

​

Query params

• sign_in_id optional

​

Behavior

• if sign_in_id is provided, only that sign-in is deleted
• otherwise all sign-ins for the session are deleted and active_signin_id is cleared

​

Side effects

• session cache is invalidated
• session deletion webhooks are published when applicable

​

Failure cases

• 400 invalid sign in ID
• 400 sign in not found for the current session
• 500 transaction failure

​

POST /session/switch-organization

​

Query params

• organization_id optional

​

Behavior

• if organization_id is omitted or empty, organization and workspace active memberships are cleared
• otherwise the handler validates membership and organization eligibility rules

​

Eligibility checks

• organization membership exists
• per-organization IP allowlist rules when enabled
• per-organization MFA enforcement when enabled
• organization admins bypass those restrictions

​

Failure cases

• 400 no active sign in
• 400 invalid organization ID
• 400 user is not a member of this organization
• 403 IP and/or MFA eligibility failure
• 500 update failure when clearing active organization context

​

POST /session/switch-workspace

​

Query params

• workspace_id optional

​

Behavior

• if workspace_id is omitted or empty, workspace and organization active memberships are cleared
• otherwise the handler validates membership and workspace eligibility rules

​

Eligibility checks

• workspace membership exists
• per-workspace IP allowlist rules when enabled
• per-workspace MFA enforcement when enabled
• workspace admins and organization admins bypass those restrictions

​

Failure cases

• 400 no active sign in
• 400 invalid workspace ID
• 400 user is not a member of this workspace
• 403 IP and/or MFA eligibility failure
• 500 update failure when clearing active workspace context

​

GET /session/ticket/exchange

​

Query params

• ticket required

​

Ticket types currently supported

• impersonation
• agent_access
• webhook_app_access
• api_auth_access

​

Shared validation before type-specific handling

1. ticket is present
2. ticket exists in Redis
3. payload is valid JSON
4. deployment_id in the ticket matches the current deployment

​

Shared failure cases

• 400 missing ticket
• 401 invalid or expired ticket
• 400 invalid deployment ID in ticket
• 401 ticket not valid for this deployment
• 400 invalid ticket type

​

Impersonation ticket behavior

• an existing frontend session is required
• user_id is required
• the target user must exist on the deployment and not be disabled
• the target user cannot already be signed in on the current session
• a new sign-in is created and made active
• the ticket is deleted after successful exchange

• success: true
• message: "Impersonation successful"
• updated session

​

Related SDK consumers

• Next.js Server Auth
• frontend hook packages for React Router and TanStack Router
• app-specific ticket exchange flows for webhook apps, API auth apps, and AI runtime access

​

Source references

• router/session.go
• middleware/prelude.go
• handler/session/handler.go
• handler/session/ticket.go