AI Agent Connections

The AI Agent Connections API provides connection management between agents and resources. See Secure an AI agent.

List all agent connections
Beta
OAuth 2.0 scopes:
  • okta.aiAgents.read
Admin roles:
  • SUPER_ADMIN

Lists all connections for the agent

Request
path Parameters
agentId
required
string

ID of the agent

Example: wlpkhjm0jnDp8RrUu0g4
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

A list of connections for the agent

403

Forbidden

404

Not Found

429

Too Many Requests

get/workload-principals/api/v1/ai-agents/{agentId}/connections
Request samples 
Response samples 
application/json
{}
Create a managed connection
Beta
OAuth 2.0 scopes: 
  • okta.aiAgents.manage
Admin roles: 
  • SUPER_ADMIN
Creates a managed connection for the agent


Request 
path Parameters
agentId
required
string
ID of the agent


 
 Example:  wlpkhjm0jnDp8RrUu0g4
Request Body schema: application/json
required
connectionType
required
string
Type of connection authentication method


 
required
object
Reference to a custom authorization server and its configuration


 
orn
required
string (AuthorizationServerOrn) 
The ORN of the authorization server


 
scopeCondition
required
string (ScopeCondition) 
Determines how Okta evaluates requested scopes for the connection.


 Enum: "ALL_SCOPES" "EXCLUDE" "INCLUDE_ONLY"  
scopes
required
Array of strings (ConnectionScopes)   non-empty 
Array of scopes. Required for all scopeCondition values. For ALL_SCOPES, this array is required with a single value of *. For INCLUDE_ONLY, only these scopes are allowed. For EXCLUDE, all scopes except these are allowed.


 
resourceIndicator
string <uri> 
Resource indicator used when requesting tokens. Defaults to the authorization server's ORN if not specified.


 
Responses 
201
A successful connection created response


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/workload-principals/api/v1/ai-agents/{agentId}/connections
Request samples 
application/json
{
  • "connectionType": "IDENTITY_ASSERTION_CUSTOM_AS",
  • "resourceIndicator": "https://api.crm.company.com",
  • "authorizationServer": {
    • "orn": "orn:okta:idp:00o5rb5mt2H3d1TJd0h7:authorization_servers:aus5rb5mt2H3d1TJd0h7"
    },
  • "scopeCondition": "EXCLUDE",
  • "scopes": [
    • "crm.admin.delete",
    • "crm.admin.write"
    ]
}
Response samples 
application/json
{}
Retrieve an agent connection
Beta
OAuth 2.0 scopes: 
  • okta.aiAgents.read
Admin roles: 
  • SUPER_ADMIN
Retrieves a connection for the agent


Request 
path Parameters
agentId
required
string
ID of the agent


 
 Example:  wlpkhjm0jnDp8RrUu0g4
connectionId
required
string
ID of the connection


 
 Example:  mcn1a2b3c4d5e6f7g8h9
Responses 
200
Successful get a connection response


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


get/workload-principals/api/v1/ai-agents/{agentId}/connections/{connectionId}
Request samples 
Response samples 
application/json
When a managed connection enables a workload principal to obtain an ID-JAG for a custom authorization server


{}
Update a managed connection
Beta
OAuth 2.0 scopes: 
  • okta.aiAgents.manage
Admin roles: 
  • SUPER_ADMIN
Updates a managed connection for the agent


Request 
path Parameters
agentId
required
string
ID of the agent


 
 Example:  wlpkhjm0jnDp8RrUu0g4
connectionId
required
string
ID of the connection


 
 Example:  mcn1a2b3c4d5e6f7g8h9
Request Body schema: application/json
required
resourceIndicator
string or null <uri>  (ManagedConnectionPatchableResourceIndicator) 
Resource indicator used when requesting tokens. Set to null to reset to the default value based on the connection type (app instance ORN, authorization server ORN, secret ORN, or service account ORN).


 
scopeCondition
string or null (ManagedConnectionPatchableScopeCondition) 
Determines how Okta evaluates requested scopes for the connection.


Restrictions:


    

  • Only valid for IDENTITY_ASSERTION_CUSTOM_AS connection types
    • 

  • Must be provided together with scopes
    • 

  • Returns a 400 error if sent for STS_VAULT_SECRET or STS_SERVICE_ACCOUNT connection types
    • 



 Enum: "ALL_SCOPES" "EXCLUDE" "INCLUDE_ONLY"  
scopes
Array of strings or null (ManagedConnectionPatchableScopes)   non-empty 
Array of scopes for the connection. For ALL_SCOPES, this array must contain a single value of *. For INCLUDE_ONLY, only these scopes are allowed. For EXCLUDE, all scopes except these are allowed.


Restrictions:


    

  • Only valid for IDENTITY_ASSERTION_CUSTOM_AS connection types
    • 

  • Must be provided together with scopeCondition
    • 

  • Returns a 400 error if sent for STS_VAULT_SECRET or STS_SERVICE_ACCOUNT connection types
    • 



 
Responses 
200
A successful connection update response


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


patch/workload-principals/api/v1/ai-agents/{agentId}/connections/{connectionId}
Request samples 
application/json
Update scopeCondition and scopes for an Identity Assertion connection. Only valid for IDENTITY_ASSERTION_APP_INSTANCE and IDENTITY_ASSERTION_CUSTOM_AS types.


{
  • "scopeCondition": "INCLUDE_ONLY",
  • "scopes": [
    • "crm.contacts.read",
    • "crm.accounts.write",
    • "crm.reports.read"
    ]
}
Response samples 
application/json
{}
Delete an agent connection
Beta
OAuth 2.0 scopes: 
  • okta.aiAgents.manage
Admin roles: 
  • SUPER_ADMIN
Deletes a managed connection for the agent


Request 
path Parameters
agentId
required
string
ID of the agent


 
 Example:  wlpkhjm0jnDp8RrUu0g4
connectionId
required
string
ID of the connection


 
 Example:  mcn1a2b3c4d5e6f7g8h9
Responses 
204
Connection deleted


403
Forbidden


404
Not Found


429
Too Many Requests


delete/workload-principals/api/v1/ai-agents/{agentId}/connections/{connectionId}
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 a managed connection
Beta
OAuth 2.0 scopes: 
  • okta.aiAgents.manage
Admin roles: 
  • SUPER_ADMIN
Activates a managed connection for the agent


Request 
path Parameters
agentId
required
string
ID of the agent


 
 Example:  wlpkhjm0jnDp8RrUu0g4
connectionId
required
string
ID of the connection


 
 Example:  mcn1a2b3c4d5e6f7g8h9
Responses 
200
A successful connection activate response


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/workload-principals/api/v1/ai-agents/{agentId}/connections/{connectionId}/lifecycle/activate
Request samples 
Response samples 
application/json
{}
Deactivate a managed connection
Beta
OAuth 2.0 scopes: 
  • okta.aiAgents.manage
Admin roles: 
  • SUPER_ADMIN
Deactivates a managed connection for the agent


Request 
path Parameters
agentId
required
string
ID of the agent


 
 Example:  wlpkhjm0jnDp8RrUu0g4
connectionId
required
string
ID of the connection


 
 Example:  mcn1a2b3c4d5e6f7g8h9
Responses 
200
A successful managed connection deactivate response


400
Bad Request


403
Forbidden


404
Not Found


429
Too Many Requests


post/workload-principals/api/v1/ai-agents/{agentId}/connections/{connectionId}/lifecycle/deactivate
Request samples 
Response samples 
application/json
{}