# WorkOS Emulator (service host)

Create an instance:
curl -s -X POST https://workos.emulators.dev/_emulate/instances
# Hosted deployments create instances lazily when the returned URL is first used. The instance URL is a capability: anyone who has it can read and modify the instance, so save the returned URLs. Never store real secrets in an emulator.
# The server generates an unguessable name. An optional {"instance":"<prefix>"} body adds a readable prefix.

Then use the returned providerBaseUrl / controlBaseUrl. Example below uses a sample instance.
# WorkOS Emulator

Stateful WorkOS emulator: AuthKit user management (hosted login, code + refresh grants, sealed-session JWKS), organizations, memberships, invitations, API keys, Vault KV, and an OAuth authorization server for MCP clients.

Provider base URL: https://workos.your-instance.emulators.dev
Control base URL: https://workos.your-instance.emulators.dev/_emulate

Supported surfaces:
- WorkOS REST API: partial at /
- Hosted AuthKit login: supported at /user_management/authorize
- OAuth authorization server (MCP): supported at /oauth2
- Vault KV: supported at /vault/v1/kv

Control endpoints:
- https://workos.your-instance.emulators.dev/_emulate/manifest
- https://workos.your-instance.emulators.dev/_emulate/coverage
- https://workos.your-instance.emulators.dev/_emulate/connections
- https://workos.your-instance.emulators.dev/_emulate/state
- https://workos.your-instance.emulators.dev/_emulate/ledger
- https://workos.your-instance.emulators.dev/_emulate/faults
- POST https://workos.your-instance.emulators.dev/_emulate/credentials
- POST https://workos.your-instance.emulators.dev/_emulate/seed
- POST https://workos.your-instance.emulators.dev/_emulate/reset

Fault injection:
Arm a one-shot provider failure with a glob pathPattern, then inspect /ledger for faulted: true.
curl -s -X POST https://workos.your-instance.emulators.dev/_emulate/faults \
  -H "content-type: application/json" \
  -d '{"match":{"method":"GET","pathPattern":"/v1/*"},"response":{"status":503,"body":{"error":"temporary"}}}'

Connect:

## WorkOS Node SDK
import { WorkOS } from "@workos-inc/node";

const url = new URL("https://workos.your-instance.emulators.dev");
const workos = new WorkOS("<token>", {
  clientId: "client_emulate",
  apiHostname: url.hostname,
  port: Number(url.port),
  https: url.protocol === "https:",
});

## Base URL (env)
WORKOS_BASE_URL=https://workos.your-instance.emulators.dev

## Create a credential
curl -s -X POST https://workos.your-instance.emulators.dev/_emulate/credentials \
  -H "content-type: application/json" \
  -d '{"type":"api-key"}'

## Inspect requests
curl -s https://workos.your-instance.emulators.dev/_emulate/ledger