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.
| Client | Version | Kind | Works with | Fails with | Checked | Known gap |
|---|---|---|---|---|---|---|
okta-mcp-server (PyPI) | v1.1.7 | mcp-server | — | default host | 2026-10-30 | 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. |
github.com/okta/okta-sdk-golang/v6 (Go) | v6.1.7 | sdk | proxy, default host | — | 2026-10-29 | — |
@okta/okta-sdk-nodejs (npm) | v8.2.0 | sdk | base URL, default host | — | 2026-10-30 | — |
okta (PyPI) | v3.4.7 | sdk | base URL, default host | — | 2026-10-30 | — |
okta/okta (Terraform) | v7.0.0 | terraform-provider | proxy, 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 carries | me is |
|---|---|
an X-Rystic-Actor header naming a user | that user, whatever the credential |
an X-Rystic-Actor header holding any other value, a login included | nobody: 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/v1or elsewhere, returns the simulator’s own 404 before theAuthorizationcheck, a known issue (Limitations). - A factor activation or verification outside the software-TOTP case the simulator models returns 501, with an
X-Rystic-Markerheader 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.
| List | after | Default limit | Largest limit | Link |
|---|---|---|---|---|
GET /api/v1/users | a user’s id | 200, or 10 with q | none | self, and next while more remain |
GET /api/v1/groups | a group’s id | every group, or 300 with q | 10000 | self, and next while more remain |
GET /api/v1/groups/{groupId}/users | a user’s id | 1000 | none | self, and next while more remain |
GET /api/v1/apps | the cursor next names | every app | none | next alone, as a path on the simulator’s origin |
GET /api/v1/apps/{appId}/users | the cursor next names | 50 | 500 | next alone |
GET /api/v1/apps/{appId}/groups | a group’s id | 20 | 200 | self and next while more remain |
- An id as the cursor. Where
afteris a record’s id, any record’s id resumes the list after that record. Anafternaming no record, or a cursor the simulator did not hand out, returns an empty page (unconfirmed). - Out of range. A
limitpast 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}/groupsandGET /api/v1/users/{userId}/factorstake neitherlimitnorafterand 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
| Resource | Operations |
|---|---|
| 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.
| Operation | Event types |
|---|---|
POST /api/v1/users | type set per call, by effect: eff_activation_email |
POST /api/v1/users/{id}/lifecycle/activate | type set per call, by effect: eff_activation_email |
Scenarios
The simulator ships 1 scenario; the quickstart boots design_studio.
| Scenario | What it is for | What it seeds | Clock |
|---|---|---|---|
design_studio (default) | Website Design Contractors’ org | group 11, group_membership 70, user 37 | 2026-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 placeholderACTIVEuser in Everyone, logintoken.owner@example.com) and Okta’s twoBUILT_INgroups, Everyone and Okta Administrators (which lists no members).
Seeding state
Each resource is one register, and each record goes in under its key:
| Register | Holds | Key |
|---|---|---|
state_user | a user | its id |
state_group | a group | its id |
state_group_membership | a group membership | <groupId>/<userId> |
state_application | an application | its id |
state_app_user | an application’s user assignment | <appId>/<userId> |
state_app_group_assignment | an application’s group assignment | <appId>/<groupId> |
state_user_factor | a factor | <userId>/<factorId> |
state_factor_challenge | a factor’s challenge | <userId>/<factorId> |
state_user_password | a password | its user’s id |
state_org | the org | its 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 witherrorCodeanderrorSummary. POST /oauth2/v1/tokenreturns 404, so okta-mcp-server’s Private Key JWT login at startup fails. The server exits before it responds toinitialize. Workaround: Before starting okta-mcp-server, store any unexpired JWT in its keyring as serviceOktaAuthManager, userapi_token. The server reuses that cached token and skips the token call. A placeholder HS256 token works, since the simulator accepts any token. Set itsexpyears ahead, because the server signs in again onceexpis 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-RemainingorX-Rate-Limit-Reset, which Okta sends on its Management API responses. GET /api/v1/appstakes alimitabove 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:
| Operation | Status | Why |
|---|---|---|
DELETE /api/v1/apps/{appId} | 429 | no request a client sends provokes it |
DELETE /api/v1/apps/{appId}/groups/{groupId} | 429 | no request a client sends provokes it |
DELETE /api/v1/apps/{appId}/users/{userId} | 429 | no request a client sends provokes it |
DELETE /api/v1/groups/{groupId} | 429 | no request a client sends provokes it |
DELETE /api/v1/groups/{groupId}/users/{userId} | 429 | no request a client sends provokes it |
DELETE /api/v1/users/{id} | 429 | no request a client sends provokes it |
DELETE /api/v1/users/{userId}/factors/{factorId} | 429 | no request a client sends provokes it |
GET /.well-known/okta-organization | 429 | no request a client sends provokes it |
GET /api/v1/apps | 429 | no request a client sends provokes it |
GET /api/v1/apps/{appId} | 429 | no request a client sends provokes it |
GET /api/v1/apps/{appId}/groups | 429 | no request a client sends provokes it |
GET /api/v1/apps/{appId}/groups/{groupId} | 429 | no request a client sends provokes it |
GET /api/v1/apps/{appId}/users | 429 | no request a client sends provokes it |
GET /api/v1/apps/{appId}/users/{userId} | 429 | no request a client sends provokes it |
GET /api/v1/groups | 429 | no request a client sends provokes it |
GET /api/v1/groups/{groupId} | 429 | no request a client sends provokes it |
GET /api/v1/groups/{groupId}/users | 429 | no request a client sends provokes it |
GET /api/v1/users | 429 | no request a client sends provokes it |
GET /api/v1/users/{id} | 429 | no request a client sends provokes it |
GET /api/v1/users/{id}/groups | 429 | no 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