Supplementary information for AI agent identities

Key capabilities and benefits

The following table summarizes the key capabilities and benefits of securing your AI-driven solutions using AI agent identities:

Capabilities	Benefits
Specialized agent identity: Treats AI agents as distinct entities with unique identities and privileges, rather than using simple impersonation.	Granular security and least privilege: Eliminates "over-privileged" accounts by applying tailored security policies specific to autonomous entities.
Streamlined onboarding & lifecycle: Manual onboarding using OAuth 2.0 grant flow or automated onboarding via Dynamic Client Registration (DCR), with centralized lifecycle management.	Operational efficiency: Reduces administrative overhead and "agent sprawl" while ensuring agents can be instantly revoked or rotated.
Advanced access and token delegation: Sophisticated token exchange mechanisms to manage "on-behalf-of" permissions and resource scoping.	Reduced complexity: Simplifies the "who, what, and how" of agent access using low-code tools, ensuring secure delegation without custom-coded security logic.
Dedicated agent observability: Isolated logging and monitoring that separates agent telemetry from end users and static applications.	Clear auditability: Provides an auditable trail of AI activity, making it easy to prove compliance and understand exactly when an AI agent acted autonomously.

Capabilities

Benefits

Specialized agent identity: Treats AI agents as distinct entities with unique identities and privileges, rather than using simple impersonation.

Granular security and least privilege: Eliminates "over-privileged" accounts by applying tailored security policies specific to autonomous entities.

Streamlined onboarding & lifecycle: Manual onboarding using OAuth 2.0 grant flow or automated onboarding via Dynamic Client Registration (DCR), with centralized lifecycle management.

Operational efficiency: Reduces administrative overhead and "agent sprawl" while ensuring agents can be instantly revoked or rotated.

Advanced access and token delegation: Sophisticated token exchange mechanisms to manage "on-behalf-of" permissions and resource scoping.

Reduced complexity: Simplifies the "who, what, and how" of agent access using low-code tools, ensuring secure delegation without custom-coded security logic.

Dedicated agent observability: Isolated logging and monitoring that separates agent telemetry from end users and static applications.

Clear auditability: Provides an auditable trail of AI activity, making it easy to prove compliance and understand exactly when an AI agent acted autonomously.

AI agent identity managed object types

The following table summarizes the managed object types related to AI agent identities:

Managed object type	Description
AI agent	This is distinct from the user managed object type. It provides unique AI agent identities and allows for clear accountability and distinct audit trails for their activities, with Advanced Identity Cloud acting as the dedicated Identity Provider (IdP).
AI agent privilege	This lets AI agent identities have delegated privileges, ensuring that they can only access specific applications, act for specific end users or groups of end users, and use specific OAuth 2.0 scopes.

Managed object type

Description

AI agent

This is distinct from the user managed object type. It provides unique AI agent identities and allows for clear accountability and distinct audit trails for their activities, with Advanced Identity Cloud acting as the dedicated Identity Provider (IdP).

AI agent privilege

This lets AI agent identities have delegated privileges, ensuring that they can only access specific applications, act for specific end users or groups of end users, and use specific OAuth 2.0 scopes.

Object model

The AI agent identity object model spans two systems: access management (system of record) and identity management (privileges store). When you create an AI agent identity in access management, Advanced Identity Cloud automatically creates a linked identity management <realm>_aiagent object and records its UUID in the aiAgentIdentityUid field on the access management OAuth 2.0 client.

Object type System Purpose

Object type	System	Purpose
OAuth 2.0 client (AI agent identity)	Access management	The agent’s OAuth 2.0 identity; defines grant types, scopes, and authentication method. Deleting this object cascades to all linked identity management objects.
`alpha_aiagent`	Identity management	Created automatically when an access management AI agent identity is created. Stores the agent’s identity management UUID, which is referenced by privilege objects.
`alpha_aiagentprivilege`	Identity management	Links the AI agent identity to a specific application (`<realm>_application`), a set of permitted users (`<realm>_user`), and a scope allowlist. Multiple privilege records can exist for a single identity (one per application).

OAuth 2.0 client (AI agent identity)

Access management

The agent’s OAuth 2.0 identity; defines grant types, scopes, and authentication method. Deleting this object cascades to all linked identity management objects.

alpha_aiagent

Identity management

Created automatically when an access management AI agent identity is created. Stores the agent’s identity management UUID, which is referenced by privilege objects.

alpha_aiagentprivilege

Identity management

Links the AI agent identity to a specific application (<realm>_application), a set of permitted users (<realm>_user), and a scope allowlist. Multiple privilege records can exist for a single identity (one per application).

Cascade behavior

Access management is the system of record for the entire AI identity object graph. Deleting an AI agent identity using the access management endpoint cascades immediately to:

Delete the linked identity management <realm>_aiagent object.
Delete all <realm>_aiagentprivilege records that reference the agent.

Application and user objects are independent and aren’t affected.

Key consequences:

Single-step deletion: Associated privileges are removed automatically without needing manual cleanup, preventing orphaned records.
Non-recoverable: Recreating an identity with the same client ID generates a new identity management UUID. Previous privileges are permanently lost and must be reconfigured.

Privilege evaluation

At token-exchange time, Advanced Identity Cloud evaluates the privileges of an AI agent identity in the following order:

Audience check: The token exchange request includes an audience parameter containing the application’s OAuth 2.0 client ID. Advanced Identity Cloud matches this against privileges where resource.ssoEntities.oidcId equals the audience value.
Permission check: The requested scopes must be a subset of the scopes in the privilege’s permissions.values list. If values is empty, any scope permitted by both the AI agent identity and the application is allowed.
Subject check: For on-behalf-of flows, the subject token’s user identity must appear in the privilege’s subjects list. For autonomous flows, the subjects list must be empty (or the privilege must have no subject restriction).
Scope check: The final granted scopes are the intersection of: the scopes in the privilege, the scopes on the application, and the scopes on the AI agent identity.

Privilege changes take effect after the privilege cache expires (10 seconds by default). A privilege you create or update may not be applied immediately in the next token exchange.

API error reference

Common error responses when managing AI agent identities via the REST API:

HTTP status Condition Resolution

HTTP status	Condition	Resolution
`400 Bad Request`	Missing required field in privilege request body (for example, no `resource` or no `agent` reference)	Ensure both `agent._ref` and `resource._ref` are present in the request body.
`401 Unauthorized`	Access token is missing, expired, or has insufficient scope	Obtain a new service account access token with the required scopes (`fr:am:` for agent operations; `fr:idm:` for privilege operations).
`404 Not Found`	AI agent identity or privilege does not exist at the specified path	Verify the agent client ID or privilege UUID in the URL. Use the list endpoint to confirm the object exists.
`412 Precondition Failed`	`If-None-Match: *` was specified for create-only semantics, but an AI agent identity with this client ID already exists.	The AI agent identity already exists. Omit `If-None-Match: *` to allow an upsert, or use a different OAuth 2.0 client ID.
`422 Unprocessable Entity`	A privilege reference points to an identity management object that doesn’t exist (for example, an invalid AI agent identity UUID or application UUID)	Verify the UUIDs in `agent._ref`, `resource._ref`, and `subjects[]._ref` using the lookup queries in Look up identity management UUIDs.
`501 Not Implemented`	The AI agent feature is not enabled	Verify that the AI agent feature is enabled. Learn more in Enable the AI agents feature in your tenant environment.

400 Bad Request

Missing required field in privilege request body (for example, no resource or no agent reference)

Ensure both agent._ref and resource._ref are present in the request body.

401 Unauthorized

Access token is missing, expired, or has insufficient scope

Obtain a new service account access token with the required scopes (fr:am:* for agent operations; fr:idm:* for privilege operations).

404 Not Found

AI agent identity or privilege does not exist at the specified path

Verify the agent client ID or privilege UUID in the URL. Use the list endpoint to confirm the object exists.

412 Precondition Failed

If-None-Match: * was specified for create-only semantics, but an AI agent identity with this client ID already exists.

The AI agent identity already exists. Omit If-None-Match: * to allow an upsert, or use a different OAuth 2.0 client ID.

422 Unprocessable Entity

A privilege reference points to an identity management object that doesn’t exist (for example, an invalid AI agent identity UUID or application UUID)

Verify the UUIDs in agent._ref, resource._ref, and subjects[]._ref using the lookup queries in Look up identity management UUIDs.

501 Not Implemented

The AI agent feature is not enabled

Verify that the AI agent feature is enabled. Learn more in Enable the AI agents feature in your tenant environment.

PingOne Advanced Identity Cloud