Directory Agent Pools

The Agent Pools API provides operations to manage the update settings of the directory agents for your org.

List all agent pools
OAuth 2.0:
  • okta.agentPools.read

Lists all agent pools with pagination support

Request
query Parameters
limitPerPoolType
integer
Default: 5

Maximum number of agent pools returned

poolType
string (AgentType)

Agent type to search for

Enum: "AD" "IWA" "LDAP" "MFA" "OPP" "RUM" "Radius"
after
string

The cursor to use for pagination. It is an opaque string that specifies your current location in the list and is obtained from the Link response header. See Pagination.

Responses
200

OK

403

Forbidden

429

Too Many Requests

get/api/v1/agentPools
Request samples
Response samples
application/json
[
  • {
    • "disruptedAgents": 0,
    • "inactiveAgents": 1,
    • "operationalStatus": "OPERATIONAL",
    • "id": "poolId1",
    • "name": "region1A.dc",
    • "type": "AD",
    • "agents": {
      },
    • "_links": {
      }
    }
]

List all agent pool updates
OAuth 2.0:
  • okta.agentPools.read

Lists all agent pool updates

Request
path Parameters
poolId
required
string

ID of the agent pool for which the settings apply to

query Parameters
scheduled
boolean

Return only scheduled or ad-hoc updates. If this parameter isn't provided, Okta returns the entire list of updates.

Responses
200

OK

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/agentPools/{poolId}/updates
Request samples
Response samples
application/json
[
  • {
    • "id": "poolId1",
    • "name": "testSchedule",
    • "agentType": "AD",
    • "agents": {
      },
    • "enabled": true,
    • "schedule": {
      },
    • "notifyAdmin": true,
    • "status": "Scheduled",
    • "targetVersion": "3.20.0",
    • "_links": {
      }
    }
]

Create an agent pool update
OAuth 2.0:
  • okta.agentPools.manage

Creates an agent pool update

Request
path Parameters
poolId
required
string

ID of the agent pool for which the settings apply to

Request Body schema: application/json
required
Array of objects (Agent)
Array
isHidden
boolean

Determines if an agent is hidden from the Admin Console

isLatestGAedVersion
boolean

Determines if the agent is on the latest generally available version

lastConnection
string <date-time>

Timestamp when the agent last connected to Okta

name
string

Agent name

operationalStatus
string (OperationalStatus)

Operational status of a given agent

Enum: "DEGRADED" "DISRUPTED" "INACTIVE" "OPERATIONAL"
poolId
string

Pool ID

type
string (AgentType)

Agent types that are being monitored

Enum: "AD" "IWA" "LDAP" "MFA" "OPP" "RUM" "Radius"
updateMessage
string

Status message of the agent

updateStatus
string (AgentUpdateInstanceStatus)

Status for one agent regarding the status to auto-update that agent

Enum: "Cancelled" "Failed" "InProgress" "PendingCompletion" "Scheduled" "Success"
version
string

Agent version number

agentType
string (AgentType)

Agent types that are being monitored

Enum: "AD" "IWA" "LDAP" "MFA" "OPP" "RUM" "Radius"
enabled
boolean

Indicates if auto-update is enabled for the agent pool

name
string

Name of the agent pool update

notifyAdmin
boolean

Indicates if the admin is notified about the update

reason
string

Reason for the update

object (AutoUpdateSchedule)

The schedule of auto-update configured by the admin

cron
string

The schedule of the update in cron format. The cron settings are limited to only the day of the month or the nth-day-of-the-week configurations. For example, 0 8 ? * 6#3 indicates every third Saturday at 8:00 AM.

delay
integer

Delay in days

duration
integer

Duration in minutes

lastUpdated
string <date-time>

Timestamp when the update finished (only for a successful or failed update, not for a cancelled update). Null is returned if the job hasn't finished once yet.

timezone
string

Timezone of where the scheduled job takes place

sortOrder
integer

Specifies the sort order

status
string (AgentUpdateJobStatus)

Overall state for the auto-update job from the admin perspective

Enum: "Cancelled" "Failed" "InProgress" "Paused" "Scheduled" "Success"
targetVersion
string

The agent version to update to

Responses
201

Created

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/agentPools/{poolId}/updates
Request samples
application/json
{
  • "agents": [
    • {
      }
    ],
  • "agentType": "AD",
  • "enabled": true,
  • "name": "region1A.dc",
  • "notifyAdmin": true,
  • "reason": "Update failed.",
  • "schedule": {
    • "cron": "0 8 ? * 6#3",
    • "delay": 0,
    • "duration": 120,
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "timezone": "America/New_York"
    },
  • "sortOrder": 0,
  • "status": "Cancelled",
  • "targetVersion": "3.20.0"
}
Response samples
application/json
{
  • "agents": [
    • {
      }
    ],
  • "agentType": "AD",
  • "enabled": true,
  • "id": "string",
  • "name": "region1A.dc",
  • "notifyAdmin": true,
  • "reason": "Update failed.",
  • "schedule": {
    • "cron": "0 8 ? * 6#3",
    • "delay": 0,
    • "duration": 120,
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "timezone": "America/New_York"
    },
  • "sortOrder": 0,
  • "status": "Cancelled",
  • "targetVersion": "3.20.0",
  • "_links": {
    • "self": {
      }
    }
}

Retrieve an agent pool update's settings
OAuth 2.0:
  • okta.agentPools.read

Retrieves the current state of the agent pool update instance settings

Request
path Parameters
poolId
required
string

ID of the agent pool for which the settings apply to

Responses
200

OK

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/agentPools/{poolId}/updates/settings
Request samples
Response samples
application/json
{
  • "agentType": "AD",
  • "continueOnError": true,
  • "latestVersion": "3.20.0",
  • "minimalSupportedVersion": "3.19.0",
  • "poolId": "0oa3eu7ekG8tjbD9J5s6",
  • "poolName": "iwa.dc",
  • "releaseChannel": "BETA"
}

Update an agent pool update settings
OAuth 2.0:
  • okta.agentPools.manage

Updates an agent pool update instance settings

Request
path Parameters
poolId
required
string

ID of the agent pool for which the settings apply to

Request Body schema: application/json
required
agentType
string (AgentType)

Agent types that are being monitored

Enum: "AD" "IWA" "LDAP" "MFA" "OPP" "RUM" "Radius"
continueOnError
boolean

Continues the update even if some agents fail to update

latestVersion
string

Latest version of the agent

minimalSupportedVersion
string

Minimal version of the agent

poolName
string

Pool name

releaseChannel
string (ReleaseChannel)

Release channel for auto-update

Enum: "BETA" "EA" "GA" "TEST"
Responses
201

Updated

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/agentPools/{poolId}/updates/settings
Request samples
application/json
{
  • "agentType": "AD",
  • "continueOnError": true,
  • "latestVersion": "3.20.0",
  • "minimalSupportedVersion": "3.19.0",
  • "poolName": "iwa.dc",
  • "releaseChannel": "BETA"
}
Response samples
application/json
{
  • "agentType": "AD",
  • "continueOnError": true,
  • "latestVersion": "3.20.0",
  • "minimalSupportedVersion": "3.19.0",
  • "poolId": "0oa3eu7ekG8tjbD9J5s6",
  • "poolName": "iwa.dc",
  • "releaseChannel": "BETA"
}

Retrieve an agent pool update by ID
OAuth 2.0:
  • okta.agentPools.read

Retrieves an agent pool update by its updateId

Request
path Parameters
poolId
required
string

ID of the agent pool for which the settings apply to

updateId
required
string

ID of the update

Responses
200

OK

403

Forbidden

404

Not Found

429

Too Many Requests

get/api/v1/agentPools/{poolId}/updates/{updateId}
Request samples
Response samples
application/json
{
  • "agents": [
    • {
      }
    ],
  • "agentType": "AD",
  • "enabled": true,
  • "id": "string",
  • "name": "region1A.dc",
  • "notifyAdmin": true,
  • "reason": "Update failed.",
  • "schedule": {
    • "cron": "0 8 ? * 6#3",
    • "delay": 0,
    • "duration": 120,
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "timezone": "America/New_York"
    },
  • "sortOrder": 0,
  • "status": "Cancelled",
  • "targetVersion": "3.20.0",
  • "_links": {
    • "self": {
      }
    }
}

Update an agent pool update by ID
OAuth 2.0:
  • okta.agentPools.manage

Updates an agent pool update instance and returns the latest agent pool update

Request
path Parameters
poolId
required
string

ID of the agent pool for which the settings apply to

updateId
required
string

ID of the update

Request Body schema: application/json
required
Array of objects (Agent)
Array
isHidden
boolean

Determines if an agent is hidden from the Admin Console

isLatestGAedVersion
boolean

Determines if the agent is on the latest generally available version

lastConnection
string <date-time>

Timestamp when the agent last connected to Okta

name
string

Agent name

operationalStatus
string (OperationalStatus)

Operational status of a given agent

Enum: "DEGRADED" "DISRUPTED" "INACTIVE" "OPERATIONAL"
poolId
string

Pool ID

type
string (AgentType)

Agent types that are being monitored

Enum: "AD" "IWA" "LDAP" "MFA" "OPP" "RUM" "Radius"
updateMessage
string

Status message of the agent

updateStatus
string (AgentUpdateInstanceStatus)

Status for one agent regarding the status to auto-update that agent

Enum: "Cancelled" "Failed" "InProgress" "PendingCompletion" "Scheduled" "Success"
version
string

Agent version number

agentType
string (AgentType)

Agent types that are being monitored

Enum: "AD" "IWA" "LDAP" "MFA" "OPP" "RUM" "Radius"
enabled
boolean

Indicates if auto-update is enabled for the agent pool

name
string

Name of the agent pool update

notifyAdmin
boolean

Indicates if the admin is notified about the update

reason
string

Reason for the update

object (AutoUpdateSchedule)

The schedule of auto-update configured by the admin

cron
string

The schedule of the update in cron format. The cron settings are limited to only the day of the month or the nth-day-of-the-week configurations. For example, 0 8 ? * 6#3 indicates every third Saturday at 8:00 AM.

delay
integer

Delay in days

duration
integer

Duration in minutes

lastUpdated
string <date-time>

Timestamp when the update finished (only for a successful or failed update, not for a cancelled update). Null is returned if the job hasn't finished once yet.

timezone
string

Timezone of where the scheduled job takes place

sortOrder
integer

Specifies the sort order

status
string (AgentUpdateJobStatus)

Overall state for the auto-update job from the admin perspective

Enum: "Cancelled" "Failed" "InProgress" "Paused" "Scheduled" "Success"
targetVersion
string

The agent version to update to

Responses
201

Updated

400

Bad Request

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/agentPools/{poolId}/updates/{updateId}
Request samples
application/json
{
  • "agents": [
    • {
      }
    ],
  • "agentType": "AD",
  • "enabled": true,
  • "name": "region1A.dc",
  • "notifyAdmin": true,
  • "reason": "Update failed.",
  • "schedule": {
    • "cron": "0 8 ? * 6#3",
    • "delay": 0,
    • "duration": 120,
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "timezone": "America/New_York"
    },
  • "sortOrder": 0,
  • "status": "Cancelled",
  • "targetVersion": "3.20.0"
}
Response samples
application/json
{
  • "agents": [
    • {
      }
    ],
  • "agentType": "AD",
  • "enabled": true,
  • "id": "string",
  • "name": "region1A.dc",
  • "notifyAdmin": true,
  • "reason": "Update failed.",
  • "schedule": {
    • "cron": "0 8 ? * 6#3",
    • "delay": 0,
    • "duration": 120,
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "timezone": "America/New_York"
    },
  • "sortOrder": 0,
  • "status": "Cancelled",
  • "targetVersion": "3.20.0",
  • "_links": {
    • "self": {
      }
    }
}

Delete an agent pool update
OAuth 2.0:
  • okta.agentPools.manage

Deletes agent pool update

Request
path Parameters
poolId
required
string

ID of the agent pool for which the settings apply to

updateId
required
string

ID of the update

Responses
204

Deleted

403

Forbidden

404

Not Found

429

Too Many Requests

delete/api/v1/agentPools/{poolId}/updates/{updateId}
Request samples
Response samples
application/json
{
  • "errorCode": "E0000006",
  • "errorSummary": "You do not have permission to perform the requested action",
  • "errorLink": "E0000006",
  • "errorId": "sampleNUSD_8fdkFd8fs8SDBK",
  • "errorCauses": [ ]
}

Activate an agent pool update
OAuth 2.0:
  • okta.agentPools.manage

Activates a scheduled agent pool update

Request
path Parameters
poolId
required
string

ID of the agent pool for which the settings apply to

updateId
required
string

ID of the update

Responses
201

Activated

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/agentPools/{poolId}/updates/{updateId}/activate
Request samples
Response samples
application/json
{
  • "agents": [
    • {
      }
    ],
  • "agentType": "AD",
  • "enabled": true,
  • "id": "string",
  • "name": "region1A.dc",
  • "notifyAdmin": true,
  • "reason": "Update failed.",
  • "schedule": {
    • "cron": "0 8 ? * 6#3",
    • "delay": 0,
    • "duration": 120,
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "timezone": "America/New_York"
    },
  • "sortOrder": 0,
  • "status": "Cancelled",
  • "targetVersion": "3.20.0",
  • "_links": {
    • "self": {
      }
    }
}

Deactivate an agent pool update
OAuth 2.0:
  • okta.agentPools.manage

Deactivates scheduled agent pool update

Request
path Parameters
poolId
required
string

ID of the agent pool for which the settings apply to

updateId
required
string

ID of the update

Responses
201

Deactivated

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/agentPools/{poolId}/updates/{updateId}/deactivate
Request samples
Response samples
application/json
{
  • "agents": [
    • {
      }
    ],
  • "agentType": "AD",
  • "enabled": true,
  • "id": "string",
  • "name": "region1A.dc",
  • "notifyAdmin": true,
  • "reason": "Update failed.",
  • "schedule": {
    • "cron": "0 8 ? * 6#3",
    • "delay": 0,
    • "duration": 120,
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "timezone": "America/New_York"
    },
  • "sortOrder": 0,
  • "status": "Cancelled",
  • "targetVersion": "3.20.0",
  • "_links": {
    • "self": {
      }
    }
}

Pause an agent pool update
OAuth 2.0:
  • okta.agentPools.manage

Pauses a running or queued agent pool update

Request
path Parameters
poolId
required
string

ID of the agent pool for which the settings apply to

updateId
required
string

ID of the update

Responses
201

Paused

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/agentPools/{poolId}/updates/{updateId}/pause
Request samples
Response samples
application/json
{
  • "agents": [
    • {
      }
    ],
  • "agentType": "AD",
  • "enabled": true,
  • "id": "string",
  • "name": "region1A.dc",
  • "notifyAdmin": true,
  • "reason": "Update failed.",
  • "schedule": {
    • "cron": "0 8 ? * 6#3",
    • "delay": 0,
    • "duration": 120,
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "timezone": "America/New_York"
    },
  • "sortOrder": 0,
  • "status": "Cancelled",
  • "targetVersion": "3.20.0",
  • "_links": {
    • "self": {
      }
    }
}

Resume an agent pool update
OAuth 2.0:
  • okta.agentPools.manage

Resumes a running or queued agent pool update

Request
path Parameters
poolId
required
string

ID of the agent pool for which the settings apply to

updateId
required
string

ID of the update

Responses
201

Resumed

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/agentPools/{poolId}/updates/{updateId}/resume
Request samples
Response samples
application/json
{
  • "agents": [
    • {
      }
    ],
  • "agentType": "AD",
  • "enabled": true,
  • "id": "string",
  • "name": "region1A.dc",
  • "notifyAdmin": true,
  • "reason": "Update failed.",
  • "schedule": {
    • "cron": "0 8 ? * 6#3",
    • "delay": 0,
    • "duration": 120,
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "timezone": "America/New_York"
    },
  • "sortOrder": 0,
  • "status": "Cancelled",
  • "targetVersion": "3.20.0",
  • "_links": {
    • "self": {
      }
    }
}

Retry an agent pool update
OAuth 2.0:
  • okta.agentPools.manage

Retries an agent pool update if the update is unsuccessful or communication with Okta was interrupted during an agent auto-update

Request
path Parameters
poolId
required
string

ID of the agent pool for which the settings apply to

updateId
required
string

ID of the update

Responses
201

Retried

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/agentPools/{poolId}/updates/{updateId}/retry
Request samples
Response samples
application/json
{
  • "agents": [
    • {
      }
    ],
  • "agentType": "AD",
  • "enabled": true,
  • "id": "string",
  • "name": "region1A.dc",
  • "notifyAdmin": true,
  • "reason": "Update failed.",
  • "schedule": {
    • "cron": "0 8 ? * 6#3",
    • "delay": 0,
    • "duration": 120,
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "timezone": "America/New_York"
    },
  • "sortOrder": 0,
  • "status": "Cancelled",
  • "targetVersion": "3.20.0",
  • "_links": {
    • "self": {
      }
    }
}

Stop an agent pool update
OAuth 2.0:
  • okta.agentPools.manage

Stops an agent pool update

Request
path Parameters
poolId
required
string

ID of the agent pool for which the settings apply to

updateId
required
string

ID of the update

Responses
201

Stopped

403

Forbidden

404

Not Found

429

Too Many Requests

post/api/v1/agentPools/{poolId}/updates/{updateId}/stop
Request samples
Response samples
application/json
{
  • "agents": [
    • {
      }
    ],
  • "agentType": "AD",
  • "enabled": true,
  • "id": "string",
  • "name": "region1A.dc",
  • "notifyAdmin": true,
  • "reason": "Update failed.",
  • "schedule": {
    • "cron": "0 8 ? * 6#3",
    • "delay": 0,
    • "duration": 120,
    • "lastUpdated": "2019-08-24T14:15:22Z",
    • "timezone": "America/New_York"
    },
  • "sortOrder": 0,
  • "status": "Cancelled",
  • "targetVersion": "3.20.0",
  • "_links": {
    • "self": {
      }
    }
}