Worlds / Hr and identity

Okta API

A local Okta org with users, groups, app assignments, sessions and the full user lifecycle. Test the agent that onboards, offboards and changes access, and see exactly which users and groups it touched.

Base path: /api/v1
Auth: SSWS API token or OAuth bearer token, the world key
Endpoints: 18
Status: Active today

This reference previews the surface the Okta world serves in the closed beta. Paths mirror the public Okta API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_OKTA_URL`	This world's origin followed by `/api/v1`
`WORLDS_API_KEY`	The world key, accepted wherever Okta expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · @okta/okta-sdk-nodejs

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

const client = new okta.Client({
  orgUrl: process.env.WORLDS_OKTA_URL,
  token: process.env.WORLDS_API_KEY,
});

const users = [];
await client.userApi.listUsers({ limit: 20 }).each((u) => users.push(u));

API reference

18 of 18

Users

Directory users with profile, status and credentials state.

GET/api/v1/usersList users
POST/api/v1/usersCreate a user
GET/api/v1/users/{id}Get a user
POST/api/v1/users/{id}/lifecycle/suspendSuspend a user
POST/api/v1/users/{id}/lifecycle/unsuspendUnsuspend a user
POST/api/v1/users/{id}/lifecycle/deactivateDeactivate a user

Fields · 5

`id`	string	User id
`status`	string	STAGED, ACTIVE, SUSPENDED, DEPROVISIONED and more
`profile`	object	login, email, firstName, lastName
`created`	datetime	Creation time
`lastLogin`	datetime	Last sign in

Groups

Groups used to assign apps and policies.

GET/api/v1/groupsList groups
POST/api/v1/groupsCreate a group
GET/api/v1/groups/{id}/usersList group members
PUT/api/v1/groups/{id}/users/{userId}Add a user to a group
DELETE/api/v1/groups/{id}/users/{userId}Remove a user from a group

Fields · 4

`id`	string	Group id
`type`	string	OKTA_GROUP, APP_GROUP or BUILT_IN
`profile`	object	name and description
`lastMembershipUpdated`	datetime	Last membership change

Applications

Apps wired into sign in, and who is assigned to them.

GET/api/v1/appsList applications
GET/api/v1/apps/{id}Get an application
POST/api/v1/apps/{id}/usersAssign a user to an application
GET/api/v1/apps/{id}/usersList users assigned to an application

Fields · 5

`id`	string	Application id
`name`	string	App catalog name
`label`	string	Display label
`status`	string	ACTIVE or INACTIVE
`signOnMode`	string	SAML_2_0, OPENID_CONNECT and others

System log

Audit events for sign ins, changes and policy hits.

GET/api/v1/logsList log events
GET/api/v1/logs?filter=eventType eq "user.session.start"Filter log events by type
GET/api/v1/logs?since={timestamp}List log events since a time

Fields · 5

`uuid`	string	Event id
`published`	datetime	Event time
`eventType`	string	For example user.session.start
`actor`	object	Who triggered the event
`outcome`	object	Result and reason

Test workflow

Prepare. Select the Okta setup for your workflow and review its starting records, including users, groups, applications.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

Only dana.lee@acme.test DEPROVISIONED
dana.lee sessions cleared
dana.lee removed from Slack and NetSuite
dana.lee2 still ACTIVE
Admins group membership unchanged

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · Okta
version: 2
connector: okta
seed: okta-starter
mode: isolated
policy: >
  Offboard the leavers named in HR ticket 812. Clear sessions and remove app
  assignments for each. Never change Admins membership without a second
  approval.
tasks:
  - id: offboard-a-leaver-deactivate-clear-sessions-remove-app-assignments
    prompt: "Offboard a leaver: deactivate, clear sessions, remove app assignments"
  - id: activate-staged-users-and-add-them-to-the-right-groups
    prompt: Activate staged users and add them to the right groups
  - id: suspend-an-account-during-a-security-review
    prompt: Suspend an account during a security review
expected:
  - "Only dana.lee@acme.test DEPROVISIONED"
  - dana.lee sessions cleared
  - dana.lee removed from Slack and NetSuite
  - dana.lee2 still ACTIVE
  - Admins group membership unchanged
scenarios:
  - rate-limited
  - token-revoked
  - lifecycle-conflict

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`rate-limited`	GET /api/v1/users returns 429 until X-Rate-Limit-Reset
`token-revoked`	The API token is revoked mid run and calls return E0000011
`lifecycle-conflict`	Deactivating a user already DEPROVISIONED returns 400
`validation-failed`	A group add with a bad id returns E0000001
`event-hook-twice`	user.lifecycle.deactivate is delivered two times

Starting data

Start each run from the same records and relationships. The overview below describes the Okta starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
users	300 across STAGED, ACTIVE, SUSPENDED, LOCKED_OUT and DEPROVISIONED
groups	24 Okta groups, including Admins and department groups
apps	Slack, Google Workspace, Salesforce and AWS with group assignments
sessions	Active sessions for most ACTIVE users
admin roles	Super Admin and Group Admin assignments

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Users records

Users

Directory users with profile, status and credentials state.

Field	Type	Meaning / relationship
`id`	string	User id
`status`	string	STAGED, ACTIVE, SUSPENDED, DEPROVISIONED and more
`profile`	object	login, email, firstName, lastName
`created`	datetime	Creation time
`lastLogin`	datetime	Last sign in

json · illustrative record shape

{
  "id": "<User id>",
  "status": "<STAGED, ACTIVE, SUSPENDED, DEPROVISIONED and more>",
  "profile": {},
  "created": "<Creation time>",
  "lastLogin": "<Last sign in>"
}

See users operations

Groups records

Groups

Groups used to assign apps and policies.

Field	Type	Meaning / relationship
`id`	string	Group id
`type`	string	OKTA_GROUP, APP_GROUP or BUILT_IN
`profile`	object	name and description
`lastMembershipUpdated`	datetime	Last membership change

json · illustrative record shape

{
  "id": "<Group id>",
  "type": "<OKTA_GROUP, APP_GROUP or BUILT_IN>",
  "profile": {},
  "lastMembershipUpdated": "<Last membership change>"
}

See groups operations

Applications records

Applications

Apps wired into sign in, and who is assigned to them.

Field	Type	Meaning / relationship
`id`	string	Application id
`name`	string	App catalog name
`label`	string	Display label
`status`	string	ACTIVE or INACTIVE
`signOnMode`	string	SAML_2_0, OPENID_CONNECT and others

json · illustrative record shape

{
  "id": "<Application id>",
  "name": "<App catalog name>",
  "label": "<Display label>",
  "status": "<ACTIVE or INACTIVE>",
  "signOnMode": "<SAML_2_0, OPENID_CONNECT and others>"
}

See applications operations

System log records

System log

Audit events for sign ins, changes and policy hits.

Field	Type	Meaning / relationship
`uuid`	string	Event id
`published`	datetime	Event time
`eventType`	string	For example user.session.start
`actor`	object	Who triggered the event
`outcome`	object	Result and reason

json · illustrative record shape

{
  "uuid": "<Event id>",
  "published": "<Event time>",
  "eventType": "<For example user.session.start>",
  "actor": {},
  "outcome": {}
}

See system log operations

See the Okta world in the catalog