Sign in

v3

latestOpenAPI 3.0.02026-08-081996601.2 MB
Agent Identity

Update agent identity

Updates the agent's identity. You can change the role management mode, the roles, or both.

Setting mode to manual freezes the current roles. The platform no longer recomputes roles when the agent's tool configuration changes. This is useful when you need to grant the agent additional permissions beyond what its tools require.

Setting mode to auto resumes platform-managed roles. The platform immediately resyncs the roles to match the current tool configuration.

patch/v2/agents/{agent_key}/identity

Path parameters

agent_keystring required

A unique key that identifies an agent.

Example:customer_support

The unique key of the agent.

Headers

Request-Timeoutinteger

The platform makes a best effort to complete the request in the specified seconds, or it times out.

Request-Timeout-Millisinteger

The platform makes a best effort to complete the request in the specified milliseconds, or it times out.

Request body

mode'auto' | 'manual'

The role management mode of the agent's identity.

  • auto: The platform keeps roles in sync with the agent's tool configuration. When tools change, the platform recomputes roles automatically.
  • manual: The caller manages the roles. The platform does not modify roles when the agent is updated.
api_rolesApiRole[]

Customer-level roles to assign. Only applied in manual mode.

Example request

{
  "mode": "auto"
}

Response

The updated agent identity.

mode'auto' | 'manual' required

The role management mode of the agent's identity.

  • auto: The platform keeps roles in sync with the agent's tool configuration. When tools change, the platform recomputes roles automatically.
  • manual: The caller manages the roles. The platform does not modify roles when the agent is updated.
client_idstring required

The OAuth2 client ID of the agent's service account.

api_rolesApiRole[] required

Customer-level roles assigned to this identity.

Example response

{
  "mode": "auto",
  "client_id": "abc123def456"
}