AtomationDocsOkta API access guideAutomate Okta API Services app setup
Create the Okta API Services app Atomation uses for assessments without an OIN API Service Integration or shared client secret. Setup uses a temporary Okta API token (SSWS) created by a Super Administrator, assigns Super Administrator to the permanent app, configures private_key_jwt, JWKS, DPoP, and exact grants, and succeeds only after revocation is confirmed.
Before you begin
This is the assessment data connection — a scoped Okta API Services app, separate from SSO and SCIM sign-in. Atomation uses this connector to read Okta posture data, capture evidence, and run assessment scans. It is not the Okta OIN SAML/SCIM app and it does not use an OIN-generated client secret.
You'll need:
- An Okta admin with the Super Admin role, for the one-time setup — creating the API Services app, assigning the app role, and granting Okta API scopes requires it.
- A temporary Okta API token (SSWS) created by that admin. It inherits the creator's full Super Administrator privileges while active. Atomation uses it once, does not store it, and fails setup unless Okta confirms revocation.
- The Okta org URL you are connecting, for example
https://your-org.okta.comorhttps://your-org.oktapreview.com. - No Okta add-ons required. Atomation connects through your org authorization server, which every OIE org has — the Okta API Access Management add-on is not needed (that add-on is only for building custom authorization servers).
The temporary setup action creates and configures the Okta API Services app and currently assigns it Super Administrator for complete assessment visibility. After setup, routine scan tokens request only the 31 approved read scopes. The permanent app also holds okta.appGrants.manage, which Okta defines as org-level application-grant management, not a self-only scope. Atomation excludes it from scans and reserves it for a future reviewed connector-update workflow targeting the configured connector app.
Test an Okta Preview org first when you have one
Before connecting a production org, we recommend connecting an available.oktapreview.com org. This lets your team run the same guided API Services app setup, use the temporary Okta API token (SSWS), review findings and framework mappings, and understand the scan-to-report workflow without starting in production.
A Preview org retains only its most recent completed scan and generated report. You can rescan, but when the new scan finishes and its report is generated, Atomation removes the previously retained Preview scan and report. Download each PDF or Markdown report before rescanning if you want to keep it as a record.
Each Preview org counts as a connected org in your purchased or pilot org allowance. The same rule applies whether the workspace is a direct-customer workspace or a client workspace managed through an Atomation partner.
Automated setup Recommended
Atomation's guided setup replaces the long manual app-creation checklist with one controlled run. You paste the Okta org URL and a temporary Okta API token, click Save & run setup, and Atomation configures the connector in your Okta org.
Create a temporary Okta API token
In Okta, create an API token from a Super Admin account used for setup. This token inherits that account's full privileges while active, is used only to create/configure the API Services app, and is not stored as an Atomation connector credential.
Run the Atomation setup
Atomation creates the API Services app, sets private_key_jwt client authentication, registers the workspace JWKS URL, enables DPoP, assigns Super Administrator to the permanent app, hides it from end-user app portals, and grants the 31 approved assessment reads plus okta.appGrants.manage. Okta evaluates both requested token scopes and the assigned admin role.
Verify and revoke
Atomation exchanges a DPoP-bound token, reads the app's actual Okta grants, verifies the required scope list, rejects unapproved Okta scopes, revokes the temporary Okta API token, and displays the revocation result so you can validate it in Okta System Log. If revocation is not confirmed, setup fails and cleanup runs.
Atomation stores the Okta org URL, API Services app Client ID, public JWKS URL reference, verification status, and approved scope list. The temporary Okta API token is not retained; setup succeeds only after Okta confirms its revocation.
Why this is outside OIN today
Atomation's SAML SSO and SCIM provisioning app can be tested through Okta OIN flows, but the assessment connector is different: it is an Okta API Services app used for customer-owned posture scanning. Today, Atomation configures that app directly in the customer's Okta org instead of asking the customer to install an OIN API Service Integration that defaults to a shared client secret.
Our view is that Okta API Service OIN apps should support this same secure posture:private_key_jwt client authentication, a customer-specific JWKS URL, DPoP-bound tokens, a transparent scope manifest, exact grant verification, and proof that any setup Okta API token was revoked. That gives customers the simplicity of a catalog-style setup without hiding the grants or leaving a reusable setup token behind.
This API access guide is separate from the Okta SAML and SCIM setup guides. Use the SAML and SCIM guides for workspace login and provisioning. Use this page only for the assessment data connector.
Manual fallback
If your security process does not allow a temporary Okta API token, you can still create the same API Services app manually. The app should end in the same state: no shared client secret, private_key_jwt with the Atomation JWKS URL, DPoP enabled, Super Administrator assigned, approved scopes granted, and no unapproved Okta scopes.
Values you'll use
Automated setup fills these in for you. Use them if you need the manual fallback or want to compare the Okta app after setup.
| Setting | Value |
|---|---|
| Tenant subdomain | TENANT-SUBDOMAIN |
| Tenant JWKS URL | https://TENANT-SUBDOMAIN.atomation.io/.well-known/okta-jwks.json |
| App name | CLIENT Okta Assessment Service - ENVIRONMENT |
| Okta org URL | https://OKTA-ORG.okta.com or https://OKTA-ORG.oktapreview.com |
Approved scopes: 31 reads + 1 maintenance grant (32 total)
Atomation uses the 31 scopes below to read assessment evidence. The permanent app also holdsokta.appGrants.manage. Okta defines that scope as org-level application-grant management; it is not inherently restricted to this app. Atomation does not request it in routine scan tokens and reserves it for a future reviewed connector-update workflow whose target app id is bound to the configured Atomation connector.
Atomation verifies the scopes actually granted to the API Services app. Missing assessment scopes are flagged, and any Okta scope outside the approved assessment and maintenance list blocks verification until removed in Okta.
okta.users.readokta.groups.readokta.apps.readokta.appGrants.readokta.clients.readokta.authorizationServers.readokta.policies.readokta.idps.readokta.devices.readokta.deviceAssurance.readokta.behaviors.readokta.networkZones.readokta.threatInsights.readokta.eventHooks.readokta.inlineHooks.readokta.features.readokta.certificateAuthorities.readokta.brands.readokta.emailDomains.readokta.emailServers.readokta.customTelephonyProvider.readokta.templates.readokta.authenticators.readokta.factors.readokta.apiTokens.readokta.trustedOrigins.readokta.logStreams.readokta.roles.readokta.userTypes.readokta.schemas.readokta.orgs.readokta.appGrants.manageSetup steps
Create the API Services app
In the Okta Admin Console, open Applications → Applications, click Create App Integration, choose API Services, and name it CLIENT Okta Assessment Service - ENVIRONMENT.
Register the JWKS URL and copy the Client ID
Under Client Credentials, set Public key / Private key, choose Use a URL to fetch keys dynamically, and paste your tenant JWKS URL. Save, then copy the Client ID.
Assign the app role
On the Admin Roles tab, assign Super Administrator to the API Services app so Okta allows the required management API reads and Atomation can audit the app's granted scopes. Okta applies the assigned role together with the scopes requested in each token.
Grant the approved scopes
On the Okta API Scopes tab, Grant each scope from the approved list above. Do not grant additional Okta scopes. If the Grantbutton is grayed out, ask an administrator with permission to grant Okta API scopes to finish this step. Enable Require Demonstrating Proof of Possession (DPoP)for the API Services app before verifying.
Verify in Atomation
Paste the Client ID into Atomation and click Verify API connection. Atomation reads the app's actual granted scopes, marks missing approved scopes red, and rejects any unapproved Okta scopes. Fix the grants in Okta and verify again until the scope review is clean.
Verify
You're connected when Atomation confirms all six:
- Token acquired — the service app authenticates against your org.
- Exact grants — all approved assessment scopes and the approved maintenance scope are granted, and no unapproved Okta scopes are present.
- Scopes usable — all 31 assessment read scopes are available to the scanner.
- Role sufficient — the admin role allows the reads (no
403). - DPoP enabled — access tokens are bound to the app's key pair.
- Verified timestamp — Atomation records the last successful check.
Atomation then captures the first snapshot, and your report appears in your workspace.
Troubleshooting
| Error | Likely cause | Fix |
|---|---|---|
invalid_client | Client ID mismatch, JWKS URL not saved, or public key not reachable. | Re-check the Client ID, tenant JWKS URL, and Client Credentials settings. |
| Scope denied | An approved scope was not granted to the service app. | Open the Okta API Scopes tab and grant the missing approved scope. |
403 on read calls | Token is valid, but the admin role is missing or too narrow. | On Admin Roles, assign Super Administrator to the API Services app. |
| DPoP failure | The Okta API Services app does not require DPoP, or the setting was not saved. | Enable Require Demonstrating Proof of Possession (DPoP), save the app, and verify again. |
| Unapproved scopes | The API Services app has Okta scopes outside the approved assessment and maintenance list, commonly from using a broad grant-all flow. | Remove every scope that is not listed in Approved scopes. Any unapproved .manage, .register, or unrelated scope must be removed before Atomation will mark the connection healthy. |
Still stuck? Email [email protected] with your Okta domain, the step that failed, and a timestamp — we'll walk through it with you.
Okta reference
Next steps
Compliance standards, manual evidence, and first-scan readiness.