Session Bootstrap API

Overview

The widget uses ingestion-side sessions to bind the browser tab to a district and preload the latest available report context.

Direct ingestion paths:

• POST /sdac/sessions
• GET /sdac/sessions/{session_id}

Widget same-origin paths:

• POST /api/ingestion/sdac/sessions
• GET /api/ingestion/sdac/sessions/{session_id}

Authentication and Access Model

These ingestion routes do not perform APIM bearer-token or subscription-key validation themselves.

• Browser clients should call the widget same-origin proxy at /api/ingestion/sdac/sessions....
• Direct /sdac/sessions... access should stay behind private networking, host-application controls, or reverse-proxy authentication.
• Do not expose these routes directly to untrusted browser clients.

Create or Resume Session

Attribute	Value
Endpoint	POST /sdac/sessions
Content-Type	application/json
Response	JSON

Request

{
  "district_id": "12345",
  "user_id": "auditor-001",
  "user_email": "auditor@state.gov",
  "user_name": "Alex Auditor",
  "user_role": "State Auditor"
}

Field	Type	Required	Description
district_id	string	Yes	Host application district identifier
user_id	string	No	User identifier
user_email	string	No	User email
user_name	string	No	Display name
user_role	string	No	Role label

Response

{
  "session_id": "4ad3e575-5d75-48ea-b010-6d09136f8177",
  "district_id": "12345",
  "expires_at": "2026-03-30T22:12:00.000Z",
  "is_new": true,
  "report_id": "8201EDC2-2EDE-4CA1-AF44-D0F5AA185CDB",
  "district_name": "Maplewood Richmond Heights",
  "quarter": "Q1",
  "year": 2026
}

Field	Description
session_id	Session identifier persisted by the client
expires_at	Session expiry timestamp
is_new	Whether the request created a new session
report_id	Latest resolved report for the district when available
district_name	Resolved district display name when available
quarter	Latest resolved quarter when available
year	Latest resolved year when available

Notes

• The service may resume an active district-scoped session instead of creating a new one.
• Session creation also attempts to resolve or ingest the latest report for the district by using the District Sync API.
• Session TTL is currently eight hours by default and is extended on access.

Side Effects

• If an active session already exists for the same district_id and user_id pair, the service reuses it and extends its expiry.
• If no active session exists, the service inserts a new session row in the ingestion database.
• After creating or resuming the session, the service attempts a district sync to resolve report_id, district_name, quarter, and year. A sync failure does not fail the session response; it leaves those fields null or omitted.

Error Cases

Status	Description
200	Session created or resumed successfully
500	Session persistence failed before a session response could be returned

Validate Session

Attribute	Value
Endpoint	GET /sdac/sessions/{session_id}
Response	JSON

Path Parameters

Parameter	Type	Required	Description
session_id	string	Yes	Session identifier returned by the create route

Success Response

{
  "session_id": "4ad3e575-5d75-48ea-b010-6d09136f8177",
  "district_id": "12345",
  "user_id": "auditor-001",
  "user_email": "auditor@state.gov",
  "user_name": "Alex Auditor",
  "user_role": "State Auditor",
  "expires_at": "2026-03-30T22:12:00.000Z"
}

Expired or Missing Session

{
  "error": "Session not found or expired"
}

This returns 404.

Side Effects

• Successful validation touches LastAccessedUtc and extends the session expiry window.

Error Cases

Status	Description
200	Session exists, is active, and its expiry was extended
404	Session was missing, inactive, or expired
500	Session lookup failed unexpectedly

Related Pages

Widget Integration

Browser, iframe, and proxy architecture

Chat Sessions

Conversation persistence inside the chat API itself