Skip to Content
SimulatorsOktaOverview

Simulators

Okta simulator

okta-twin is a local, stateful simulator of the Okta Management API for testing provisioning code. Users and their lifecycle, groups and memberships, bookmark applications and their assignments, password operations and software-TOTP factors keep Okta’s statuses, refusals and error codes. Where the simulator departs from an Okta org, these pages say so, in a Differs from Okta line beside the behavior or under Limitations. Behavior not yet checked against a real Okta org is marked (unconfirmed). It never calls Okta, changes no real directory and sends no email: creating or activating a user records the activation email on GET /_rystic/egress.

Quickstart

Install the CLI, sign in and boot the simulator with RYSTIC_URL pointing at it.

On Pro you sign in with an API key from your account .

curl -fsSL https://www.rystic.ai/install.sh | sh
rystic login rys_…   # your API key
export RYSTIC_URL=$(rystic run okta-twin -d --port 0 --scenario design_studio --json | jq -r .data.url)
curl -s "$RYSTIC_URL/_rystic/version"
# -> {..."product":"okta-twin"...}

On Enterprise, the licensed edition signs in with a license file in place of the key: rystic login ./rystic-license.json (licensing ).

First calls

List the Design department, onboard a new hire and read the hire back by login:

curl -s "$RYSTIC_URL/api/v1/users?search=profile.department%20eq%20%22Design%22" -H 'Authorization: SSWS placeholder' | jq -c 'map(.profile.firstName) | sort'
# -> ["Casey","Felix","Ingrid","June","Luis","Mei","Rosa","Tariq"]
curl -s "$RYSTIC_URL/api/v1/users?activate=false" -H 'Authorization: SSWS placeholder' -H 'Content-Type: application/json' -d '{"profile":{"firstName":"New","lastName":"Hire","email":"new.hire@wdcontractors.example","login":"new.hire@wdcontractors.example"}}' | jq -c '{id, status}'
# -> {"id":"00u00000000000000001","status":"STAGED"}
curl -s "$RYSTIC_URL/api/v1/users/new.hire@wdcontractors.example" -H 'Authorization: SSWS placeholder' | jq -c '{id, status, login: .profile.login}'
# -> {"id":"00u00000000000000001","status":"STAGED","login":"new.hire@wdcontractors.example"}

Connect your client

Point an official Okta client at $RYSTIC_URL with any placeholder token, setting the SDK’s org URL where it has one. The simulator serves plain HTTP, so turn off the SDK’s HTTPS check for tests. The Python SDK (okta 3.x) reads that switch from its environment, not from the config dict:

export OKTA_TESTING_TESTINGDISABLEHTTPSCHECK=true

Python:

import os

from okta.client import Client as OktaClient

client = OktaClient({
    "orgUrl": os.environ["RYSTIC_URL"],
    "token": "placeholder",
})

Node:

import okta from "@okta/okta-sdk-nodejs";

const client = new okta.Client({
  orgUrl: process.env.RYSTIC_URL,
  token: "placeholder",
  testing: { disableHttpsCheck: true },
});

The Go SDK (v6) and terraform-provider-okta reach the simulator through a proxy: set HTTP_PROXY (Go) or OKTA_HTTP_PROXY (Terraform) to $RYSTIC_URL, with any org URL and token. Go:

import (
	"os"

	"github.com/okta/okta-sdk-golang/v6/okta"
)

func main() {
	os.Setenv("OKTA_CLIENT_ORGURL", "http://okta.localhost")
	os.Setenv("OKTA_CLIENT_TOKEN", "placeholder")
	os.Setenv("HTTP_PROXY", os.Getenv("RYSTIC_URL"))
	cfg, _ := okta.NewConfiguration()
	cfg.Okta.Testing.DisableHttpsCheck = true
	_ = okta.NewAPIClient(cfg)
}

The simulator serves Okta’s paths as they are (/api/v1/users), so an org URL is the host alone. Every _links href and Link target is on the origin your client reached, so paging stays on the simulator.

To keep an org URL on okta.com, boot with rystic run okta-twin --intercept and run your client under rystic exec -- <command> (Intercept). An org on a custom domain isn’t routed, so point the SDK’s orgUrl at the simulator.

okta-mcp-server

okta-mcp-server needs the workaround in the table below to sign in, because the simulator doesn’t serve Okta’s OAuth routes. It puts https:// in front of OKTA_ORG_URL, so keep that on your Okta host and run the server under rystic exec, as above.

Each client’s quickstart was run against this simulator in each way it connects, with the vendor’s own hosts blocked.

ClientVersionKindWorks withFails withCheckedKnown gap
okta-mcp-server (PyPI)v1.1.7mcp-server—default host2026-10-30POST /oauth2/v1/token returns 404, so okta-mcp-server’s Private Key JWT login at startup fails. The server exits before it responds to initialize. Workaround: Before starting okta-mcp-server, store any unexpired JWT in its keyring as service OktaAuthManager, user api_token. The server reuses that cached token and skips the token call. A placeholder HS256 token works, since the simulator accepts any token. Set its exp years ahead, because the server signs in again once exp is under a minute away. Or call the simulator through the Okta SDKs or terraform-provider-okta, which it serves.
github.com/okta/okta-sdk-golang/v6 (Go)v6.1.7sdkproxy, default host—2026-10-29—
@okta/okta-sdk-nodejs (npm)v8.2.0sdkbase URL, default host—2026-10-30—
okta (PyPI)v3.4.7sdkbase URL, default host—2026-10-30—
okta/okta (Terraform)v7.0.0terraform-providerproxy, default host—2026-10-30—

Auth

The simulator takes an API token where Okta does, as Authorization: SSWS <token>.

Differs from Okta: the simulator accepts any non-empty Authorization value, Bearer included. It checks no token shape, admin role, scope or expiry.

A request with no Authorization header returns 403 E0000005 (Invalid session) on every route the simulator serves. As on Okta, that check comes before any lookup of an id in the path and before the body is read.

The exception is GET /.well-known/okta-organization, which takes no credential. It returns the simulator’s own org: a placeholder 00o… id, pipeline idx and the org URL on the origin you reached.

GET /api/v1/users/me returns the user who owns the calling credential, as the full user object. Which user that is depends on the request:

The request carriesme is
an X-Rystic-Actor header naming a userthat user, whatever the credential
an X-Rystic-Actor header holding any other value, a login includednobody: the request returns 404 E0000007
a credential bound to a user, with POST /_rystic/credentials or by the scenario (and no X-Rystic-Actor)that user
a credential bound to any other value, a login included (and no X-Rystic-Actor)nobody: the request returns 404 E0000007
any other credential (and no X-Rystic-Actor)the scenario’s token owner

A header or binding names a user by its state_user key, its id or a label a scenario file’s actors maps to it. The token owner’s key is member.

Differs from Okta: for a Bearer token no binding names, me is the token owner too, where Okta returns the token’s subject.

me names the same user in four more routes:

  • /api/v1/users/me/groups
  • /api/v1/users/me/factors
  • /api/v1/users/me/factors/catalog
  • /api/v1/users/me/factors/{factorId}

In /api/v1/apps/{appId}/users/me, as on Okta, me is an unknown id.

API version

The simulator serves the Okta Management API as published in the August 2026 release of Okta’s OpenAPI description, under /api/v1. Okta versions this API by path and sends no version header, so there is nothing to pin. A request to another prefix, such as /api/v2/users, returns 404 (Error format).

Errors and limits

Error format

A refusal from a route the simulator serves has Okta’s error fields: errorCode, errorSummary, errorLink, errorId and errorCauses. errorId is opaque: most routes write oae plus a counter, so a run repeats, and the refusal of a request with no Authorization header has a fixed one.

Two refusals have other bodies:

  • A path Okta doesn’t have, under /api/v1 or elsewhere, returns the simulator’s own 404 before the Authorization check, a known issue (Limitations).
  • A factor activation or verification outside the software-TOTP case the simulator models returns 501, with an X-Rystic-Marker header and a body naming the unmodeled check.

Rate limits

Okta’s routes here throttle nothing by themselves, with one exception, factor activation: after five wrong passcodes within five minutes, POST /api/v1/users/{userId}/factors/{factorId}/lifecycle/activate returns 429 E0000047 until five minutes have passed since the first.

Okta’s X-Rate-Limit-* headers are a known issue (Limitations). Network profiles send a 429 you shape, such as Okta’s E0000047.

Pagination

A list takes limit for the page size and after for the cursor, and the Link header’s rel="next" carries the next page’s after.

ListafterDefault limitLargest limitLink
GET /api/v1/usersa user’s id200, or 10 with qnoneself, and next while more remain
GET /api/v1/groupsa group’s idevery group, or 300 with q10000self, and next while more remain
GET /api/v1/groups/{groupId}/usersa user’s id1000noneself, and next while more remain
GET /api/v1/appsthe cursor next namesevery appnonenext alone, as a path on the simulator’s origin
GET /api/v1/apps/{appId}/usersthe cursor next names50500next alone
GET /api/v1/apps/{appId}/groupsa group’s id20200self and next while more remain
  • An id as the cursor. Where after is a record’s id, any record’s id resumes the list after that record. An after naming no record, or a cursor the simulator did not hand out, returns an empty page (unconfirmed).
  • Out of range. A limit past the largest is served as the largest, and on the two app assignment lists one below the smallest (1 for users, 20 for groups) as the smallest (unconfirmed).
  • No paging. GET /api/v1/users/{id}/groups and GET /api/v1/users/{userId}/factors take neither limit nor after and return every record.

A limit above 200 on GET /api/v1/apps is a known issue (Limitations). /_rystic/page-cap caps limit on a list.

Idempotency

Not applicable: no Okta Management API route reads an idempotency header.

Coverage

OAuth 2.0 and OIDC, browser and Identity Engine sign-in, sessions and unlock are out of scope. So are roles and grants, group rules and owners, linked objects, the System Log, hooks and every other Management API family.

50 routes, counted from the simulator’s route table.

Show all operations
ResourceOperations
Application (7)GET, POST /api/v1/apps; GET, PUT, DELETE /api/v1/apps/{appId}; POST /api/v1/apps/{appId}/lifecycle/activate; POST /api/v1/apps/{appId}/lifecycle/deactivate
Application group assignment (2)PATCH, DELETE /api/v1/apps/{appId}/groups/{groupId}
Application user assignment (5)GET, POST /api/v1/apps/{appId}/users; GET, POST, DELETE /api/v1/apps/{appId}/users/{userId}
Group (11)GET /api/v1/apps/{appId}/groups; GET, PUT /api/v1/apps/{appId}/groups/{groupId}; GET, POST /api/v1/groups; GET, PUT, DELETE /api/v1/groups/{groupId}; PUT, DELETE /api/v1/groups/{groupId}/users/{userId}; GET /api/v1/users/{id}/groups
Org (1)GET /.well-known/okta-organization
Private user password verifier (2)POST /api/v1/users/{id}/lifecycle/expire_password_with_temp_password; POST /api/v1/users/{userId}/credentials/change_password
User (15)GET /api/v1/groups/{groupId}/users; GET, POST /api/v1/users; GET, POST, PUT, DELETE /api/v1/users/{id}; POST /api/v1/users/{id}/lifecycle/activate; POST /api/v1/users/{id}/lifecycle/deactivate; POST /api/v1/users/{id}/lifecycle/expire_password; POST /api/v1/users/{id}/lifecycle/reactivate; POST /api/v1/users/{id}/lifecycle/reset_password; POST /api/v1/users/{id}/lifecycle/suspend; POST /api/v1/users/{id}/lifecycle/unsuspend; GET /api/v1/users/{userId}/factors/catalog
User factor (MFA enrollment) (7)POST /api/v1/users/{id}/lifecycle/reset_factors; GET, POST /api/v1/users/{userId}/factors; GET, DELETE /api/v1/users/{userId}/factors/{factorId}; POST /api/v1/users/{userId}/factors/{factorId}/lifecycle/activate; POST /api/v1/users/{userId}/factors/{factorId}/verify

Feed effects. Each operation below can put an effect event on the event feed (/_rystic/events) for each event type beside it, when what the call does produces that event. Any other call puts only its request event there.

OperationEvent types
POST /api/v1/userstype set per call, by effect: eff_activation_email
POST /api/v1/users/{id}/lifecycle/activatetype set per call, by effect: eff_activation_email

Scenarios

The simulator ships 1 scenario; the quickstart boots design_studio.

ScenarioWhat it is forWhat it seedsClock
design_studio (default)Website Design Contractors’ orggroup 11, group_membership 70, user 372026-03-01T00:00:00Z

What each scenario holds:

  • design_studio:
    • 33 ACTIVE users, 27 staff in seven team groups and six in Freelancers.
    • Hannah Kim, the newest staff hire.
    • Three DEPROVISIONED ex-staff, Casey Morgan the latest.
    • Staff profiles with title, department, manager and managerId, so the org chart walks down from Dana Whitfield.
    • Studio Bot, the Okta Admins integration account an unbound token acts as.

Boot one by name, or load one into a running simulator:

rystic run okta-twin -d --port 0 --scenario design_studio
curl -s -X POST "$RYSTIC_URL/_rystic/scenario" -d '{"name":"design_studio"}'

design_studio binds the credential SSWS 00WdcNoorAdmin7kQ2xVb9mT4pLs8nRc3 to Noor Haddad. Without an X-Rystic-Actor header, GET /api/v1/users/me with it returns Noor’s user, noor@wdcontractors.example; with any other credential it returns Studio Bot.

The studio’s timeline

Moving the clock plays design_studio’s timeline, each step a call Noor Haddad makes. Events, in order: Hannah Kim joins Content (+1h) → Hannah is retitled (+4h) → Ava Chen is suspended (+24h) → Ava leaves Freelancers (+25h) → Lena Okafor is onboarded (+72h) → Lena joins Freelancers (+72h5m).

What the scenarios do not hold

  • No application, factor or password is seeded: create them with the API.
  • Without --scenario, the simulator boots an org that holds only its token owner (a placeholder ACTIVE user in Everyone, login token.owner@example.com) and Okta’s two BUILT_IN groups, Everyone and Okta Administrators (which lists no members).

Seeding state

Each resource is one register, and each record goes in under its key:

RegisterHoldsKey
state_usera userits id
state_groupa groupits id
state_group_membershipa group membership<groupId>/<userId>
state_applicationan applicationits id
state_app_useran application’s user assignment<appId>/<userId>
state_app_group_assignmentan application’s group assignment<appId>/<groupId>
state_user_factora factor<userId>/<factorId>
state_factor_challengea factor’s challenge<userId>/<factorId>
state_user_passworda passwordits user’s id
state_orgthe orgits id

Seed an ACTIVE user under an id of your own, then read it back:

curl -s -X POST "$RYSTIC_URL/_rystic/seed" -d '{"state_user":{"00useed0000000000001":{"id":"00useed0000000000001","status":"ACTIVE","type":{"id":"otyseed000000000001"},"credentials":{"provider":{"name":"OKTA","type":"OKTA"}},"profile":{"firstName":"Seed","lastName":"User","email":"seed@example.com","login":"seed@example.com"}}}}'
curl -s "$RYSTIC_URL/api/v1/users/00useed0000000000001" -H 'Authorization: SSWS placeholder' | jq -c '{id, status, login: .profile.login}'
# -> {"id":"00useed0000000000001","status":"ACTIVE","login":"seed@example.com"}

Seeding covers the seed route’s responses, its refusals and boot files.

Features

Each feature has its own page:

  • Bookmark applications: Bookmark applications are assigned to users directly or through groups, and a user’s access follows its group membership and status.
  • Software TOTP factors: A user enrolls an OKTA software TOTP factor, activates it and verifies it with codes computed from the shared secret at the simulator’s clock.
  • User lifecycle and passwords: A user moves through Okta’s statuses (staged, active, suspended, deprovisioned) by the lifecycle routes, and password routes expire, reset and change its password; an activation email is recorded, never sent.

Determinism and reset

Ids are sequences with a prefix per kind: 00u00000000000000001 for a user, 00g00000000000000001 for a group, 0oa00000000000000001 for an application. Moving the clock with POST /_rystic/clock plays the studio’s timeline and changes the software-TOTP codes, which are computed at the simulator’s clock (Software TOTP factors).

Reset and determinism covers reset, the clock and the RNG.

Limitations

Known issues.

  • A path or method Okta doesn’t have returns 404 with a JSON message, where Okta returns its error object with errorCode and errorSummary.
  • POST /oauth2/v1/token returns 404, so okta-mcp-server’s Private Key JWT login at startup fails. The server exits before it responds to initialize. Workaround: Before starting okta-mcp-server, store any unexpired JWT in its keyring as service OktaAuthManager, user api_token. The server reuses that cached token and skips the token call. A placeholder HS256 token works, since the simulator accepts any token. Set its exp years ahead, because the server signs in again once exp is under a minute away. Or call the simulator through the Okta SDKs or terraform-provider-okta, which it serves.
  • No response sends X-Rate-Limit-Limit, X-Rate-Limit-Remaining or X-Rate-Limit-Reset, which Okta sends on its Management API responses.
  • GET /api/v1/apps takes a limit above 200 and returns that many apps, where Okta’s largest is 200.

Beyond the known issues, 684 of the 734 operations in the published spec are not served, 102 documented responses have no test yet and 122 behaviors are not modeled. The details follow.

Show all limitations

Not served. 684 of the 734 operations in the published spec are not served. Calling one of these routes returns 501, unless a served route takes its path.

  • Group, 8 of 9 served: GET /api/v1/groups/{groupId}/apps
  • User, 6 of 7 served: GET /api/v1/users/{id}/blocks
  • UserCred, 4 of 7 served: POST /api/v1/users/{userId}/credentials/change_recovery_question, POST /api/v1/users/{userId}/credentials/forgot_password, POST /api/v1/users/{userId}/credentials/forgot_password_recovery_question
  • UserFactor, 7 of 13 served: GET /api/v1/org/factors/yubikey_token/tokens, POST /api/v1/org/factors/yubikey_token/tokens, GET /api/v1/org/factors/yubikey_token/tokens/{tokenId}, GET /api/v1/users/{userId}/factors/questions, POST /api/v1/users/{userId}/factors/{factorId}/resend, GET /api/v1/users/{userId}/factors/{factorId}/transactions/{transactionId}
  • UserLifecycle, 6 of 7 served: POST /api/v1/users/{id}/lifecycle/unlock
  • UserResources, 1 of 4 served: GET /api/v1/users/{id}/appLinks, GET /api/v1/users/{userId}/clients, GET /api/v1/users/{userId}/devices
  • Not served at all: AgentPools (14), ApiServiceIntegrations (9), ApiToken (5), ApplicationConnections (6), ApplicationCrossAppAccessConnections (5), ApplicationFeatures (3), ApplicationGrants (4), ApplicationInterclientTrustMappings (4), ApplicationLogos (1), ApplicationPolicies (1), ApplicationSSO (1), ApplicationSSOCredentialKey (9), ApplicationSSOFederatedClaims (5), ApplicationSSOPublicKeys (12), ApplicationTokens (4), AssociatedDomainCustomizations (7), AttackProtection (4), Authenticator (19), AuthorizationServer (7), AuthorizationServerAssoc (3), … and 91 more

Not tested. 217 tests compare the simulator with the real service. 102 documented responses have no test yet, and 49 of them need a credential our test account doesn’t hold (403 ×49). The other 53:

OperationStatusWhy
DELETE /api/v1/apps/{appId}429no request a client sends provokes it
DELETE /api/v1/apps/{appId}/groups/{groupId}429no request a client sends provokes it
DELETE /api/v1/apps/{appId}/users/{userId}429no request a client sends provokes it
DELETE /api/v1/groups/{groupId}429no request a client sends provokes it
DELETE /api/v1/groups/{groupId}/users/{userId}429no request a client sends provokes it
DELETE /api/v1/users/{id}429no request a client sends provokes it
DELETE /api/v1/users/{userId}/factors/{factorId}429no request a client sends provokes it
GET /.well-known/okta-organization429no request a client sends provokes it
GET /api/v1/apps429no request a client sends provokes it
GET /api/v1/apps/{appId}429no request a client sends provokes it
GET /api/v1/apps/{appId}/groups429no request a client sends provokes it
GET /api/v1/apps/{appId}/groups/{groupId}429no request a client sends provokes it
GET /api/v1/apps/{appId}/users429no request a client sends provokes it
GET /api/v1/apps/{appId}/users/{userId}429no request a client sends provokes it
GET /api/v1/groups429no request a client sends provokes it
GET /api/v1/groups/{groupId}429no request a client sends provokes it
GET /api/v1/groups/{groupId}/users429no request a client sends provokes it
GET /api/v1/users429no request a client sends provokes it
GET /api/v1/users/{id}429no request a client sends provokes it
GET /api/v1/users/{id}/groups429no request a client sends provokes it
… and 33 more

Not modeled. Behavior the simulator does not model, by operation:

  • Whether the concrete errorCode values for 403/404/429 are stable constants. (DELETE /api/v1/apps/{appId}/groups/{groupId})
  • Asynchronous processing semantics under Prefer: respond-async (whether the status code or any Location/monitoring header differs from the synchronous 204) — the spec documents only the header and the 204 response. (DELETE /api/v1/users/{id})
  • Password hash/hook validation and production KDF equivalence are outside this simulator scope. Private verifier is deterministic simulator state and never public response data. (DELETE /api/v1/users/{id}, POST /api/v1/users, POST /api/v1/users/{id}, POST /api/v1/users/{id}/lifecycle/expire_password_with_temp_password, POST /api/v1/users/{userId}/credentials/change_password, PUT /api/v1/users/{id})
  • _links.alternate, which Okta adds only for an org with a custom domain. (GET /.well-known/okta-organization)
  • Behavior when expand carries a malformed value or a userId not assigned to the app. (GET /api/v1/apps/{appId})
  • Exact _embedded payload for expand=group vs expand=metadata (open object in the schema). (GET /api/v1/apps/{appId}/groups)
  • Link header next/self pagination relations. (GET /api/v1/apps/{appId}/groups)
  • Whether a non-existent appId and a non-assigned groupId produce distinguishable errorCode/errorSummary values within the single documented 404 response. (GET /api/v1/apps/{appId}/groups/{groupId})
  • Link header pagination semantics (the concrete next cursor value and page boundaries) are not modeled beyond the header’s presence. (GET /api/v1/apps/{appId}/users)
  • Behavior when q is combined with after/limit (docs state paging and query are mutually exclusive but do not state the response) (GET /api/v1/groups)
  • Exact matching semantics of search/filter operators (sw, eq, co) against seeded groups (GET /api/v1/groups)
  • Link response header carrying the self/next pagination relations (GET /api/v1/groups)
  • Early Access expand=classification _embedded payload shape and classification.type search semantics. (GET /api/v1/users)
  • Status/body for a malformed or overly complex search/filter expression. (GET /api/v1/users)
  • The Link response header carrying the next/self pagination cursors (documented only by reference to the external pagination guide). (GET /api/v1/users)
  • A 401 for a missing or invalid credential is not documented for this operation and is not modeled. (GET /api/v1/users/{userId}/factors)
  • Which factors are actually returned depends on the org’s highest priority authenticator enrollment policy (only REQUIRED or OPTIONAL factors) and, for admin callers, on the admin client’s own client-specific conditions during policy evaluation. No policy resource is in scope, so that filtering is not modeled. (GET /api/v1/users/{userId}/factors)
  • Authenticator enrollment policy evaluation (which policy applies, and how the admin caller’s client-specific conditions such as network zone change the result) is not modeled: no policy resource is in scope. (GET /api/v1/users/{userId}/factors/catalog)
  • Whether a 404 is returned for a factor belonging to a different user (cross-user factorId) versus a plain unknown factorId is not documented. (GET /api/v1/users/{userId}/factors/{factorId})
  • Whether the OktaAccessGateway-Agent header changes any response behavior. (POST /api/v1/apps)
  • … and 102 more

Release notes: Changelog

Last updated on