Adapters Overview

Stepflow is framework-agnostic and provides official adapters for popular TypeScript web frameworks. Adapters handle HTTP routing, request parsing, and real-time SSE streaming, allowing you to expose your workflows as a secure API.

Supported Frameworks

Common Features

All official adapters share a common set of features and configuration patterns.

Standard Routes

Adapters expose the following routes by default:

• POST /trigger/:workflowId - Trigger a workflow execution
• GET /runs/:runId - Get the current status of a run
• GET /runs/:runId/stream - Real-time updates via Server-Sent Events (SSE)
• POST /notify/:eventId - Send an external event to a waiting workflow
• GET /health - Health check endpoint

Endpoint Configuration

You can control which endpoints are enabled using the endpoints option. This can be a preset string or a fine-grained configuration object.

// Using a preset
const endpoints = "private"; // Disables trigger/notify, enables runs/health

// Fine-grained control
const endpoints = {
  trigger: true,
  notify: false,
  runs: true,
  runsStream: true,
  health: true,
};

Presets

• all / public: All endpoints enabled (default)
• none: All endpoints disabled
• private: Disables trigger and notify (useful for backend-only internal APIs)
• internal: Only the health endpoint is enabled

Authorization

Stepflow adapters provide a flexible authorization system. You can define a global handler or route-specific handlers.

import { createApiKeyAuth, anyOf } from "@stepflowjs/adapter-shared";

const auth = {
  // Global handler for all routes
  global: createApiKeyAuth(process.env.STEPFLOW_API_KEY),

  // Override for specific routes
  health: () => ({ ok: true }), // Make health check public
};

Auth Helpers

The @stepflowjs/adapter-shared package provides several helpers for common auth patterns:

• createApiKeyAuth(key, options) - Simple API key check in headers (default: x-api-key)
• createBearerAuth(validator, options) - Validates Bearer tokens using a custom function
• anyOf(...handlers) - Logical OR: allows access if ANY handler passes
• allOf(...handlers) - Logical AND: allows access only if ALL handlers pass

Custom Health Checks

You can provide a custom health check function to verify your application's dependencies (e.g., database connection).

const healthCheck = async () => {
  const dbOk = await checkDatabase();
  return dbOk;
};