App bootstrap

/api/bootstrap is how the browser starts its Matrix session. The page loads the static HTML/JS bundle, then on first paint fetches /api/bootstrap to receive the session-shaped payload it needs to connect to NATS and identify the user.

This is a platform endpoint owned by the gateway (not delegated to a package).

Endpoint

GET /api/bootstrap
Accept: application/json

Authentication is via session cookie if present; otherwise the response is the anonymous variant.

Response shape

typescript

{
  natsWsUrl: string,                  // e.g. "wss://hivecast.ai/nats-ws"
  root: string,                        // bus authority root, e.g. "COM.NIMBLETEC.RICHARD-SANTOMAURO"
  authorityRoot: string,               // same as root
  spaceId?: string,                    // when in a Space context
  routeKey?: string,                   // public Space route handle (v1 alias)
  publicNamespace?: string,            // typed namespace (e.g. "space.alt.stories")
  canonicalNamespace?: string,
  canonicalRouteKey?: string,
  platformRoot: string,                // gateway's own root from host.json
  role: 'client',
  addressRoot?: string,                // present when authenticated
  provisioned: boolean,
  authorityReady: boolean,
  authenticated: boolean,
  principal: { principalId, displayName } | null,
  busToken?: string,
  natsOwnership: { mode, source },
  federation: { connected, hubUrl, source },
  transportPlan: {
    protocolVersion: 1,
    kind: 'nats',
    wsMode: 'same-origin-proxy',
    wsPath: '/nats-ws',
    authMode: 'jwt' | 'anonymous',
    authEndpoint: '/api/nats-jwt' | null,
    busAuthMode: 'bus-token' | 'none',
    sessionMode: 'session-cookie' | 'anonymous' | 'local-client',
  },
  sources: {
    root, authorityRoot, routeKey, publicNamespace,
    spaceId, platformRoot, addressRoot,
    browserWsPath, transportAuthMode, busToken, sessionIdentity, federation
  }
}

What each field gives the browser

Field	Used for
`natsWsUrl`	NATS WebSocket URL (always same-origin `/nats-ws` for product builds).
`transportPlan.wsPath`	`/nats-ws`. The browser opens its WS to this path.
`transportPlan.authMode`	`'jwt'` if JWT auth is required, `'anonymous'` for public sessions.
`transportPlan.authEndpoint`	If `authMode === 'jwt'`, the URL to fetch a NATS JWT.
`root` / `authorityRoot`	The browser's bus prefix. Subjects go under this.
`principal`	The current user's identity, if authenticated.
`busToken`	A short-lived token used to authorize bus operations on behalf of the principal.
`sources`	Provenance metadata — for each field above, which subsystem produced it.

Anonymous vs. authenticated

The gateway resolves browser identity from the request (cookies / session service). The bootstrap response shape is the same; specific fields are absent or null when anonymous:

Field	Anonymous	Authenticated
`authenticated`	`false`	`true`
`provisioned`	`false`	`true`
`principal`	`null`	`{ principalId, displayName }`
`addressRoot`	`undefined`	the user's authority root
`authMode`	`'anonymous'` (or `'jwt'` if a public-session JWT path is configured)	`'jwt'`
`sessionMode`	`'anonymous'` or `'local-client'`	`'session-cookie'`

Why the browser needs this

The browser does not know:

which authority root to subscribe under,
which NATS WebSocket URL to open,
whether to present a session cookie or fetch a JWT,
whether it has a principal identity or is anonymous.

These cannot be hard-coded in the static bundle because they depend on the deployment (cloud vs. local), the user (authenticated vs. anonymous), and the Space context (URL-based, derived from the public path).

/api/bootstrap is the single dynamic edge that makes the static bundle usable across deployments.

Edge gateway differences

When the public Edge serves bootstrap, the same shape is returned but with edge-specific source fields:

sources.root may be 'system-auth:publicNamespaces' instead of 'host-service:transport.root'.
transportAuthMode reflects the public-session credential ref.

This is built by host-platform-http-surface.ts in projects/matrix-3/packages/system-gateway-http/src/, lines around 480-580.

App bootstrap ​

Endpoint ​

Response shape ​

What each field gives the browser ​

Anonymous vs. authenticated ​

Why the browser needs this ​

Edge gateway differences ​

See also ​