Okta (Client Credentials) - Living Security Platform

What Living Security needs

Credential	Description
Client ID	The unique identifier for your Okta API Services application
Private Key (JWK)	The RSA private key in JSON Web Key format
Okta Domain	The subdomain of your Okta organization (e.g., `dev-12345678`)
Scopes	Space-separated list of Okta Management API scopes

Scopes: okta.users.read okta.logs.read — okta.users.read backs the users sync and okta.logs.read backs the system log sync; both are required. Required role: Super Administrator in Okta (to create apps and assign admin roles)

Prerequisites

You must have Super Administrator access in Okta to create API Services applications and assign administrator roles.

Part A — In Okta

Your Okta administrator completes these steps.

Create an API Services application

Log in to your Okta Admin Console.
In the left sidebar, navigate to Applications → Applications.
Click Create App Integration.
Select API Services as the sign-in method and click Next.

Okta application creation dialog with API Services selected

Give your application a name (e.g., Living Security) and click Save.
On the application’s General tab, find your Client ID — you’ll need it in Part B.

Configure public key authentication

On the General tab, set Client authentication to Public key / Private key.

Client authentication set to Public key / Private key

Disable Proof of possession (DPoP) — it is not supported.

The application must use Public key / Private key authentication. okta.* scopes are only supported with this authentication method.

Generate and register the RSA key pair

Option A: Use Okta’s key generator (recommended)

On the General tab, scroll to the PUBLIC KEYS section.
Click Add Key, then select Generate new key.
Click Save — Okta generates the key pair and displays the Private Key (JWK) once.
Copy and save the private key JSON immediately — it will not be shown again.

The private key is sensitive credential material. Store it in a password vault or secrets manager. Do not email it — use delegated setup so the admin enters it directly into the platform.

Option B: Generate your own keyIf you prefer to generate keys yourself, use this Node.js script (requires Node.js 18+):

const { generateKeyPairSync } = require('crypto');
const { privateKey, publicKey } = generateKeyPairSync('rsa', { modulusLength: 2048 });

const privateJwk = privateKey.export({ format: 'jwk' });
const publicJwk  = publicKey.export({ format: 'jwk' });

// Assign a kid — must match between private and public JWK
const kid = require('crypto').randomUUID();
privateJwk.kid = kid;
publicJwk.kid  = kid;

console.log('=== PUBLIC JWK (upload to Okta) ===');
console.log(JSON.stringify(publicJwk, null, 2));
console.log('\n=== PRIVATE JWK (paste into the Living Security Platform) ===');
console.log(JSON.stringify(privateJwk));

Then register the public JWK in Okta:

On the General tab, scroll to the PUBLIC KEYS section.
Click Add Key, paste the public JWK JSON, and click Save.

Find your Okta Domain

Your Okta Domain is the subdomain of your Okta organization URL:

In the Admin Console, your browser shows a URL like https://dev-12345678-admin.okta.com
Your Okta Domain is the part before .okta.com, ignoring -admin (e.g., dev-12345678)
Alternatively, go to Settings → Account in the Admin Console

Grant API scopes

In the Admin Console, navigate to Applications → Applications and open your application.
Click the Okta API Scopes tab.
Grant the required scopes:
- okta.users.read
- okta.logs.read

See the Okta Management API reference for the full list of available scopes.

Assign an admin role

Granting scopes alone is not enough — Okta Management API endpoints silently return empty results if your application has no admin role. You must assign at least Read-Only Administrator:

In the Admin Console, navigate to Security → Administrators.
Click Add administrator assignment and select your API Services application.

Assign the Read-Only Administrator role.
Click Save.

Without an admin role, API calls succeed with 200 OK but return empty results — there is no 403 error to indicate the problem.

Part B — In the Living Security Platform

The program owner completes this step, or the system admin if using delegated setup.

You are now connected to Okta (Client Credentials).

Troubleshooting

Empty results (200 OK but no users returned)

The application is missing an admin role assignment. Okta Management API endpoints return empty arrays instead of errors when the application lacks permissions.Fix: Assign at least Read-Only Administrator to the application in Security → Administrators.

401 Unauthorized

The credentials are invalid. Check:

Client ID is correct
Private key matches the public key registered in Okta
Okta Domain is correct (no https://, no -admin suffix)

403 Forbidden or insufficient_scope

The application is missing required scopes. Verify that okta.users.read and okta.logs.read are granted in Applications → [Your App] → Okta API Scopes.

Invalid DPoP proof

DPoP (Demonstrating Proof of Possession) is enabled but not supported. Disable DPoP in the application’s General settings.

Portions of this documentation are adapted from Nango, used under the Elastic License 2.0.

​What Living Security needs

​Prerequisites

​Part A — In Okta

​Part B — In the Living Security Platform

​Troubleshooting

What Living Security needs

Prerequisites

Part A — In Okta

Part B — In the Living Security Platform

Troubleshooting