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

# Okta

> Connect Okta to CloudThinker for identity access reviews, sign-in investigation, and approval-gated group management

Connect your Okta organization to let CloudThinker agents review users, groups, application access, and sign-in activity. Agents can also create CloudThinker-owned groups and change their exact memberships after you approve each write.

## Prerequisites

* An Okta administrator who can create an API token.
* Read access to the users, groups, applications, and System Log data agents should investigate.
* Group-management permission if agents should create groups or change membership.

<Info>
  An Okta API token carries the permissions of the administrator who creates it. Use a dedicated administrator with the least-privilege role that covers the intended reviews and groups.
</Info>

## Setup

<Steps>
  <Step title="Create an API token">
    In the Okta Admin Console, go to **Security → API → Tokens**, select **Create token**, and name it `cloudthinker`.

    Copy the value immediately. Okta shows it once and expires a token that goes 30 days without a request.
  </Step>

  <Step title="Find your Okta domain">
    Copy the organization domain from the top-right corner of the Admin Console. Use only the hostname, such as `acme.okta.com` or `acme.okta-emea.com`.

    Do not include `https://`, a port, a path, or credentials. Prefer the plain organization domain over the `-admin` console domain.
  </Step>

  <Step title="Add the connection in CloudThinker">
    Go to **Connections → Okta** and enter:

    * **Okta domain**: the organization hostname
    * **API token**: the token you copied

    Select **Connect**. CloudThinker reads the organization settings and shows **Connected** with the verified organization and status.
  </Step>
</Steps>

## Connection details

| Field           | Description                                             | Example         |
| --------------- | ------------------------------------------------------- | --------------- |
| **Okta domain** | Bare Okta organization hostname, with no scheme or path | `acme.okta.com` |
| **API token**   | Token from **Security → API → Tokens**                  | —               |

Connection verification reads organization settings only.

## Required permissions

The API token inherits its creator's administrator roles. Assign the dedicated service account the **Read-only Administrator** role for users, groups, applications, organization settings, and the System Log.

If agents should manage CloudThinker-owned groups, add a custom administrator role with **Create groups**, **Manage group membership**, and **Edit users' group membership**. Constrain the membership permissions to the intended group resources; Okta requires **Create groups** at organization scope.

| Use                       | Okta access needed                                       |
| ------------------------- | -------------------------------------------------------- |
| **Access reviews**        | Read-only Administrator                                  |
| **Sign-in investigation** | Read-only Administrator                                  |
| **Create managed groups** | Create groups                                            |
| **Add or remove members** | Manage group membership and Edit users' group membership |

An HTTP 403 means the token's administrator role cannot read or change that resource. It does not mean the resource is absent.

## Agent capabilities

Once connected, agents can:

| Capability                | Description                                                                                 |
| ------------------------- | ------------------------------------------------------------------------------------------- |
| **Identity inventory**    | Read bounded samples of users and groups, including user status                             |
| **Person access review**  | Trace one exact user to their groups, applications, and recent events                       |
| **Sign-in investigation** | Review bounded System Log windows for failures, lockouts, actors, and client IPs            |
| **Application access**    | Compare direct-user and group assignments, including inactive applications with assignments |
| **Group creation**        | Create a CloudThinker-owned `OKTA_GROUP` after approval                                     |
| **Membership control**    | Add or remove one exact user from one exact CloudThinker-owned group after approval         |

Okta list endpoints return cursors, not organization totals. Agents report bounded rows and whether more pages exist.

### Verify the connection

```text theme={null}
@alex run Okta discovery and #report the users, groups, applications, and credential capabilities in the bounded result
```

### Example prompts

```text theme={null}
@alex review what alex@example.com can access in Okta over the last 7 days
@alex investigate failed Okta sign-ins in the last 24 hours and group them by outcome
@alex create an Okta group named CloudThinker-OnCall and add alex@example.com after I approve each change
```

## Write access

Okta write access is not general administration. Every write needs your approval and a fresh discovery read against the selected organization.

| Supported write   | Safety boundary                                                                                            |
| ----------------- | ---------------------------------------------------------------------------------------------------------- |
| Create a group    | Creates an `OKTA_GROUP` with a signed CloudThinker ownership receipt bound to its immutable group ID       |
| Add one member    | Requires the exact group ID, exact current group name, valid ownership receipt, and exact user login or ID |
| Remove one member | Uses the same checks and verifies the resulting membership state                                           |

Agents refuse group update or deletion, user lifecycle changes, factors, credentials, sessions, tokens, administrator roles, application assignments, policies, and changes to unowned groups. Multiple Okta connections stay read-only until one is selected.

## Troubleshooting

<Accordion title="Okta rejected the API token (401)">
  The token is wrong, revoked, or expired after 30 days without a request. Check **Security → API → Tokens**, then reconnect with a current token.
</Accordion>

<Accordion title="The token cannot read this resource (403)">
  The token is valid, but its creator's administrator role lacks access to the endpoint. Give the dedicated administrator the required read or group-management permission, create a new token if needed, and reconnect.
</Accordion>

<Accordion title="The organization domain is rejected">
  Enter only the Okta-hosted hostname. Remove the scheme, port, path, query, and credentials. Prefer `acme.okta.com` over `acme-admin.okta.com`.
</Accordion>

<Accordion title="Okta rate-limited the request (429)">
  Wait for the rate-limit window to reset before running the request again. Do not retry immediately.
</Accordion>

<Accordion title="A write is refused">
  Confirm that the agent selected one exact Okta connection, that the token's administrator can manage groups, and that the target is a CloudThinker-owned `OKTA_GROUP`. Other Okta mutations are intentionally unsupported.
</Accordion>

## Security

* **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later.
* **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection.
* **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
* **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves.

- **Dedicated administrator** — the token inherits its creator's access, so use a least-privilege account instead of a personal super administrator.
- **Bounded writes** — approval alone does not grant arbitrary mutation; scripts restrict changes to signed CloudThinker-owned groups and verify the final state.

## Related

<CardGroup cols={2}>
  <Card title="Keycloak Connection" icon="https://mintcdn.com/cloudthinker/CGWam0VVP8R5KVLk/images/icons/keycloak.svg?fit=max&auto=format&n=CGWam0VVP8R5KVLk&q=85&s=ec65e48f0913c7c687e6c84c2ffceb1f" href="/guide/connections/keycloak" width="24" height="24" data-path="images/icons/keycloak.svg">
    Identity and access management for Keycloak
  </Card>

  <Card title="Approval" icon="shield-check" href="/guide/approval">
    Control how agent write tools request approval
  </Card>
</CardGroup>