Okta SDK Node.js

https://github.com/okta/okta-sdk-nodejs
Admin
Node.js SDK for the Okta management API to create users, manage groups, applications, and more...
Tokens:1,137,742
Snippets:4,885
Trust Score:9.4
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Client constructor example

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/api-reference/client.md

Example of constructing a Client with no configuration, which throws an Error listing all validation failures.

```javascript
new okta.Client({})
```

--------------------------------

### Install @okta/okta-sdk-nodejs via npm

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/README.md

Install the Okta Node.js SDK using npm. Requires Node.js version 14.0.0 or higher.

```sh
npm install @okta/okta-sdk-nodejs
```

--------------------------------

### Search Users with q, search, and filter Parameters

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/docs/JSDOC.md

Searches for users using the Users: List Users API with three query parameter approaches: q, search, and filter. The library URL-encodes the values automatically. Each example iterates over the results with each() and logs matching users.

```javascript
await (await client.userApi.listUsers({
  q: 'Robert'
})).each(user => {
  console.log('User matches query: ', user);
});

await (await client.userApi.listUsers({
  search: 'profile.nickName eq "abc 1234"'
})).each(user => {
  console.log('User matches search:', user);
});

await (await client.userApi.listUsers({
  filter: 'lastUpdated gt "2017-06-05T23:00:00.000Z"'
})).each(user => {
  console.log('User matches filter:', user);
});
```

--------------------------------

### Use API objects for SDK 7.x.x

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/README.md

For SDK 7.x.x, API methods are called from corresponding API objects of `client` (e.g., `client.applicationApi`). Params are passed as a single object. This example shows creating and getting an application.

```typescript
const application: BookmarkApplication = {
  name: 'bookmark',
  label: 'Bookmark app',
  signOnMode: 'BOOKMARK',
  settings: {
    app: {
      requestIntegration: false,
      url: 'https://example.com/bookmark.htm'
    }
  }
};
const createdApplication: BookmarkApplication = await client.applicationApi.createApplication({
  application
});

const oidcApp: OpenIdConnectApplication = await client.applicationApi.getApplication({ appId });
```

--------------------------------

### Create a Group with client.groupApi.createGroup()

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/docs/JSDOC.md

Creates a group using the Groups: Add Group API. The newGroup object contains a profile with a name. The promise resolves with the created group object. Note: the example passes the group as {grpup: newGroup} (typo in the source).

```javascript
const newGroup = {
  profile: {
    name: 'Admin Users Group'
  }
};

client.groupApi.createGroup({grpup: newGroup})
.then(group => {
  console.log('Created group', group);
});
```

--------------------------------

### Paginate over all users with listUsers

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/api-reference/user-api.md

Iterates over all users using an async iterator from listUsers. The example sets a limit of 100 and a search filter for emails starting with 'foo'.

```javascript
const collection = await client.userApi.listUsers({ limit: 100, search: 'profile.email sw "foo"' });
for await (const user of collection) {
  console.log(user.id, user.profile.email, user.status);
}
```

--------------------------------

### Simple Subscription Example

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/README.md

Subscribes to a collection to poll for new items at a configurable interval. Call unsubscribe() to stop polling.

```javascript
const subscription = collection.subscribe({
  interval: 5000,
  next(item) {
    console.log(item);
  },
  error(err) {
    // handle error
  }
});

// In the future, unsubscribe when you want to stop polling:
subscription.unsubscribe()
```

--------------------------------

### Get a User by ID or Login with client.userApi.getUser()

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/docs/JSDOC.md

Fetches a user by id or by login (profile.login property) using the Users: Get User API. The userId parameter accepts either the user's ID or their login string. Each call returns a promise that resolves with the user object.

```javascript
client.userApi.getUser({ userId: 'ausmvdt5xg8wRVI1d0g3' }).then(user => {
  console.log(user);
});

client.userApi.getUser({ userId: 'foo@bar.com' }).then(user => {
  console.log(user);
});
```

--------------------------------

### Direct usage of MemoryStore with error handling

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/api-reference/memory-store.md

Demonstrates direct usage: set with ttl, get returns 'value', delete removes key, get returns undefined. Setting with empty key throws synchronously with message 'MemoryStore.set requires a defined key'.

```javascript
const store = new okta.MemoryStore({ keyLimit: 10 });
await store.set('cache-key', 'value', { ttl: 60000 });
console.log(await store.get('cache-key')); // 'value'
await store.delete('cache-key');
console.log(await store.get('cache-key')); // undefined

try {
  await store.set('', 'value');
} catch (err) {
  console.error(err.message); // MemoryStore.set requires a defined key
}
```

--------------------------------

### Update a User with client.userApi.updateUser()

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/docs/JSDOC.md

Modifies a user instance and persists changes using the Users: Update User API. The example changes the profile.nickName property and passes the user object along with the user's id. The promise resolves when the update is saved.

```javascript
user.profile.nickName = 'rob';
client.userApi.updateUser({ userId: user.id, user }).then(() => console.log('User nickname change has been saved'));
```

--------------------------------

### Basic usage example

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/api-reference/oauth.md

Shows how to instantiate the client with PrivateKey authorization mode and use client.oauth.getAccessToken() and clearCachedAccessToken().

```javascript
const okta = require('@okta/okta-sdk-nodejs');
const client = new okta.Client({
  orgUrl: 'https://dev-1234.okta.com',
  authorizationMode: 'PrivateKey',
  clientId: '0oa...',
  scopes: ['okta.users.manage'],
  privateKey: '{...JWK...}'
});

// Normally you don't touch client.oauth directly — Http.prepareRequest does:
const token = await client.oauth.getAccessToken();
console.log(token.access_token, token.token_type, token.expires_in, token.scope);

// Force a token refresh:
client.oauth.clearCachedAccessToken();
const freshToken = await client.oauth.getAccessToken();
```

--------------------------------

### Get a User by ID or Login with client.userApi.getUser

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/README.md

Fetches a user by their ID or login (profile.login) using the Users: Get User API. The userId parameter accepts either the user's ID or login string.

```javascript
let user;
user = await client.userApi.getUser({ userId: 'ausmvdt5xg8wRVI1d0g3' });
console.log(user);

user = await client.userApi.getUser({ userId: 'foo@bar.com' });
console.log(user);
```

--------------------------------

### GET /api/v1/apps

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Lists all applications. This endpoint is part of the ApplicationApi.

```APIDOC
## [GET] /api/v1/apps

### Description
Lists all applications.

### Method
GET

### Endpoint
/api/v1/apps

### Response
#### Success Response (200)
- Returns a collection of applications.

#### Response Example
[
  {
    "id": "0oa1abcde2FGHIJKLMNOP",
    "name": "My App"
  }
]
```

--------------------------------

### Error handling example

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/api-reference/oauth.md

Shows how to catch OktaApiError when calling getAccessToken() and log the error code and summary.

```javascript
try {
  const token = await client.oauth.getAccessToken();
} catch (err) {
  if (err.name === 'OktaApiError') {
    console.error('Token endpoint error', err.errorCode, err.errorSummary);
  }
}
```

--------------------------------

### Environment variable configuration

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/docs/JSDOC.md

Environment variables for Okta client configuration. Configuration names are flattened and delimited with underscores, e.g., OKTA_CLIENT_ORGURL and OKTA_CLIENT_TOKEN.

```sh
OKTA_CLIENT_ORGURL=https://dev-1234.oktapreview.com/
OKTA_CLIENT_TOKEN=xYzabc
```

--------------------------------

### Get a Session with client.sessionApi.getSession

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/README.md

Retrieves session details using the session ID. The details include authentication time and session expiration.

```javascript
session = await client.sessionApi.getSession({
  sessionId: session.id
});
console.log('Session details:', session);
```

--------------------------------

### Create application with type for SDK 5.1.0

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/README.md

Shows how to create a bookmark application in SDK 5.1.0 using `client.createApplication` with an `ApplicationOptions` object. The method returns a typed `BookmarkApplication`.

```typescript
const applicationOptions: ApplicationOptions = {
  name: 'bookmark',
  label: 'Bookmark app',
  signOnMode: 'BOOKMARK',
  settings: {
    app: {
      requestIntegration: false,
      url: 'https://example.com/bookmark.htm'
    }
  }
};
const application: BookmarkApplication = client.createApplication(applicationOptions);
```

--------------------------------

### ConfigLoader usage example

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/api-reference/config-loader.md

Shows how to instantiate ConfigLoader, apply defaults, and override configuration. Demonstrates that authorizationMode defaults to 'SSWS' unless overridden. Comments show direct calls to applyYamlFile and applyEnvVars.

```javascript
// ~/.okta/okta.yaml holds orgUrl + token; constructor merges it
const loader = new ConfigLoader();
loader.applyDefaults();

console.log(loader.config.client.authorizationMode); // 'SSWS' (default, unless overridden)

// explicit overrides (as the Client constructor does):
loader.apply({ client: { orgUrl: 'https://dev-1234.okta.com' } });

// applyYamlFile / applyEnvVars are called internally; you can still call them directly:
// loader.applyYamlFile('/path/to/okta.yaml');
// loader.applyEnvVars();
```

--------------------------------

### Generate a DPoP proof

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/api-reference/jwt.md

Example usage of generateDpopJwt with a GET request, an access token, and no nonce. The function returns a compact JWS string.

```javascript
const { generateDpopJwt } = require('@okta/okta-sdk-nodejs/src/dpop');
const proof = await generateDpopJwt(
  { method: 'GET', url: 'https://dev-1234.okta.com/api/v1/users' },
  client,
  'access-token-value',
  null
);
```

--------------------------------

### Create a Basic Authentication Application with client.applicationApi.createApplication

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/README.md

Creates an Okta application of type 'template_basic_auth' with BASIC_AUTH sign-on mode. The created application object is logged.

```javascript
const application = {
  name: 'template_basic_auth',
  label: 'Sample Basic Auth App',
  signOnMode: 'BASIC_AUTH',
  settings: {
    app: {
      url: 'https://example.com/auth.htm',
      authURL: 'https://example.com/login.html'
    }
  }
};

const createdApplication = await client.applicationApi.createApplication({ application });
console.log('Created application:', createdApplication);
```

--------------------------------

### constructor(config)

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/api-reference/client.md

Creates a new Client instance, the entry point of the Okta SDK. It validates the merged configuration and throws an Error listing all validation failures if any required settings are missing.

```APIDOC
## constructor(config)

### Description
Creates a new Client instance, the entry point of the Okta SDK. It validates the merged configuration and throws an Error listing all validation failures if any required settings are missing.

### Method
constructor

### Signature
```typescript
constructor(config?: V2Configuration);
```

### Parameters
- **config** (V2Configuration, object) - Optional - Client options. See configuration.md for details.

### Configuration Fields
- **orgUrl** (string) - Optional - Okta organization URL.
- **token** (string) - Optional - SSWS API token.
- **clientId** (string) - Optional - OAuth 2.0 client ID.
- **scopes** (string[]) - Optional - OAuth 2.0 scopes.
- **requestExecutor** (RequestExecutor) - Optional - Custom request executor.
- **authorizationMode** (string) - Optional - 'SSWS' or 'PrivateKey'.
- **privateKey** (string | Record<string, unknown>) - Optional - JWK string, JSON object, or PEM.
- **keyId** (string) - Optional - Key ID.
- **cacheStore** (CacheStorage) - Optional - Cache storage.
- **cacheMiddleware** (typeof defaultCacheMiddleware | unknown) - Optional - Pass null to disable.
- **defaultCacheMiddlewareResponseBufferSize** (number) - Optional - Response buffer size.
- **userAgent** (string) - Optional - User agent string.
- **httpsProxy** (string) - Optional - HTTPS proxy.

### Validation Errors
Throws an Error with a message listing all validation failures. The message ends with 'See https://github.com/okta/okta-sdk-nodejs for usage.'

| Condition | Error text |
|-----------|------------|
| `orgUrl` missing | `Okta Org URL not provided` |
| `token` missing AND `authorizationMode !== 'PrivateKey'` | `Okta API token not provided` |
| `authorizationMode === 'PrivateKey'` and no `clientId` | `Okta Client ID not provided` |
| `authorizationMode === 'PrivateKey'` and no `scopes` | `Scopes not provided` |
| `authorizationMode === 'PrivateKey'` and no `privateKey` | `Private Key not provided` |
| `authorizationMode` is not `'SSWS'` or `'PrivateKey'` | `Unknown Authorization Mode` |

### Example
```js
new okta.Client({})
```
Throws: `Error: Found 2 errors:\nOkta Org URL not provided\nOkta API token not provided\nSee https://github.com/okta/okta-sdk-nodejs for usage.`
```

--------------------------------

### Config via ~/.okta/okta.yaml

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/api-reference/client.md

Define client configuration in a YAML file. The client constructor reads configuration from ~/.okta/okta.yaml, ./okta.yaml, and OKTA_* environment variables.

```yaml
okta:
  client:
    orgUrl: 'https://dev-1234.okta.com'
    token: 'xYzabc'
```

```javascript
const client = new okta.Client(); // reads ~/.okta/okta.yaml, ./okta.yaml, then OKTA_* env vars
```

--------------------------------

### Create Okta Client with API Token

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/README.md

Initialize the Okta client with your Okta Domain and API token. The client handles authentication and communication with the Okta API.

```javascript
const okta = require('@okta/okta-sdk-nodejs');

const client = new okta.Client({
  orgUrl: 'https://dev-1234.oktapreview.com/',
  token: 'xYzabc'    // Obtained from Developer Dashboard
});
```

--------------------------------

### Create a User with client.userApi.createUser()

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/docs/JSDOC.md

Creates a basic user with email and password using the Users: Create User API. The newUser object includes profile and credentials properties; the password value must meet Okta's password requirements. The promise resolves with the created user object.

```javascript
const newUser = {
  profile: {
    firstName: 'Foo',
    lastName: 'Bar',
    email: 'foo@example.com',
    login: 'foo@example.com',
  },
  credentials: {
    password : {
      value: 'PasswordAbc123'
    }
  }
};

client.userApi.createUser({ body: newUser })
.then(user => {
  console.log('Created user', user);
});
```

--------------------------------

### YAML configuration structure with okta top-level key

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/configuration.md

Defines the required YAML structure for client configuration. Must have an `okta` top-level key because `applyYamlFile` loads `yaml.load(file).okta`. Supports `orgUrl`, `token`, `authorizationMode`, and optional `clientId`, `scopes`, `privateKey`, and `keyId` for PrivateKey mode. `userAgent` also merges through YAML but has no corresponding `OKTA_CLIENT_USERAGENT` env var.

```yaml
okta:
  client:
    orgUrl: 'https://dev-1234.okta.com'
    token: 'xYzabc'
    authorizationMode: 'SSWS'
    # for PrivateKey mode:
    # clientId: '0oa...'
    # scopes: 'okta.users.manage okta.users.read'
    # privateKey: '{"kty":"RSA",...}'
    # keyId: 'kidValue'
```

--------------------------------

### TypeScript usage for SDK 4.5.x - create application with request body

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/README.md

Shows how to provide request body parameters when creating an application in SDK 4.5.x. Imports `Application` and `ApplicationOptions` from specific paths and uses `client.createApplication` with a bookmark app configuration.

```typescript
import { Application, ApplicationOptions } from '@okta/okta-sdk-nodejs/src/types/models/Application';
import { Client } from '@okta/okta-sdk-nodejs'
import { LogEvent } from '@okta/okta-sdk-nodejs/src/types/models/LogEvent';
const client = new Client({
  orgUrl:'https://dev-org.okta.com',
  token: 'apiToken',
});
const bookmarkAppOptions: ApplicationOptions = {
  "name": "bookmark",
  "label": "Sample Bookmark App",
  "signOnMode": "BOOKMARK",
  "settings": {
    "app": {
      "requestIntegration": false,
      "url": "https://example.com/bookmark.htm"
    }
  }
};
client.createApplication(bookmarkAppOptions).then((createdApp: Application) => {
  console.log(createdApp);
});
```

--------------------------------

### createUser

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/api-reference/user-api.md

Creates a new user. Optionally activates the user, sets the provider, and specifies the next login action.

```APIDOC
## [POST] /api/v1/users

### Description
Creates a new user. Optionally activates the user, sets the provider, and specifies the next login action.

### Method
POST

### Endpoint
/api/v1/users

### Parameters
#### Query Parameters
- **activate** (boolean) - Optional - Whether to activate the user immediately.
- **provider** (boolean) - Optional - Whether the user is a provider.
- **nextLogin** (UserNextLogin) - Optional - The next login action.

#### Request Body
- **body** (CreateUserRequest) - Required - The user creation request object.

### Request Example
{
  "body": {
    "profile": {
      "firstName": "string",
      "lastName": "string",
      "email": "string",
      "login": "string"
    }
  }
}

### Response
#### Success Response (200)
- **User** (object) - The created user.

#### Response Example
{
  "id": "string",
  "status": "ACTIVE",
  "profile": {
    "firstName": "string",
    "lastName": "string",
    "email": "string",
    "login": "string"
  }
}
```

--------------------------------

### GET /api/v1/realms

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Lists all realms. This endpoint is part of the RealmApi.

```APIDOC
## GET /api/v1/realms

### Description
Lists all realms.

### Method
GET

### Endpoint
/api/v1/realms

```

--------------------------------

### Create client with base RequestExecutor

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/README.md

Instantiates a client using the base RequestExecutor, which delegates requests to isomorphic-fetch and emits 'request' and 'response' events. This executor has no configuration and is used by default if none is provided. In the next major version, you must explicitly pass it to opt out of the default executor.

```javascript
const client = new okta.Client({
  orgUrl: 'https://dev-1234.oktapreview.com/',
  token: 'xYzabc',    // Obtained from Developer Dashboard
  requestExecutor: new okta.RequestExecutor()
});
```

--------------------------------

### GET /api/v1/logs

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Retrieves system logs. This endpoint is part of the SystemLogApi.

```APIDOC
## GET /api/v1/logs

### Description
Retrieves system logs.

### Method
GET

### Endpoint
/api/v1/logs

```

--------------------------------

### GET /api/v1/mappings

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Lists all profile mappings. This endpoint is part of the ProfileMappingApi.

```APIDOC
## GET /api/v1/mappings

### Description
Lists all profile mappings.

### Method
GET

### Endpoint
/api/v1/mappings

```

--------------------------------

### GET /api/v1/device-integrations

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Lists all device integrations. This endpoint is part of the DeviceIntegrationsApi.

```APIDOC
## GET /api/v1/device-integrations

### Description
Lists all device integrations.

### Method
GET

### Endpoint
/api/v1/device-integrations

```

--------------------------------

### Create a User with client.userApi.createUser

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/README.md

Creates a basic user with profile and password credentials using the Users: Create User API. The newUser object defines profile fields and a password value; the method returns the created user object.

```javascript
const newUser = {
  profile: {
    firstName: 'Foo',
    lastName: 'Bar',
    email: 'foo@example.com',
    login: 'foo@example.com'
  },
  credentials: {
    password: {
      value: 'PasswordAbc123'
    }
  }
};
const user = await client.userApi.createUser({ body: newUser });
console.log('Created user', user);
```

--------------------------------

### GET /api/v1/risk/providers

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Lists all risk providers. This endpoint is part of the RiskProviderApi.

```APIDOC
## GET /api/v1/risk/providers

### Description
Lists all risk providers.

### Method
GET

### Endpoint
/api/v1/risk/providers

```

--------------------------------

### GET /api/v1/push-providers

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Lists all push providers. This endpoint is part of the PushProviderApi.

```APIDOC
## GET /api/v1/push-providers

### Description
Lists all push providers.

### Method
GET

### Endpoint
/api/v1/push-providers

```

--------------------------------

### Configure MemoryStore with keyLimit and expirationPoll

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/README.md

Creates an Okta client with a custom MemoryStore cache. Set expirationPoll to true to periodically scan the entire store and remove expired keys, preventing unbounded growth. keyLimit defaults to 100000 and deletes oldest keys when exceeded.

```javascript
const okta = require('@okta/okta-sdk-nodejs');
const MemoryStore = okta.MemoryStore;

const client = new okta.Client({
  orgUrl: 'https://dev-1234.oktapreview.com/',
  token: 'xYzabc', // Obtained from Developer Dashboard
  cacheStore: new MemoryStore({
    keyLimit: 100000,
    expirationPoll: true
  })
});

```

--------------------------------

### Search for Users with q, search, and filter

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/README.md

Demonstrates three search methods for the Users: List Users API: q, search, and filter. Each query is passed as a parameter to listUsers; the library URL-encodes values automatically.

```javascript
let collection;
collection = await client.userApi.listUsers({
  q: 'Robert'
});
await collection.each(user => {
  console.log('User matches query: ', user);
});


collection = await client.userApi.listUsers({
  search: 'profile.nickName eq "abc 1234"'
});
await collection.each(user => {
  console.log('User matches query: ', user);
});

collection = await client.userApi.listUsers({
  filter: 'lastUpdated gt "2017-06-05T23:00:00.000Z"'
});
await collection.each(user => {
  console.log('User matches query: ', user);
});
```

--------------------------------

### GET /api/v1/idps

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Lists all Identity Providers. This endpoint is part of the IdentityProviderApi.

```APIDOC
## GET /api/v1/idps

### Description
Lists all Identity Providers.

### Method
GET

### Endpoint
/api/v1/idps

```

--------------------------------

### Environment variables only client configuration

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/configuration.md

Creates an Okta client with no inline configuration; all settings are read from environment variables (OKTA_CLIENT_ORGURL, OKTA_CLIENT_TOKEN). Use when you want to keep credentials and configuration out of source code.

```javascript
// 3) Env vars only
// OKTA_CLIENT_ORGURL=https://dev-1234.okta.com
// OKTA_CLIENT_TOKEN=xYzabc
const client = new okta.Client(); // config comes from the environment
```

--------------------------------

### okta.yaml client configuration

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/README.md

YAML structure for configuring the Okta client via an okta.yaml file. The file is searched in ~/.okta and the current working directory, with properties matching the client constructor options.

```yaml
okta:
  client:
    orgUrl: 'https://dev-1234.oktapreview.com/'
    token: 'xYzabc'

```

--------------------------------

### GET /api/v1/operations/{operationId}

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Retrieves an operation by its ID. This endpoint is part of the OperationsIntegrationApi.

```APIDOC
## GET /api/v1/operations/{operationId}

### Description
Retrieves an operation by its ID.

### Method
GET

### Endpoint
/api/v1/operations/{operationId}

### Parameters
#### Path Parameters
- **operationId** (string) - Required - The ID of the operation.

```

--------------------------------

### List All Org Users with client.userApi.listUsers() and each()

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/docs/JSDOC.md

Fetches a collection of all users using the Users: List Users API. The each() method iterates through the collection, logging each user. The promise resolves after all users have been listed.

```javascript
const orgUsersCollection = client.userApi.listUsers();

orgUsersCollection.each(user => {
  console.log(user);
})
.then(() => console.log('All users have been listed'));
```

--------------------------------

### GET /api/v1/threats/configuration

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Retrieves threat insight configuration. This endpoint is part of the ThreatInsightApi.

```APIDOC
## GET /api/v1/threats/configuration

### Description
Retrieves threat insight configuration.

### Method
GET

### Endpoint
/api/v1/threats/configuration

```

--------------------------------

### GET /api/v1/principal-rate-limits

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Lists all principal rate limits. This endpoint is part of the PrincipalRateLimitApi.

```APIDOC
## GET /api/v1/principal-rate-limits

### Description
Lists all principal rate limits.

### Method
GET

### Endpoint
/api/v1/principal-rate-limits

```

--------------------------------

### List All Org Users with each()

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/README.md

Fetches a collection of all users using the Users: List Users API and iterates with the each() method. The callback logs each user; after iteration, a completion message is printed.

```javascript
const collection = await client.userApi.listUsers();
await collection.each(user => {
  console.log(user);
});
console.log('All users have been listed');
```

--------------------------------

### GET /api/v1/meta/schemas/user/linkedObjects

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Lists all linked object definitions. This endpoint is part of the LinkedObjectApi.

```APIDOC
## GET /api/v1/meta/schemas/user/linkedObjects

### Description
Lists all linked object definitions.

### Method
GET

### Endpoint
/api/v1/meta/schemas/user/linkedObjects

```

--------------------------------

### TypeScript usage for SDK 4.5.x - fetch logs

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/README.md

Shows how to use the SDK with TypeScript in version 4.5.x. Imports `Client` and `LogEvent` from specific paths and uses `client.getLogs` to iterate over log events. The `each` method processes entries and collects actor display names.

```typescript
import { Client } from '@okta/okta-sdk-nodejs'
import { LogEvent } from '@okta/okta-sdk-nodejs/src/types/models/LogEvent';
const client = new Client({
  orgUrl:'https://dev-org.okta.com',
  token: 'apiToken',
});
const logEvents = client.getLogs({
  since: '2021-03-11'
});
const actors: Set<string> = new Set();
logEvents.each((entry: LogEvent) => {
  actors.add(entry.actor.displayName);
}).then(() => {
  // res.send(JSON.stringify([...actors], null, 4));
};)
```

--------------------------------

### GET /api/v1/dr/status

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Retrieves disaster recovery status. This endpoint is part of the DisasterRecoveryApi.

```APIDOC
## GET /api/v1/dr/status

### Description
Retrieves disaster recovery status.

### Method
GET

### Endpoint
/api/v1/dr/status

```

--------------------------------

### Client wiring with createConfiguration

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/api-reference/generated-configuration.md

JavaScript example from src/client.js lines 91-95 showing how the Client wires createConfiguration with a baseServer and httpApi. All generated APIs share one Configuration whose httpApi is the hand-written Http, which supplies SSWS/OAuth/DPoP auth, caching, and retries.

```javascript
const configuration = createConfiguration({
  baseServer: new ServerConfiguration(parsedConfig.client.orgUrl),
  httpApi: this.http,
});
```

--------------------------------

### GET /api/v1/realms/{realmId}

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Retrieves a realm by its ID. This endpoint is part of the RealmApi.

```APIDOC
## GET /api/v1/realms/{realmId}

### Description
Retrieves a realm by its ID.

### Method
GET

### Endpoint
/api/v1/realms/{realmId}

### Parameters
#### Path Parameters
- **realmId** (string) - Required - The ID of the realm.

```

--------------------------------

### All-inline client configuration with requestExecutor, cacheMiddleware, httpsProxy, userAgent

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/configuration.md

Configures an Okta client entirely inline with orgUrl, token, a custom DefaultRequestExecutor (maxRetries, requestTimeout), disabled caching via cacheMiddleware: null, an HTTPS proxy, and a custom userAgent. Use when you need full control over all client options in code.

```javascript
// 1) All inline
const client = new okta.Client({
  orgUrl: 'https://dev-1234.okta.com',
  token: 'xYzabc',
  requestExecutor: new okta.DefaultRequestExecutor({ maxRetries: 2, requestTimeout: 30000 }),
  cacheMiddleware: null,                       // disable caching
  httpsProxy: 'http://user:pass@proxy.corp:8080',
  userAgent: 'my-service/1.0'
});
```

--------------------------------

### GET /privileged-access/api/v1/okta-service-accounts

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Lists all Okta service accounts. This endpoint is part of the OktaManagedUserAccountApi.

```APIDOC
## GET /privileged-access/api/v1/okta-service-accounts

### Description
Lists all Okta service accounts.

### Method
GET

### Endpoint
/privileged-access/api/v1/okta-service-accounts

```

--------------------------------

### Create, fetch, and update a user with userApi

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/api-reference/user-api.md

Shows the full lifecycle of creating a user with a password and profile, fetching it by ID, and updating its profile. Requires an Okta client configured with orgUrl and token. The createUser call uses activate: true to activate the user immediately.

```javascript
const okta = require('@okta/okta-sdk-nodejs');
const client = new okta.Client({ orgUrl, token });

const newUser = await client.userApi.createUser({
  body: {
    profile: {
      firstName: 'Foo', lastName: 'Bar',
      email: 'foo@example.com', login: 'foo@example.com'
    },
    credentials: { password: { value: 'PasswordAbc123' } }
  },
  activate: true
});
console.log(newUser.id); // '00u...'

const fetched = await client.userApi.getUser({ userId: newUser.id });
const updated = await client.userApi.updateUser({
  userId: fetched.id,
  user: { profile: { ...fetched.profile, department: 'Engineering' } }
});
```

--------------------------------

### GET /workload-principals/api/v1/potential-connections

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Retrieves potential connections for workload principals. This endpoint is part of the AgentPotentialConnectionsApi.

```APIDOC
## GET /workload-principals/api/v1/potential-connections

### Description
Retrieves potential connections for workload principals.

### Method
GET

### Endpoint
/workload-principals/api/v1/potential-connections

```

--------------------------------

### GET /api/v1/mappings/{mappingId}

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Retrieves a profile mapping by its ID. This endpoint is part of the ProfileMappingApi.

```APIDOC
## GET /api/v1/mappings/{mappingId}

### Description
Retrieves a profile mapping by its ID.

### Method
GET

### Endpoint
/api/v1/mappings/{mappingId}

### Parameters
#### Path Parameters
- **mappingId** (string) - Required - The ID of the profile mapping.

```

--------------------------------

### applyYamlFile method signature

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/api-reference/config-loader.md

Declares the applyYamlFile method. Takes a path to a YAML file and applies its 'okta' top-level key.

```typescript
applyYamlFile(path: string): void;
```

--------------------------------

### GET /api/v1/device-integrations/{deviceIntegrationId}

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Retrieves a device integration by its ID. This endpoint is part of the DeviceIntegrationsApi.

```APIDOC
## GET /api/v1/device-integrations/{deviceIntegrationId}

### Description
Retrieves a device integration by its ID.

### Method
GET

### Endpoint
/api/v1/device-integrations/{deviceIntegrationId}

### Parameters
#### Path Parameters
- **deviceIntegrationId** (string) - Required - The ID of the device integration.

```

--------------------------------

### Create a Group with client.groupApi.createGroup

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/README.md

Creates a new Okta group with a profile containing a name. The group object is returned and logged.

```javascript
const newGroup = {
  profile: {
    name: 'Admin Users Group'
  }
};

const group = await client.groupApi.createGroup({ group: newGroup });
console.log('Created group', group);
```

--------------------------------

### GET /attack-protection/api/v1/authenticator-settings

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Retrieves authenticator settings for attack protection. This endpoint is part of the AttackProtectionApi.

```APIDOC
## GET /attack-protection/api/v1/authenticator-settings

### Description
Retrieves authenticator settings for attack protection.

### Method
GET

### Endpoint
/attack-protection/api/v1/authenticator-settings

```

--------------------------------

### JSON convenience methods (getJson, postJson)

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/api-reference/http.md

Use client.http.getJson() and client.http.postJson() for JSON responses and requests. The postJson example creates a group with a profile name.

```javascript
const user = await client.http.getJson(`${client.baseUrl}/api/v1/users/me`);
const created = await client.http.postJson(`${client.baseUrl}/api/v1/groups`, {
  body: { profile: { name: 'Engineers' } }
});
```

--------------------------------

### GET /api/v1/risk/providers/{riskProviderId}

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Retrieves a risk provider by its ID. This endpoint is part of the RiskProviderApi.

```APIDOC
## GET /api/v1/risk/providers/{riskProviderId}

### Description
Retrieves a risk provider by its ID.

### Method
GET

### Endpoint
/api/v1/risk/providers/{riskProviderId}

### Parameters
#### Path Parameters
- **riskProviderId** (string) - Required - The ID of the risk provider.

```

--------------------------------

### GET /api/v1/push-providers/{pushProviderId}

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Retrieves a push provider by its ID. This endpoint is part of the PushProviderApi.

```APIDOC
## GET /api/v1/push-providers/{pushProviderId}

### Description
Retrieves a push provider by its ID.

### Method
GET

### Endpoint
/api/v1/push-providers/{pushProviderId}

### Parameters
#### Path Parameters
- **pushProviderId** (string) - Required - The ID of the push provider.

```

--------------------------------

### Using generated APIs directly with createConfiguration (without Client)

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/api-reference/generated-configuration.md

Creates a configuration with a base server and API token authentication, then instantiates UserApi and calls getUser. Requires @okta/okta-sdk-nodejs and a valid SSWS token.

```javascript
const okta = require('@okta/okta-sdk-nodejs');
const { createConfiguration, ServerConfiguration, HttpMethodEnum } = okta;

const configuration = createConfiguration({
  baseServer: new ServerConfiguration('https://dev-1234.okta.com'),
  authMethods: {
    apiToken: 'xYzabc' // SSWS token
  }
});

const userApi = new okta.UserApi(configuration);
const user = await userApi.getUser({ userId: '00u123' });
```

--------------------------------

### GET /api/v1/idps/credentials/keys

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Lists all signing keys for Identity Providers. This endpoint is part of the IdentityProviderApi.

```APIDOC
## GET /api/v1/idps/credentials/keys

### Description
Lists all signing keys for Identity Providers.

### Method
GET

### Endpoint
/api/v1/idps/credentials/keys

```

--------------------------------

### GET /api/v1/apps/{appId}/grants

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Lists all grants for an application. This endpoint is part of the ApplicationApi.

```APIDOC
## [GET] /api/v1/apps/{appId}/grants

### Description
Lists all grants for an application.

### Method
GET

### Endpoint
/api/v1/apps/{appId}/grants

### Parameters
#### Path Parameters
- **appId** (string) - Required - The ID of the application.

### Response
#### Success Response (200)
- Returns a collection of grants.

#### Response Example
[
  {
    "id": "grant1",
    "status": "ACTIVE"
  }
]
```

--------------------------------

### new ServerConfiguration(url, variableConfiguration?)

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/api-reference/generated-configuration.md

Creates a new ServerConfiguration instance with the given base URL and optional variable configuration. The variable configuration replaces {var} placeholders in the URL.

```APIDOC
## Constructor

### Description
Creates a new ServerConfiguration instance with the given base URL and optional variable configuration. The variable configuration replaces `{var}` placeholders in the URL.

### Signature
`constructor(url: string, variableConfiguration?: { [key: string]: unknown })`

### Parameters
- **url** (string) - Required - The org base URL.
- **variableConfiguration** (object) - Optional - Variables to replace `{var}` placeholders in the URL.

### Example
```typescript
const config = new ServerConfiguration('https://{yourOktaDomain}', { 'yourOktaDomain': 'subdomain.okta.com' });
```
```

--------------------------------

### getUrl()

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/api-reference/generated-configuration.md

Returns the base URL with variables substituted.

```APIDOC
## Method: getUrl

### Description
Returns the base URL with variables substituted.

### Signature
`getUrl(): string`

### Returns
- **string** - The base URL with `{variables}` substituted.
```

--------------------------------

### GET /api/v1/apps/{appId}/tokens

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Lists all tokens for an application. This endpoint is part of the ApplicationApi.

```APIDOC
## [GET] /api/v1/apps/{appId}/tokens

### Description
Lists all tokens for an application.

### Method
GET

### Endpoint
/api/v1/apps/{appId}/tokens

### Parameters
#### Path Parameters
- **appId** (string) - Required - The ID of the application.

### Response
#### Success Response (200)
- Returns a collection of tokens.

#### Response Example
[
  {
    "id": "token1",
    "status": "ACTIVE"
  }
]
```

--------------------------------

### listUsers

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/api-reference/user-api.md

Lists users with optional filters, search, and pagination.

```APIDOC
## [GET] /api/v1/users

### Description
Lists users with optional filters, search, and pagination.

### Method
GET

### Endpoint
/api/v1/users

### Parameters
#### Query Parameters
- **contentType** (string) - Optional - The content type.
- **search** (string) - Optional - Search query.
- **filter** (string) - Optional - Filter expression.
- **q** (string) - Optional - Query string.
- **after** (string) - Optional - Pagination cursor.
- **limit** (number) - Optional - Maximum number of items to return.
- **sortBy** (string) - Optional - Sort field.
- **sortOrder** (string) - Optional - Sort order (asc/desc).
- **fields** (string) - Optional - Fields to return.
- **expand** (string) - Optional - Additional fields to expand.

### Response
#### Success Response (200)
- **Collection<User>** (collection) - List of users.

#### Response Example
[
  {
    "id": "string",
    "status": "ACTIVE",
    "profile": {
      "firstName": "string",
      "lastName": "string",
      "email": "string",
      "login": "string"
    }
  }
]
```

--------------------------------

### GET /api/v1/apps/{appId}/features

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Lists all features for an application. This endpoint is part of the ApplicationApi.

```APIDOC
## [GET] /api/v1/apps/{appId}/features

### Description
Lists all features for an application.

### Method
GET

### Endpoint
/api/v1/apps/{appId}/features

### Parameters
#### Path Parameters
- **appId** (string) - Required - The ID of the application.

### Response
#### Success Response (200)
- Returns a collection of features.

#### Response Example
[
  {
    "name": "FEATURE",
    "status": "ENABLED"
  }
]
```

--------------------------------

### each()

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/docs/JSDOC.md

Iterates over every item in a collection returned by an Okta SDK API call. Supports synchronous and asynchronous work, and allows early termination by returning false or rejecting a promise.

```APIDOC
## each()

### Description
Iterates over every item in the collection, optionally performing work at each item. Returns a promise that resolves when all items have been visited, or rejects if an iterator returns a rejected promise.

### Method
`each()`

### Parameters
- **iterator** (function) - Required - A function that receives each item in the collection. Can return a promise for asynchronous work, `false` to stop iteration, or nothing to continue.

### Return Value
Returns a Promise that resolves when all items have been visited, or rejects if the iterator returns a rejected promise.

### Usage Examples

#### Serial or Parallel Synchronous Work
```javascript
(await client.userApi.listUsers()).each(user => {
  console.log(user);
  logUserToRemoteSystem(user);
}).then(() => {
  console.log('All users have been vistied');
});
```

#### Serial Asynchronous Work
```javascript
(await client.userApi.listUsers()).each(user => {
  return new Promise((resolve, reject) => {
    // do work, then resolve or reject the promise
  })
});
```

#### Ending Iteration by Returning false
```javascript
(await client.userApi.listUsers()).each(user => {
  console.log(user);
  return false;
}).then(() => {
  console.log('Only one user was visited');
});
```

#### Ending Iteration by Returning false in a Promise
```javascript
(await client.userApi.listUsers()).each((user) => {
  console.log(user);
  return Promise.resolve(false);
}).then(() => {
  console.log('Only one user was visited');
});
```

#### Ending Iteration with an Error
```javascript
return (await client.userApi.listUsers()).each((user) => {
  console.log(user);
  return Promise.reject('foo error');
}).catch((err)=>{
  console.log(err); // 'foo error'
});
```
```

--------------------------------

### GET /api/v1/apps/{appId}/credentials/csrs

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Lists all CSRs for an application. This endpoint is part of the ApplicationApi.

```APIDOC
## [GET] /api/v1/apps/{appId}/credentials/csrs

### Description
Lists all CSRs for an application.

### Method
GET

### Endpoint
/api/v1/apps/{appId}/credentials/csrs

### Parameters
#### Path Parameters
- **appId** (string) - Required - The ID of the application.

### Response
#### Success Response (200)
- Returns a collection of CSRs.

#### Response Example
[
  {
    "id": "csr1",
    "status": "PENDING"
  }
]
```

--------------------------------

### ServerConfiguration

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/api-reference/generated-configuration.md

Represents a server configuration with a base URL and methods to get affected resources.

```APIDOC
## ServerConfiguration

### Description
Represents a server configuration with a base URL and methods to get affected resources.

### Constructor
- `constructor(url: string)` - Creates an instance with the base URL.

### Methods
- `getAffectedResources(path: string, params: object): string[]` - Returns an array of URLs that match the given path and parameters.
```

--------------------------------

### applyDefaults method signature

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/api-reference/config-loader.md

Declares the applyDefaults method. Applies built-in defaults, then global and local YAML files, then environment variables.

```typescript
applyDefaults(): void;
```

--------------------------------

### GET /api/v1/apps/{appId}/unconfirmed-users

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/_autodocs/endpoints.md

Retrieves unconfirmed users for an app. This endpoint is part of the UnconfirmedUsersApi.

```APIDOC
## GET /api/v1/apps/{appId}/unconfirmed-users

### Description
Retrieves unconfirmed users for an app.

### Method
GET

### Endpoint
/api/v1/apps/{appId}/unconfirmed-users

### Parameters
#### Path Parameters
- **appId** (string) - Required - The ID of the app.

```

--------------------------------

### Create a Session with client.sessionApi.createSession

Source: https://github.com/okta/okta-sdk-nodejs/blob/master/README.md

Creates a session using a session token. This method is rarely used; see the linked documentation for common session creation methods.

```javascript
const session = await client.sessionApi.createSession({
  createSessionRequest: {
    sessionToken: 'your session token'
  }
});
console.log('Session details:', session);
```
Tokens:
Raw