Connect Okta

Agent markdown

Before you start

Okta uses customer client credentials (oauth2_client_credentials + customer_credentials). There is no Init platform OAuth app for this provider.

Connection admin/user creates an Okta API service app, grants Management API scopes, and submits the org domain, client ID, and complete RSA private JWK through Init Connect. Engine operator does not store a shared Okta client secret.

You need:

• An Okta org Super Admin (or equivalent) who can create API service apps and assign admin roles/scopes.
• The org hostname only (for example example.okta.com), not the -admin console host and not a custom domain.
• Access to Init Connect for the tenant that will own the connection.

Configure the provider

Create an Okta API service app (Connection admin/user)

1. In the Okta Admin Console, create an API Services OAuth app (service app) for machine-to-machine access.
2. Configure client authentication as public key / private key (private_key_jwt). Client secret auth is not accepted for Okta Management API scopes.
3. Generate an RSA key pair. Register the public JWK on the service app. Keep the complete private JWK offline in a secret manager.
4. Grant only the Okta API scopes required for the Init actions you will run (for example okta.users.read, okta.groups.read, okta.apps.read, plus manage variants when writes are required). Prefer least privilege.
5. Assign any Okta admin roles the service app needs so those scopes can actually call Management API endpoints.
6. Copy the Client ID (20 alphanumeric characters). Note the org domain hostname without scheme or path.

There is no one-time Init platform Okta app registration.

Connect to Init

Connection admin/user starts an Okta Connect session and submits only these contract fields:

The private JWK must be a strict RSA signing key with all of these members: kty (RSA), kid, alg (RS256), use (sig), n, e, d, p, q, dp, dq, and qi. Do not paste a real JWK into tickets or docs. Never embed JWT client assertions in documentation.

Permissions

Service-app grants control which Okta Management API scopes Init can mint. Match grants to the generated action scope matrix; do not enable unused admin scopes.

Okta also requires appropriate admin roles on the service app so granted scopes succeed at runtime. Scope grants without roles still fail with authorization errors.

Verify the connection

1. Complete Connect and confirm the connection is active.
2. Run Init’s connection test or a safe read such as listing users or groups the service app can access.
3. Success looks like Okta returning Management API data without 401 invalid-client or scope errors.

Rotate or revoke access

1. Generate a new RSA key pair. Register the new public JWK on the Okta service app.
2. Reconnect in Init with the same org_domain / client_id and the new complete private JWK.
3. Remove the old public key from the Okta app after cutover.
4. To revoke access entirely, deactivate or delete the service app in Okta and delete the Init connection.

If a private JWK is exposed, rotate keys immediately in Okta, then reconnect.

Troubleshooting