# Okta

The Okta connector reads users, groups, group memberships and sign-in activity
from an Okta Workforce Identity org, so Mesh can correlate those identities with
accounts from every other connected system.

It is **read-only**. Every request it makes is a read request; it never creates,
changes or deletes anything in your Okta org.

## What it reads

| From Okta | Becomes in Mesh |
| --- | --- |
| Users and their profiles | User accounts |
| Enrolled MFA authenticators | Credentials |
| Groups and their members | Groups and membership |
| Applications and who can use them | Applications and assignments |
| Sign-in events | Sign-in activity |

Reading that needs **four permissions** in Okta and nothing more:
`okta.users.read`, `okta.groups.read`, `okta.apps.read`, and `okta.logs.read`.

For the full field-level detail — every endpoint, every mapped attribute — see
the [Okta connector reference](../okta.mdx).

## Setup

Setting Okta up has two halves. Do them in order.

| Step | What you do | Where |
| --- | --- | --- |
| **[1. Set up Okta](./okta-portal-setup.mdx)** | Create the credential and grant the four read permissions | Okta Admin Console |
| **[2. Set up in Mesh](./mesh-setup.mdx)** | Add the connector with the five-step wizard and verify the first collection | Axiad Mesh |

You need the credential from the first half before you can finish the second,
so start in Okta.

> **tip**
Okta offers two ways to authorize a read-only integration: an **OAuth service
app**, which is limited to exactly the four permissions above, and an **API
token**, which is limited by the admin role of the account that created it.
The first half of the guide covers both, but the Mesh connector authenticates
with an **API token** today — the service app method is not wired up yet.

## A trap worth knowing about before you start

Okta controls access two ways, and only one of them fails loudly.

- The wrong **permission** makes Okta refuse the request outright. You will see
  the error.
- The wrong **admin role** makes Okta answer normally, but with **fewer records
  than exist**. Nothing looks wrong.

That second case is the most common cause of an Okta connector that appears
healthy while under-reporting. Both setup pages call out where it bites.