Well-Known Endpoints

The engine exposes well-known endpoints under /.well-known/rstream/ for session-aware HTTP integrations. These endpoints are served by the engine on active HTTP tunnel hosts and are not forwarded upstream.

The endpoints are intended for applications that need to display authentication state or trigger logout while keeping the actual edge-authentication logic in rstream.

Session endpoint

/.well-known/rstream/session accepts GET and HEAD. Responses use Cache-Control: no-store and Content-Type: application/json.

When authentication cannot be resolved, the response is:

{
  "auth": {
    "authenticated": false
  }
}

When authentication succeeds, the response includes the authentication method, the user profile known to rstream, tunnel identifiers, and the active edge policies:

{
  "auth": {
    "authenticated": true,
    "method": "rstream-auth"
  },
  "user": {
    "userId": "user-id",
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "image": null
  },
  "tunnel": {
    "host": "api-f587ee53.t.aws-eu-west-3-1.c.rstream.io",
    "workspaceId": "workspace-id",
    "projectId": "project-id"
  },
  "policies": ["token-auth", "rstream-auth"]
}

The user.name, user.email, and user.image fields can be null when profile data is unavailable.

Logout endpoint

/.well-known/rstream/logout accepts POST. It clears the engine-issued rstream Auth session cookie when the request is authenticated through rstream Auth, and returns 204 No Content. For token-authenticated or unauthenticated requests, logout is a no-op and still returns 204.

The handler accepts an empty body or Content-Type: application/json. When Origin or Referer is present, it must match the tunnel origin.

await fetch("/.well-known/rstream/logout", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  credentials: "include",
});

Authentication precedence

When token auth and rstream Auth are both enabled, the engine checks the token first. Tokens can be supplied through the Authorization: Bearer <token> header or the rstream.token query parameter. If token authentication is missing or invalid and rstream Auth is enabled, the engine falls back to the rstream session cookie.