# Add the Okta connector in Axiad Mesh

This is the second half of the Okta integration. Complete
[Set up Okta for Axiad Mesh](./okta-portal-setup.mdx) first — you need the
**API token** before you start here.

## Before you begin

Have these ready:

- Your **Okta org URL**, over HTTPS — for example `https://acme.okta.com`.
- The **API token** you created in Okta.
- A Mesh administrator account with permission to manage connectors.

> **note**
This wizard authenticates with an Okta API token. The OAuth service app
method is not wired up yet, so follow the API token option in the Okta half
of the guide.

## Open the wizard

In the Mesh portal, go to **Settings → Connectors** and select
**Add connector**.

![The Connectors page in Mesh settings, with the Add connector button in the top right](/img/connectors/okta/mesh-01-connectors-list.png)

Choose **Okta** under **Guided setup**.

![The Add connector dialog, with Okta listed under Guided setup](/img/connectors/okta/mesh-02-add-connector.png)

> **note**
The list also has an older **Okta Single-sign-on** entry further down, under
**Manual setup**. That is a different, earlier connector. This guide covers
the **Okta** entry under **Guided setup**.

The wizard has five steps — **Identify**, **Authenticate**, **Collect**,
**Tuning** and **Review**. The rail on the left tracks where you are and
summarizes each finished step. Steps ahead of an incomplete one stay locked
until you can reach them.

## Step 1 — Identify

Enter a display name for the connector and your Okta org URL.

The URL must be HTTPS on an Okta domain: `.okta.com`, `.oktapreview.com`,
`.okta-emea.com`, or `.okta-gov.com`. No path, no query string.

![Step 1, Identify, with the Connector name and Okta org URL fields and the fixed-after-creation notice](/img/connectors/okta/mesh-03-step1-identify.png)

> **warning**
The org URL identifies the source of everything Mesh ingests through this
connector, so it cannot be changed later. Check it before you continue. To
read a second Okta org, add a second connector.

The display name is only a label — it appears in the connector list and in
reports, and you can change it whenever you like.

## Step 2 — Authenticate

Paste the API token into **Okta API token**.

![Step 2, Authenticate, with the Okta API token field](/img/connectors/okta/mesh-04-step2-authenticate.png)

Paste the token exactly as Okta issued it. Mesh sends it as
`Authorization: SSWS`, the scheme Okta's Management API requires, so the value
needs no prefix of its own. There is no client ID to enter: an API token
carries its own identity. Mesh encrypts the token at rest and never shows it
again — after saving, only a short fingerprint of it is displayed.

Select **Test connection**. **You cannot continue until the test passes.**
Changing the token clears a previous pass, and you have to test again.

A pass shows a green **Connected** banner and unlocks **Continue**. It means
Okta accepted the credential — it does **not** mean every endpoint returns
data. That is checked by the sample read on step 5.

If the test fails, the wizard says which kind of failure it was:

| Error | Meaning | What to do |
| --- | --- | --- |
| Authentication | Okta rejected the token | Check the value, and confirm the token has not been revoked or expired |
| Communication | Mesh could not reach Okta | Re-check the org URL on step 1 |

## Step 3 — Collect

Choose what Mesh reads. Endpoints are grouped by domain — Directory,
Applications, Security — and each row shows the Okta API path it calls, so you
can see exactly what a selection means. The checkbox on a domain header
selects or clears that whole domain.

![Step 3, Collect, with the endpoint groups Directory, Applications and Security all selected](/img/connectors/okta/mesh-06-step3-collect.png)

Your selection is saved with the connector and applied on its next run —
endpoints you clear are not called. Leave everything selected unless you have
a reason not to; clearing an endpoint removes the data it feeds, and anything
Mesh derives from that data goes with it.

Whatever you select here, Mesh stores the same four sets of Okta records:
users, groups, group memberships and sign-in events.

## Step 4 — Tuning

Optional. Every setting on this step has a default that works, so you can
accept them all and move on.

![Step 4, Tuning, with the sync frequency, request rate and retry options](/img/connectors/okta/mesh-07-step4-tuning.png)

| Setting | Default | When to change it |
| --- | --- | --- |
| **How often should Mesh read?** | Every hour | Every 15 minutes to see joiners and leavers sooner; twice a day to keep API load low |
| **Request rate** | Standard — 10 requests a second, 4 at once | Gentle if your Okta org already throttles, or if other integrations share the tenant; Fast only on a higher-tier Okta plan |
| **If Okta stops responding** | Keep trying — 5 attempts | Give up quickly if you would rather see a failure reported sooner than have the run ride out an Okta incident |
| **Records per request** | 100 | Smaller pages on slow links, larger pages for a big org |

This is also where the sync frequency lives — not on the Collect step.

## Step 5 — Review

The wizard runs a **sample read** against your org and reports what it found
for each category, then summarizes the configuration you are about to create.

![Step 5, Review and create, with per-category sample read results and the configuration summary](/img/connectors/okta/mesh-08-step5-review.png)

Read the per-category results before you create the connector. A `SUCCESS`
row with a record count means Mesh reached that endpoint and Okta returned
data. A `FAILURE` row names the reason — in the frame above the System log
read came back `http 429 Too Many Requests`, which is Okta rate-limiting the
org rather than anything wrong with the configuration.

Select **Run sample again** to retry after fixing something, or
**Create connector** to finish. Creating the connector closes the wizard.

> **danger**
This is almost always the Okta admin role, not the connector. A token can
hold the right scopes and still see only part of the org. Go back to
[Set up Okta](./okta-portal-setup.mdx) and confirm the account behind the
token has the **Read-only Administrator** role, with resource sets set to
**All**.

## Managing the connector

Back on the connector list, each row shows the provider, health and sync
status. The **Status** toggle enables or disables scheduled collection.

The row menu holds the rest:

![The connector row menu, showing View collections, Logs, Edit and Run now](/img/connectors/okta/mesh-09-row-menu.png)

| Action | What it does |
| --- | --- |
| **View collections** | Record counts and last-updated times per data type |
| **Logs** | Collection run history |
| **Edit** | Change the configuration — everything except the org URL |
| **Run now** | Trigger a collection immediately, without waiting for the schedule |

> **note**
Once saved, the token is displayed only as a fingerprint. If you lose the
original value, create a new token in Okta and update the connector.

## Verify the collection

1. Open **View collections** and confirm the first collection completed.
2. Compare the collected user and group counts against your Okta org.

A collection that finishes but returns noticeably fewer records than your org
holds is usually a permission problem rather than a connection problem — see
the next section.

## Troubleshooting

| Symptom | Likely cause | What to do |
| --- | --- | --- |
| Test connection fails with an authentication error | The token is wrong, revoked, or expired | Issue a fresh token in Okta and paste it again |
| Test connection fails with a communication error | The org URL is wrong or not reachable | Re-check the URL on step 1 |
| A category on step 5 reports `http 429 Too Many Requests` | Okta is rate-limiting the org | Re-run the sample, or set **Request rate** to Gentle on step 4 |
| Collection completes, but far fewer records than expected | The token's account has the right scopes but **no admin role**, or a custom role bound to a narrowed resource set | Assign **Read-only Administrator**, and set every resource set to **All** |
| Users and groups arrive, but no sign-in events | `okta.logs.read` was not granted, or a **custom** admin role is in use and cannot read the System Log | Grant the scope, and switch to the standard Read-only Administrator role |
| Authentication fails from a token that worked before | The token is IP-restricted and Mesh's addresses changed, or the token expired | Confirm the IP zone with Axiad support, or issue a new token |
| Collection is slower than expected | Okta is rate-limiting your org | No action needed. Mesh reads Okta's rate-limit headers and slows itself before hitting a limit, then retries. |
| The org URL is wrong and **Edit** will not let you change it | The org URL is fixed once the connector exists | Create a new connector with the correct URL, then disable the old one |

If a problem persists, contact Axiad support with the connector name, the time
of the failed collection, and the step the wizard stopped on.