Before you start
- Before you start: turn on MFA in Seven21. Owners and Admins need an authenticator app before Directories Sync will accept a connect. Open Account (avatar menu) or /app/mfa and finish setup (including saving recovery codes).
- Who: Seven21 Owner or Admin, plus an Okta Super Admin (or an admin who can create API Services apps, grant Okta API scopes, assign app admin roles, or create API tokens).
- Time: About 15 to 20 minutes.
- Seven21 will read: Users, groups, active assigned SaaS apps and assignments, and recent SSO sign-in from system log.
- Access: read-only for directory sync. Seven21 does not remove people in the provider admin console.
Import people and every assigned SaaS app from Okta, without connecting each app individually.
Turn on MFA in Seven21
- Owners and Admins need an authenticator app before Directories Sync will accept a connect.
- Open Account (avatar menu) or /app/mfa, finish setup, and save recovery codes.
Create an Okta API Services app (preferred)
- In the Okta Admin Console, open Applications, then Applications, then Create App Integration. Choose API Services. (Some orgs show Applications and Resources, then Applications. If you see Classic experience, use that create path.)
- Name it for Seven21 and save.
- On General, set Client authentication to Public key / Private key. Add or generate a key and download the private key (PEM). Okta shows the private key once.
- Open Admin roles on the app. Edit assignments and assign a read-capable admin role (for example, Read-only Administrator). Save. Scopes alone are not enough without an admin role on the service app.
- Open Okta API Scopes. A Super Admin must Grant each required scope below.
- Copy the Client ID from the app.
Required OAuth scopes
okta.apps.read
okta.users.read
okta.groups.read
okta.logs.readAdmin role required: Okta requires an admin role on every OAuth service app. Without Admin roles assigned, token minting can succeed and API calls still return 403.
Or create an API token (fallback)
- In Okta Admin, go to Security, then API, then the Tokens tab, then Create token.
- Name the token. Create it with an admin account (or custom admin role) that can read applications, users, groups, and system log.
- Copy the token immediately. Okta will not show the full token again.
Prefer the service app: OAuth service apps use shorter-lived tokens and scoped access. Use an API token only when you cannot create an API Services app.
Connect in Seven21
- Open Directories Sync, then Okta (or /app/settings/integrations/okta).
- Enter the Okta org URL (https://acme.okta.com; also okta-emea, oktapreview, okta-gov).
- Paste either the service app Client ID and private key PEM, or the API token.
- Click Test and connect. Seven21 validates the host, confirms the org, and stores secrets encrypted (last 4 only in the UI).
- On Subscriptions, review Apps found in Okta and Add only the apps you want. Nothing is added automatically. Optionally Preview people to import the roster into People.
Permissions checklist
- okta.apps.read: List active apps and assignments.
- okta.users.read: People roster and status.
- okta.groups.read: Expand group assignments to users.
- okta.logs.read: Last SSO sign-in (unused license signal).
Confirm it worked
Connection saved. Discovered apps appear on Subscriptions for opt-in review. Sync now (or the daily sync) refreshes people and the discovered list without creating subscriptions. Cost stays blank until you Add cost.
Troubleshooting
- Rejected credentials or 403 after connect: Recreate the token or key. Confirm Okta API scopes were granted, and that the service app has an Admin role assignment.
- Org URL refused: Use https and a host ending in okta.com, oktapreview.com, okta-emea.com, or okta-gov.com. Custom domains need allowlisting by Seven21 support.
- Needs reconnect: Open Okta settings, update credentials, and Test connection.
- Rate limited: Wait for the rate limit window to reset, then Sync now.
Signed in? Open this guide in Help Center · Contact support
