AI Agent Registrations

The AI Agent Registrations API provides registration and lifecycle management for AI agents. See Register an AI agent.

List all AI agents
Beta
OAuth 2.0 scopes:
  • okta.aiAgents.read
Admin roles:
  • SUPER_ADMIN

Lists all AI agents

Request
query Parameters
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 and Link header.

limit
integer [ 1 .. 200 ]
Default: 20

A limit on the number of objects to return

search
string <scim-filter>

Searches for AI agents with a filtering expression that supports:

  • eq operator for the status and appId property
  • sw, co and eq operator for the profile.name property

Note: Query parameter percent encoding is required. See Special characters.

Example: search=profile.name sw "Demo Agent" and status eq "ACTIVE" and appId eq "0oa1qmn4LZQQEH0wZ0g4"
Responses
200

OK

403

Forbidden

429

Too Many Requests

get/workload-principals/api/v1/ai-agents
Request samples 
Response samples 
application/json
{}
Register an AI agent
Beta
OAuth 2.0 scopes: 
  • okta.aiAgents.manage
Admin roles: 
  • SUPER_ADMIN
Registers an AI agent


Request 
Request Body schema: application/json
required
appId
string
The ID of the connected app for the AI agent


 
object (AIAgentProfile) 
AI agent profile


 
name
required
string
Unique name of the AI agent


 
description
string
Description of the AI agent


 
Responses 
202
Accepted


400
Bad Request


403
Forbidden


429
Too Many Requests


post/workload-principals/api/v1/ai-agents
Request samples 
application/json
{
  • "appId": "0oab1234EXAMPLEID5d6",
  • "profile": {
    • "name": "Demo Agent",
    • "description": "Demo Conversational AI Agent"
    }
}
Response samples 
application/json
{
  • "errorCode": "E0000001",
  • "errorSummary": "Api validation failed: {0}",
  • "errorLink": "E0000001",
  • "errorId": "sampleiCF-8D5rLW6myqiPItW",
  • "errorCauses": [ ]
}
Retrieve an AI agent
Beta
OAuth 2.0 scopes: 
  • okta.aiAgents.read
Admin roles: 
  • SUPER_ADMIN
Retrieves an AI agent


Request 
path Parameters
agentId
required
string
ID of the AI agent


 
 Example:  wlpcFogtKCrK9aYq3fgV
Responses 
200
OK


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


get/workload-principals/api/v1/ai-agents/{agentId}
Request samples 
Response samples 
application/json
{}
Replace an AI agent
Beta
OAuth 2.0 scopes: 
  • okta.aiAgents.manage
Admin roles: 
  • SUPER_ADMIN
Replaces an AI agent


Request 
path Parameters
agentId
required
string
ID of the AI agent


 
 Example:  wlpcFogtKCrK9aYq3fgV
Request Body schema: application/json
required
appId
string
The ID of the connected app for the AI agent


 
object (AIAgentProfile) 
AI agent profile


 
name
required
string
Unique name of the AI agent


 
description
string
Description of the AI agent


 
Responses 
202
Accepted


400
Bad Request


403
Forbidden


429
Too Many Requests


put/workload-principals/api/v1/ai-agents/{agentId}
Request samples 
application/json
{
  • "appId": "0oab1234EXAMPLEID5d6",
  • "profile": {
    • "name": "Demo Agent",
    • "description": "Demo Conversational AI Agent"
    }
}
Response samples 
application/json
{
  • "errorCode": "E0000001",
  • "errorSummary": "Api validation failed: {0}",
  • "errorLink": "E0000001",
  • "errorId": "sampleiCF-8D5rLW6myqiPItW",
  • "errorCauses": [ ]
}
Update an AI agent
Beta
OAuth 2.0 scopes: 
  • okta.aiAgents.manage
Admin roles: 
  • SUPER_ADMIN
Updates an AI agent. Use this request to perform partial updates on AI agent profile properties.


Request 
path Parameters
agentId
required
string
ID of the AI agent


 
 Example:  wlpcFogtKCrK9aYq3fgV
Request Body schema: application/merge-patch+json
required
appId
string or null
The ID of the connected app for the AI Agent


 
object (PatchAIAgentProfile) 
Partial update for AI agent profile


 
description
string or null
Description of the AI agent


 
name
string or null
Unique name of the AI agent


 
Responses 
202
Accepted


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


patch/workload-principals/api/v1/ai-agents/{agentId}
Request samples 
application/merge-patch+json
{
  • "appId": "0oab1234EXAMPLEID5d6",
  • "profile": {
    • "name": "Updated name",
    • "description": "Updated description"
    }
}
Response samples 
application/json
{
  • "errorCode": "E0000001",
  • "errorSummary": "Api validation failed: {0}",
  • "errorLink": "E0000001",
  • "errorId": "sampleiCF-8D5rLW6myqiPItW",
  • "errorCauses": [ ]
}
Delete an AI agent
Beta
OAuth 2.0 scopes: 
  • okta.aiAgents.manage
Admin roles: 
  • SUPER_ADMIN
Deletes an AI agent


Request 
path Parameters
agentId
required
string
ID of the AI agent


 
 Example:  wlpcFogtKCrK9aYq3fgV
Responses 
202
Accepted


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


delete/workload-principals/api/v1/ai-agents/{agentId}
Request samples 
Response samples 
application/json
{
  • "errorCauses": [
    • {
      }
    ],
  • "errorCode": "string",
  • "errorId": "string",
  • "errorLink": "string",
  • "errorSummary": "string"
}
Activate an AI agent
Beta
OAuth 2.0 scopes: 
  • okta.aiAgents.manage
Admin roles: 
  • SUPER_ADMIN
Activates an AI agent


Request 
path Parameters
agentId
required
string
ID of the AI agent


 
 Example:  wlpcFogtKCrK9aYq3fgV
Responses 
202
Accepted


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/workload-principals/api/v1/ai-agents/{agentId}/lifecycle/activate
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000001",
  • "errorSummary": "Api validation failed: {0}",
  • "errorLink": "E0000001",
  • "errorId": "sampleiCF-8D5rLW6myqiPItW",
  • "errorCauses": [ ]
}
Deactivate an AI agent
Beta
OAuth 2.0 scopes: 
  • okta.aiAgents.manage
Admin roles: 
  • SUPER_ADMIN
Deactivates an AI agent


Request 
path Parameters
agentId
required
string
ID of the AI agent


 
 Example:  wlpcFogtKCrK9aYq3fgV
Responses 
202
Accepted


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/workload-principals/api/v1/ai-agents/{agentId}/lifecycle/deactivate
Request samples 
Response samples 
application/json
{
  • "errorCode": "E0000001",
  • "errorSummary": "Api validation failed: {0}",
  • "errorLink": "E0000001",
  • "errorId": "sampleiCF-8D5rLW6myqiPItW",
  • "errorCauses": [ ]
}
List all AI agent operations
Beta
OAuth 2.0 scopes: 
  • okta.aiAgents.read
Permissions: 
  • okta.aiAgents.read
Lists all AI agent operations.
Operations are sorted in descending order from most recent to oldest by creation time.


Request 
query Parameters
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 and Link header.


 
limit
integer  [ 1 .. 200 ] 
 Default:  20
A limit on the number of objects to return


 
Responses 
200
OK


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


get/workload-principals/api/v1/operations
Request samples 
Response samples 
application/json
{}
Retrieve an AI agent operation
Beta
OAuth 2.0 scopes: 
  • okta.aiAgents.read
Permissions: 
  • okta.aiAgents.read
Retrieves an AI agent operation and its status


Request 
path Parameters
operationId
required
string
ID of the AI agent operation


 
 Example:  op-1a2b3c4d
Responses 
200
OK


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


get/workload-principals/api/v1/operations/{operationId}
Request samples 
Response samples 
application/json
{}