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": {
      }
    }
}