Stateway Frontend Gateway

The Stateway Frontend Gateway lets your frontend interact directly with running process instances — without building a dedicated backend layer for user task delivery.

Instead of your backend querying Stateway, determining which task a user should see, and relaying state to the frontend, the Gateway handles this automatically: when the SDK connects, it resolves the user's pending work — by direct assignment, individual nomination (candidateUsers), or group membership (candidateGroups) — and delivers tasks in real time via WebSocket.

When to Use

Use the Frontend Gateway when:

• End users need to interact with human steps of processes (fill out forms, approve requests, review data)
• You want real-time push notifications about process progress without polling
• You want to reduce orchestration code in your backend

Continue using the REST API directly when:

• You need to create or version process definitions (administrative operations)
• You are integrating backend-to-backend systems (webhooks, service tasks)
• You are building AI agents (use the MCP server)

How It Works

YOUR BACKEND                STATEWAY                   YOUR FRONTEND
     │                          │                           │
[authenticate user]             │                           │
     │                          │                           │
     ├── POST /v1/sessions ─────>                           │
     │<── session_token ─────────                           │
     │                          │                           │
     ├──────────────────── session_token ───────────────────>
     │                          │                           │
     │                          │       [SDK connects WSS]  │
     │                          │<── WebSocket handshake ───┘
     │                          │─── work.snapshot ─────────>
     │                          │                           │
     │                          │         [user completes task]
     │                          │<── completeTask ───────────
     │                          │─── task.completed ────────>
     │                          │─── task.assigned ─────────>

Components

Sessions API — An endpoint in the Stateway API for your backend to issue ephemeral, scoped session tokens for end users. Your backend remains the identity issuer; Stateway manages work state.

WebSocket Proxy (stateway-ws) — A dedicated container that accepts WebSocket connections authenticated by session token, resolves the user's pending work, delivers tasks and events in real time, and arbitrates concurrent claim operations.

@stateway/frontend-sdk — A JavaScript/TypeScript library for use in your frontend. It abstracts the WebSocket protocol, reconnection with exponential backoff, request multiplexing, and message typing.

Session Continuity

Work state belongs to the user within the tenant — not to the session. A session is an ephemeral access token. When the user re-authenticates and a new session is created with the same user_id, Stateway automatically re-associates all running instances. No state is lost.

user_id  (permanent, your namespace)
    │
    ├── frontend_session A  [expired]
    ├── frontend_session B  [active]   ← new session, same user_id
    │
    └── process instances              ← survive session changes
            inst_01j...  [running]
            inst_02j...  [completed]

Your Backend's Responsibilities

The Frontend Gateway reduces your backend to two responsibilities:

1. Authenticate your own user (as it already does today)
2. Call POST /v1/sessions with the user_id and appropriate scope, returning the session_token to the frontend

Everything else — work resolution, task delivery, event streaming, claim arbitration, variable filtering — is handled by Stateway.