handleFlow()

The handleFlow() function returns an Express route handler that advances the embedded sign-in flow and responds with JSON.

Signature

handleFlow(): express.RequestHandler

Import

const {handleFlow} = require('@thunderid/express');

Prerequisites

• Mount thunderID() with mode: 'embedded'
• Mount express.json() before this handler so the SDK can read req.body
• Keep handleSignIn() mounted on your callback route so the returned redirect URL can complete sign-in

Usage

index.js

const express = require('express');
const cookieParser = require('cookie-parser');
const {thunderID, handleFlow, handleSignIn, handleSignOut} = require('@thunderid/express');

const app = express();

app.use(cookieParser());
app.use(express.json());
app.use(
  thunderID({
    baseUrl: 'https://localhost:8090',
    clientId: '<your-client-id>',
    clientSecret: '<your-client-secret>',
    mode: 'embedded',
  }),
);

app.post('/flow/sign-in', handleFlow());
app.get('/login', handleSignIn());
app.get('/logout', handleSignOut());

Request Shapes

First Request

When no executionId is present, send:

{
  "applicationId": "app-id",
  "flowType": "SIGN_IN"
}

If flowType is omitted, the SDK uses 'SIGN_IN'.

Continuation Request

When continuing an existing flow, send:

{
  "executionId": "...",
  "challengeToken": "...",
  "authId": "...",
  "inputs": {
    "...": "..."
  }
}

Response Shapes

Flow Continues

If the flow needs another step, the handler returns:

{
  "authId": "...",
  "challengeToken": "...",
  "components": [],
  "executionId": "...",
  "flowStatus": "..."
}

Flow Completes

If the flow finishes and the next step is the OAuth callback, the handler returns:

{
  "done": true,
  "redirectUrl": "/login?code=..."
}

The client must navigate to redirectUrl, which is then handled by handleSignIn() to exchange the code and set the session cookie.

Runtime Behavior

• Requires req.thunderIDAuth from thunderID()
• Requires baseUrl in the initialized config
• On the first request, if authId is not provided, the handler derives it from client.getSignInUrl()
• Delegates flow execution to the embedded sign-in flow executor and normalizes the response into JSON

Failure Behavior

The handler returns 500 JSON responses for these cases:

Condition	Response
thunderID() not mounted first	{ "error": "SDK not initialised" }
baseUrl missing from config	{ "error": "baseUrl is not configured" }
Flow execution failure	{ "error": "<runtime message>" }

Related APIs

• thunderID()
• handleSignIn()
• Embedded Sign-In