Simulators

Clerk changelog

What changed in each Clerk simulator release, newest first.

v0.0.5 — 2026-11-06

A key that does not start with sk_ is refused on every route. Every Backend API route returns 401 clerk_key_invalid for a bearer value that does not start with sk_, as Clerk does. A second Authorization header gets 401 authorization_header_format_invalid, where Clerk returns a 400 page. Deleting an organization and updating a membership used to carry out such requests, and the other routes returned a 401 or 403 that varied by route.
The docs gain an Errors and limits section. It shows the errors body with code, long_message, meta.param_name and clerk_trace_id, how each list pages with limit, offset and starting_after, and what a repeated create returns.

v0.0.4 — 2026-11-05

The twin documents its own control plane in Swagger. /_rystic/swagger now lists a Rystic control plane spec, served at /_rystic/swagger/spec/rystic-control-plane.json, describing the /_rystic/* routes this twin serves (its scenarios, inspect views and seedable registers by name) and its /_twin/* routes.
A state dump seeds back as it was, and the next record gets a fresh id. GET /_rystic/inspect posted to POST /_rystic/seed after a reset restores every record where it was, per-caller records included, which used to land under a doubled key. The next record created after any seed passes every uuid and event id the simulator minted that the seed holds. GET /_rystic/inspect?view=sequences lists every id counter, and a world document’s new sequences key restores them, so ids the simulator renders from a counter continue where the dump left off.
A slow client no longer holds up the others. The simulator reads a request’s whole body before it starts serving it and sends the answer after, so a client that uploads slowly, or reads a large answer slowly, no longer delays other clients’ requests. Answers are unchanged; one larger than 4 MiB still makes other requests wait while it is sent.
The call log shows what each call asked for and whether it succeeded. Each GET /_rystic/calls entry now carries args, the call’s query and body arguments with credentials redacted (long values cut, file contents left out), and ok, false for an answer that is not 2xx. A path the simulator does not serve is marked unknown_route: true. ?tail=N returns only the last N calls, and dropped counts the calls the log no longer keeps.
Coverage lists the browser assets. The docs’ Coverage section now lists GET and HEAD for /clerk.js, /clerk-ui.js, /clerk.css and /preview/{file}, which the simulator already served, and counts them in its route total.
The docs are one page, with a page for the browser companion. The archive ships README.md in place of HOWTO.md and SCENARIOS.md, with the same sections in the same order as every Rystic simulator’s page, and CHANGELOG.md beside it. The browser companion has its own page under docs/features/, and every example on these pages runs as written against a fresh simulator.
The docs page links the admin token section. The page now sends you to the admin token’s section of the shared-simulators page.
Scenario descriptions use customer terms. The Scenarios table and --list-scenarios describe each scenario in American spelling, with no internal references.
The Scenarios table is easier to scan. Each row says in a line what the scenario is for, and a list below the table says what each scenario holds.
Pro starts with a 14-day trial. Free has ended, so every simulator is on Pro and Enterprise, and the docs name only those plans.
Limitations is shorter to read. It opens with the known issues and one sentence counting the rest. The detailed lists follow, and the website folds them behind “Show all limitations”.
The page has no Plans section. The Quickstart names the plans that run the simulator, and the pricing page lists what each plan includes.
The docs read more plainly, and each difference from Clerk is marked. Sentences are shorter, and each behavior that differs from Clerk is marked “Differs from Clerk” where it’s described. Rules with several outcomes, such as what a missing key returns, which Clerk-API-Version values the simulator serves and which writes record a webhook event, are tables. The Auth section also names the two requests that go through with a key not starting with sk_ or a repeated Authorization header: deleting an organization and updating a membership. Quickstart, Auth, Seeding state and the reset section keep to this simulator’s own facts, leaving the rules every simulator shares to the shared pages.

v0.0.3 — 2026-10-27

The HOWTO documents the world document POST /_rystic/seed takes. A direct seed takes a whole scenario file, with its clock, rng_seed, credentials and events, not only the bare register map; the HOWTO now says so, with an example that binds a token and schedules a call.
Indexed list query parameters. A list filter sent as user_id[0]=…&user_id[1]=…, as some SDKs encode arrays, reads the same as the repeated user_id=…&user_id=… on GET /users, GET /users/count, GET /organizations and GET /organizations/{organization_id}/memberships.
Swagger UI to read and call the twin from the browser. /_rystic/swagger, linked from the state UI header, is Swagger UI over the published API trimmed to the operations this twin serves; Try it out sends each request to the twin.

v0.0.2 — 2026-10-12

clerk_acme_tenant plays a timeline. Its backend, bound to sk_test_acme_backend, updates Sam’s metadata two hours after the pinned clock, creates Priya Raman a day in, promotes Yuki to admin, moves the organization to the scale plan on day three and removes Iris on day five, all through the Backend API; advance the clock to watch the tenant change.
A seeded user, organization or membership sends its created webhook. A record a world’s timeline seed event or a bare POST /_rystic/seed creates now sends user.created, organization.created or organizationMembership.created, as the create operation does, to the egress log and any configured webhook endpoint. A world’s starting snapshot sends none.
Session tokens and webhooks can follow a shifted app clock. POST /_rystic/clock {"wall_offset_seconds": N} stamps session JWT iat, nbf and exp and the webhook svix-timestamp N seconds past the wall clock, so an app whose own clock you moved forward (as sandbox clock -advance does) still accepts them; 0 or /_rystic/reset puts it back.
Every Backend API call without a secret key is refused as Clerk refuses it. A request with no Authorization header now answers 401 with errors[0].code = authorization_header_format_invalid on every operation, ahead of the operation’s own checks. DELETE /v1/organizations/{id} and PATCH /v1/organizations/{id}/memberships/{user_id} used to succeed without a key, and other operations answered with differing authentication_invalid bodies.

v0.0.1 — 2026-10-11

A local Clerk for your app’s users, organizations and sign-in. The first release of the Clerk twin: the 20 Backend API operations on users and their metadata, organizations with their metadata and memberships, at Clerk-API-Version: 2026-05-12, served from a model validated against a live Clerk development instance, and a browser companion that serves a lookalike clerk.js so a @clerk/nextjs app signs users in against the same state. It runs on Pro and Enterprise. Point @clerk/backend at it with any sk_ key (HOWTO.md shows how); no email is sent and no real instance changes.
Users and their metadata, as Clerk keeps them. POST /v1/users stores each email address in lowercase, GET /v1/users?email_address= finds a user by any letter case of their address, and an address that differs from a taken one only in case answers 422 form_identifier_exists; a malformed one answers 422 form_param_format_invalid. GET /v1/users refuses an order_by that names no sortable field with 422 form_param_value_invalid. PATCH and PUT /v1/users/{user_id}/metadata merge and replace metadata, and DELETE /v1/users/{user_id} removes the user’s organization memberships. Every image_url and profile_image_url leads to a PNG the twin serves under /preview/.
Organizations, their metadata and their members. An organization created with created_by lists its creator as an org:admin member right after the create, and include_members_count=true counts them. PATCH /v1/organizations/{organization_id}/metadata deep-merges public_metadata and private_metadata, removing a key set to null, and PUT replaces each field it names whole. Writes and lists answer with the keys Clerk’s answers carry.
Clerk-API-Version is checked on every route and echoed. 2021-02-05, 2024-10-01, 2025-04-10, 2025-11-10 and 2026-05-12 (the default) are accepted and echoed in clerk-api-version, and any other value answers 400 api_version_invalid. At 2026-05-12, metadata sent to PATCH /v1/users/{user_id} or PATCH /v1/organizations/{organization_id} answers 422 form_param_deprecated, as Clerk does: write it through the /metadata routes.
A browser sign-in for @clerk/nextjs. Point NEXT_PUBLIC_CLERK_JS_URL and NEXT_PUBLIC_CLERK_UI_URL at the twin’s /clerk.js and /clerk-ui.js and your app gets email sign-in and sign-up with consent, Continue with GitHub and Continue with Google buttons that sign in local test identities, organization creation and selection, and member invitation, role changes and removal; signing in as an invited address joins its organization with no email sent. Sessions are RS256 tokens stamped on the wall clock your site verifies them against, and the SDK middleware’s handshake is answered by the twin, so a sandboxed site never leaves it. Boot the twin with your own RSA key, your site’s origin and its own origin; GET /_twin/config gives the publishable key, the public PEM and the proxy URL.
Webhooks Clerk would send, signed with Svix headers. Every user write, organization create, update and delete, and membership write, from the Backend API or the browser, records user.*, organization.* or organizationMembership.* in GET /_rystic/egress; the organization /metadata routes record none. Boot with CLERK_TWIN_WEBHOOK_URL and a whsec_ CLERK_TWIN_WEBHOOK_SECRET and each is also delivered, its svix-timestamp on the wall clock so your receiver’s five-minute window holds however long the twin sat idle. A failed delivery never undoes the write. Event shapes follow Clerk’s documentation and are not measured against live deliveries.
Five shipped worlds. --scenario clerk_acme_tenant boots Acme Robotics: five users in one organization, two pending invitations and three live sessions. clerk_holdco_orgs holds one identity across three organizations, clerk_invite_backlog an organization at its ten-seat cap with eight invitations pending, clerk_session_sweep six sessions from lapsed to live, and clerk_solo_founder one user and her organization; SCENARIOS.md says what each is for. Without --scenario the twin boots an empty instance, POST /_rystic/seed lands users, organizations, memberships, sessions and invitations directly, and POST /_rystic/reset rewinds the ID sequence, so two identical runs from a pinned clock give byte-identical users and organizations.
Measured against a live Clerk development instance. The 2026-10-07 full-suite round matched 100 of 100 Backend API probes, with 0 inconclusive. HOWTO.md states what the suite leaves out and the differences this release ships with: typed query parameters are not validated, responses carry no x-clerk-trace-id header, an unserved route answers a plain 404, not Clerk’s resource_not_found, and deleting an organization or changing a membership’s role checks no secret key.