Add the Okta connector in Axiad Mesh
This is the second half of the Okta integration. Complete Set up Okta for Axiad Mesh 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.
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.
Choose Okta under Guided setup.
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.
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.
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.
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.
| 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.
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.
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 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:
| 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 |
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
- Open View collections and confirm the first collection completed.
- 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.