> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ancha.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs describe the Ancha CLI, npm package @ancha-labs/cli version 0.1.4, and the hosted workspace at app.ancha.io. Coding agents should start at https://docs.ancha.io/coding-agents. Run the CLI as `ancha` after `npm install -g @ancha-labs/cli`, or as `npx -y @ancha-labs/cli@0.1.4` without installing. Pass --json for machine-readable output, or set ANCHA_JSON=1. Every command ends with a `next:` line naming the next command. Exit codes: 0 pass, 1 a check failed or a comparison regressed, 2 usage, config or authentication error, 3 infrastructure error, 4 unimplemented endpoint with --strict.

# Okta

> A stateful replica of Okta's Management API v1: users and their lifecycle, groups, applications and app assignments, and the System Log.

The Okta replica implements 31 endpoints of the Management API v1 for one org: users with their lifecycle states, groups, applications, app assignments and the System Log. Its key is `okta`. It was tested with `@okta/okta-sdk-nodejs`.

## Connect

| Variable | Value |
| - | - |
| `OKTA_ORG_URL` | The org URL. Paths start with `/api/v1/`. |
| `OKTA_API_TOKEN` | Fake SSWS API token. Send `Authorization: SSWS <token>`. |

```js Node theme={null}
import okta from '@okta/okta-sdk-nodejs';
const client = new okta.Client({ orgUrl: process.env.OKTA_ORG_URL, token: process.env.OKTA_API_TOKEN });
for await (const user of await client.userApi.listUsers()) console.log(user?.profile?.login);
```

This is what `ancha connect okta --lang ts` prints.

## Endpoints

All 31 endpoints are partial. Anything else returns HTTP 501 with Okta's error shape and `x-ancha-gap: 1`.

### Users

| Method | Path | Notes |
| - | - | - |
| `GET` | `/api/v1/users` | `q`, `filter` and `search` with the SCIM operators `eq`, `ne`, `sw`, `co`, `ew`, `gt`, `ge`, `lt`, `le` and `pr`; `limit` and `after`. Deprovisioned users appear only through `filter` or `search`. |
| `POST` | `/api/v1/users` | `activate` and `nextLogin`, the default profile schema and password policy, `groupIds`. |
| `GET` | `/api/v1/users/{id}` | By ID, login, or `me` for the token's owner. |
| `POST` | `/api/v1/users/{id}` | Partial profile update and password change. |
| `DELETE` | `/api/v1/users/{id}` | Deactivates first; deletes a deprovisioned user. |
| `GET` | `/api/v1/users/{id}/groups`, `/api/v1/users/{id}/appLinks` | |
| `DELETE` | `/api/v1/users/{id}/sessions` | |
| `POST` | `/api/v1/users/{id}/lifecycle/activate` | `sendEmail=false` returns an activation link. |
| `POST` | `/api/v1/users/{id}/lifecycle/deactivate`, `suspend`, `unsuspend`, `unlock` | |
| `POST` | `/api/v1/users/{id}/lifecycle/reset_password` | `sendEmail=false` returns a reset link. Nothing is emailed. |

### Groups

| Method | Path | Notes |
| - | - | - |
| `GET`, `POST` | `/api/v1/groups` | `q`, `filter`, `search`, `limit`, `after` and `expand=stats`. |
| `GET`, `PUT`, `DELETE` | `/api/v1/groups/{groupId}` | |
| `GET` | `/api/v1/groups/{groupId}/users` | |
| `PUT`, `DELETE` | `/api/v1/groups/{groupId}/users/{userId}` | |

### Applications

| Method | Path | Notes |
| - | - | - |
| `GET` | `/api/v1/apps` | `q`, `filter` (`status`, `name`, `user.id`, `group.id`), `limit` and `after`. |
| `GET` | `/api/v1/apps/{appId}` | |
| `GET`, `POST` | `/api/v1/apps/{appId}/users` | Direct (`USER`) and group (`GROUP`) assignments; `expand=user`. |
| `DELETE` | `/api/v1/apps/{appId}/users/{userId}` | |
| `GET` | `/api/v1/apps/{appId}/groups` | |
| `PUT`, `DELETE` | `/api/v1/apps/{appId}/groups/{groupId}` | |

### System Log

| Method | Path | Notes |
| - | - | - |
| `GET` | `/api/v1/logs` | `since`, `until`, `filter`, `q`, `sortOrder`, `limit` and `after`. Every change made through the API is logged. There is no polling next link. |

## Behavior

* One org, `acme`, and one SSWS token owned by the super administrator `ancha@acme.example`.
* Lifecycle changes are immediate. Activation and reset links are returned in the response, never emailed.
* The System Log holds the seeded events and every change the agent makes.

## Starter data

The `okta-starter` dataset is the org **Acme**.

| Record | Detail |
| - | - |
| Users | Twelve: the automation account `ancha@acme.example`, Mike Turner, Ben Carter, Rachel Moore, Greg Wilson, Laura Kim, Ellen Price and Anna Fischer (active); Tom Hughes (locked out 43 minutes before start after three failed sign-ins); Victor Lane (staged, created 26 hours ago); Iris Cole (suspended); Owen Marsh (deprovisioned). Profiles carry titles, departments, managers and employee numbers. |
| Groups | Engineering, Data Platform, On-call, Sales, Customer Success, Product, Finance, Leadership and IT Admins. |
| Applications | Eight SAML apps: Slack and Google Workspace for everyone; GitHub and Datadog for Engineering and Data Platform; PagerDuty for On-call; HubSpot for Sales and Customer Success; Snowflake for Data Platform; AWS for Engineering, plus Anna Fischer directly. |
| System Log | Ten events: Owen's deactivation, Iris's suspension, Victor's creation, Rachel's sign-in and single sign-on to PagerDuty, Tom's two failed sign-ins and lockout, and Ben's sign-in. |

## Checks

Okta has no state checks. Use trace checks, for example `{ called: "POST /api/v1/users/*/lifecycle/unlock" }` or `{ not_called: "DELETE /api/v1/users/*" }`.

## Limits

* One org and one SSWS token; no OAuth service apps, factors, policies or sign-in flows.
* Nothing is emailed: activation and reset links come back in the response.
* The System Log gives no polling next link.


## Related topics

- [Checks reference](https://docs.ancha.io/reference/checks.md)
- [ancha connect](https://docs.ancha.io/cli/connect.md)
- [Tools](https://docs.ancha.io/tools/overview.md)
- [Test file (scene.yaml)](https://docs.ancha.io/reference/test-file.md)
- [Introduction](https://docs.ancha.io/index.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.