--- title: Manage AI agent identities using the API description: Use the Advanced Identity Cloud REST API to create, read, update, and delete AI agent identities and AI agent privileges programmatically using a service account bearer token. component: pingoneaic page_id: pingoneaic:identity-for-ai:ai-agent-identities-api canonical_url: https://docs.pingidentity.com/pingoneaic/identity-for-ai/ai-agent-identities-api.html llms_txt: https://docs.pingidentity.com/pingoneaic/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md section_ids: prerequisites: Prerequisites authenticate-to-the-endpoints: Authenticate to the API endpoints manage-ai-agent-identities: Manage AI agent identities get-all-ai-agent-identities: Get all AI agent identities get-an-ai-agent-identity: Get an AI agent identity create-an-ai-agent-identity: Create an AI agent identity update-an-ai-agent-identity: Update an AI agent identity delete-an-ai-agent-identity: Delete an AI agent identity manage-ai-agent-identity-privileges: Manage AI agent identity privileges get-all-ai-agent-identity-privileges: Get all AI agent identity privileges get-an-ai-agent-identity-privilege: Get an AI agent identity privilege create-an-ai-agent-identity-privilege: Create an AI agent identity privilege update-an-ai-agent-privilege: Update an AI agent identity privilege delete-an-ai-agent-privilege: Delete an AI agent identity privilege look-up-identity-management-uuids: Look up identity management UUIDs look-up-an-ai-agent-identity-uuid: Look up an AI agent identity UUID look-up-application-uuid: Look up an application UUID look-up-user-uuid: Look up a user UUID --- # Manage AI agent identities using the API You can find background information on AI agent identities in PingOne Advanced Identity Cloud in [Secure your AI-driven solutions using AI agent identities](ai-agent-identities.html). ## Prerequisites Before managing AI agent identities using the API, verify that the following prerequisites are met: * The AI agents feature is enabled for your tenant environments. Learn more in [Enable the AI agents feature](ai-agent-identities-enable.html). * The OAuth 2.0 provider for your realm has the Token Exchange grant type enabled. Learn more in [Configure the OAuth 2.0 provider service](ai-agent-identities-configure-autonomous-agent-flow.html#configure-the-oauth-2-abbr-provider-service). ## Authenticate to the API endpoints To authenticate to the access management and identity management API endpoints, use an [access token](../developer-docs/authenticate-to-rest-api-with-access-token.html) created with one or both of the `fr:am:*` and `fr:idm:*` scopes. | Scope | API endpoint | Description | | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `fr:am:*` | * `/am/json/realms/root/realms//realm-config/agents/AIAgent` | Endpoint is part of the access management API. Use for agent operations. Each token request creates an access management session. A maximum of 5 concurrent access management sessions are allowed per service account identity. | | `fr:idm:*` | - `/openidm/managed/_aiagentprivilege` - `/openidm/managed/_aiagent` - `/openidm/managed/_application` - `/openidm/managed/_user` | Endpoints are part of the identity management API. Use for privilege operations and UUID lookups. Doesn't consume session quota. | For full lifecycle management of both agents and privileges, request both `fr:am:*` and `fr:idm:*` scopes. ## Manage AI agent identities All operations in this section use the access management REST API at `realm-config/agents/AIAgent` and require `fr:am:*` scope. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | When you create an AI agent identity via the access management REST API, Advanced Identity Cloud automatically creates a linked `managed/alpha_aiagent` object in identity management and records its UUID in the `aiAgentIdentityUid` field on the OAuth 2.0 client. You need this UUID when creating privileges for the identity. Learn more in [Look up identity management UUIDs](#look-up-identity-management-uuids). | ### Get all AI agent identities 1. [Get an access token](../developer-docs/authenticate-to-rest-api-with-access-token.html#get_an_access_token) with `fr:am:*` scope, or reuse an existing access token to minimize access management session consumption. 2. Run the following command: ```shell $ curl -G \ --request GET 'https:///am/json/realms/root/realms//realm-config/agents/AIAgent' \(1)(2) --header 'Accept-API-Version: resource=2.0' \ --header 'Authorization: Bearer ' \(3) --data-urlencode '_queryFilter=true' ``` > **Collapse: Show request guidance** > > | | | > | ----- | -------------------------------------------------------------------- | > | **1** | Replace \ with the FQDN of your tenant environment. | > | **2** | Replace \ with `alpha` or `bravo`. | > | **3** | Replace \ with your service account access token. | ```json { "result": [ { "_id": "bot-traffic-analyzer-agent", (1) "_rev": "-69253262", ..., "aiAgentIdentityUid": "2835a79f-aa51-446c-808d-0195b2fec75c", (2) ... }, { "_id": "digital-assistant-ai-agent", (1) "_rev": "-142442485", ... "aiAgentIdentityUid": "19301b4f-27ae-43fd-adc3-04389fd97f42", (2) ... } ], "resultCount": 2, ... } ``` > **Collapse: Show response guidance** > > | | | > | ----- | -------------------------------------------------------------------- | > | **1** | The OAuth 2.0 client IDs of the AI agent identities. | > | **2** | The identity management UUIDs of the linked `alpha_aiagent` objects. | ### Get an AI agent identity 1. [Get an access token](../developer-docs/authenticate-to-rest-api-with-access-token.html#get_an_access_token) with `fr:am:*` scope, or reuse an existing access token to minimize access management session consumption. 2. Run the following command: ```shell $ curl \ --request GET 'https:///am/json/realms/root/realms//realm-config/agents/AIAgent/' \(1)(2)(3) --header 'Accept-API-Version: resource=2.0' \ --header 'Authorization: Bearer '(4) ``` > **Collapse: Show request guidance** > > | | | > | ----- | ---------------------------------------------------------------------------------------------------------- | > | **1** | Replace \ with the FQDN of your tenant environment. | > | **2** | Replace \ with `alpha` or `bravo`. | > | **3** | Replace \ with the OAuth 2.0 client ID of the AI agent identity, for example, `my-agent`. | > | **4** | Replace \ with your service account access token. | ```json { "_id": "digital-assistant-ai-agent", (1) "_rev": "2028182383", "overrideOAuth2ClientConfig": { ... "acceptAudienceParametersInTokenExchangeRequests": true, (2) ... "providerOverridesEnabled": true, (3) ..., "statelessTokensEnabled": true, (4) ... }, "advancedOAuth2ClientConfig": { ... "tokenEndpointAuthMethod": { (5) "inherited": false, "value": "client_secret_post" }, ... "grantTypes": { (6) "inherited": false, "value": [ "urn:ietf:params:oauth:grant-type:token-exchange" ] }, }, ... "coreOAuth2ClientConfig": { ... "status": { (7) "inherited": false, "value": "Active" }, ... "clientType": { (8) "inherited": false, "value": "Confidential" }, ... "scopes": { (9) "inherited": false, "value": [] }, ... }, ... "aiAgentIdentityAttributes": { "inherited": false, "value": { "_id": "19301b4f-27ae-43fd-adc3-04389fd97f42", (10) "_rev": "696f19cc-4cda-4f9b-aad8-6fbd6d933672-1309951", "oauth2ClientId": "digital-assistant-ai-agent", (11) "name": "Digital Assistant Web App", (12) ... } }, "aiAgentIdentityUid": { "inherited": false, "value": "19301b4f-27ae-43fd-adc3-04389fd97f42" (13) }, "_type": { "_id": "AIAgent", "name": "AI Agents", "collection": true } } ``` > **Collapse: Show response guidance** > > | | | > | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | > | **1** | The OAuth 2.0 client ID of the AI agent identity. | > | **2** | Accept audience parameters in token exchange requests. When enabled, the identity can request access tokens for audiences that differ from its own. | > | **3** | Enable OAuth 2.0 provider overrides. When enabled, the identity can bypass realm-wide provider defaults and enforce its own custom token lifetimes, scripts, consent rules, and plugin settings. | > | **4** | Allow client-side access and refresh tokens. When enabled, the identity can request access and refresh tokens that are not stored in the server-side session. | > | **5** | The token endpoint auth method for the identity. Valid values are `client_secret_post` (credentials in POST body) or `client_secret_basic` (HTTP Basic Auth). | > | **6** | The OAuth 2.0 grant types for the identity. | > | **7** | The status of the identity. | > | **8** | The client type of the identity. | > | **9** | The allowed scopes for the identity. | > | **10** | The identity management UUID of the linked `alpha_aiagent` object. | > | **11** | The OAuth 2.0 client ID of the linked `alpha_aiagent` object. | > | **12** | The name of the linked `alpha_aiagent` object. | > | **13** | The identity management UUID of the linked `alpha_aiagent` object. | ### Create an AI agent identity You can use a single PUT request to create both the access management OAuth 2.0 client and the linked identity management `alpha_aiagent` object. 1. [Get an access token](../developer-docs/authenticate-to-rest-api-with-access-token.html#get_an_access_token) with `fr:am:*` scope, or reuse an existing access token to minimize access management session consumption. 2. Run the following command: ```shell $ curl \ --request PUT 'https:///am/json/realms/root/realms//realm-config/agents/AIAgent/' \(1)(2)(3) --header 'Accept-API-Version: resource=2.0' \ --header 'Content-Type: application/json' \ --header 'If-None-Match: *' \(4) --header 'Authorization: Bearer ' \(5) --data-raw '{ "aiAgentIdentityAttributes": { "inherited": false, "value": { "name": "", "oauth2ClientId": "" } }, "coreOAuth2ClientConfig": { "status": { "inherited": false, "value": "Active" }, "clientType": { "inherited": false, "value": "Confidential" }, "scopes": { "inherited": false, "value": }(6) }, "advancedOAuth2ClientConfig": { "grantTypes": { "inherited": false, "value": },(7) "tokenEndpointAuthMethod": { "inherited": false, "value": "" }(8) } }' ``` > **Collapse: Show request guidance** > > | | | > | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | **1** | Replace \ with the FQDN of your tenant environment. | > | **2** | Replace \ with `alpha` or `bravo`. | > | **3** | Replace \ with the OAuth 2.0 client ID for the new AI agent identity, for example, `my-agent`. | > | **4** | `If-None-Match: *` enforces create-only semantics; the request fails with HTTP 412 if an AI agent identity with this OAuth 2.0 client ID already exists. Omit this header to allow upsert (create or overwrite). | > | **5** | Replace \ with your service account access token. | > | **6** | Replace \ with a JSON array of scopes, for example, `["openid", "profile", "email"]`. An AI agent identity with no allowed scopes can't mint tokens. | > | **7** | Replace \ with a JSON array of grant types:- For an on-behalf-of agent: `["urn:ietf:params:oauth:grant-type:token-exchange"]` > > - For an autonomous agent: `["client_credentials", "urn:ietf:params:oauth:grant-type:token-exchange"]` | > | **8** | Replace \ with the token endpoint auth method: `client_secret_post` (credentials in POST body) or `client_secret_basic` (HTTP Basic Auth). The caller must use the same method when authenticating the AI agent identity in token exchange requests. | The request returns an HTTP 201 status code on success. Find an example response body in [Get an AI agent identity](#get-an-ai-agent-identity). ### Update an AI agent identity The access management REST API doesn't support PATCH for AI agent identity configuration. To update an AI agent identity, read the current configuration, modify the fields you want to change, remove `_rev` from the body, then PUT the full body back. 1. [Get an access token](../developer-docs/authenticate-to-rest-api-with-access-token.html#get_an_access_token) with `fr:am:*` scope, or reuse an existing access token to minimize access management session consumption. 2. Get the current configuration with a GET request: ```shell $ curl \ --request GET 'https:///am/json/realms/root/realms//realm-config/agents/AIAgent/' \(1)(2)(3) --header 'Accept-API-Version: resource=2.0' \ --header 'Authorization: Bearer '(4) ``` > **Collapse: Show request guidance** > > | | | > | ----- | ------------------------------------------------------------------------------------------- | > | **1** | Replace \ with the FQDN of your tenant environment. | > | **2** | Replace \ with `alpha` or `bravo`. | > | **3** | Replace \ with the OAuth 2.0 client ID of the AI agent identity to update. | > | **4** | Replace \ with your service account access token. | 3. Take the response body from the previous step, update the fields you want to change, then remove the `_rev` field. The following table contains common fields and their `jq` paths: | Field | `jq` path | | -------------------------- | ----------------------------------------------------------- | | Allowed scopes | `.coreOAuth2ClientConfig.scopes.value` | | Grant types | `.advancedOAuth2ClientConfig.grantTypes.value` | | Token endpoint auth method | `.advancedOAuth2ClientConfig.tokenEndpointAuthMethod.value` | | Client secret | `.userpassword` (write-only; not returned in GET responses) | 4. Update the configuration with a PUT request: ```shell $ curl \ --request PUT 'https:///am/json/realms/root/realms//realm-config/agents/AIAgent/' \(1)(2)(3) --header 'Accept-API-Version: resource=2.0' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \(4) --data-raw ''(5) ``` > **Collapse: Show request guidance** > > | | | > | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | > | **1** | Replace \ with the FQDN of your tenant environment. | > | **2** | Replace \ with `alpha` or `bravo`. | > | **3** | Replace \ with the OAuth 2.0 client ID of the AI agent identity to update. | > | **4** | Replace \ with your service account access token. | > | **5** | Replace \ with the response body from step 1, with your changes applied and the `_rev` field removed. To set the OAuth 2.0 client secret, add `"userpassword": ""` to the body (this field is write-only and isn't returned in GET responses). | The request returns an HTTP 200 status code on success. Find an example response body in [Get an AI agent identity](#get-an-ai-agent-identity). ### Delete an AI agent identity 1. [Get an access token](../developer-docs/authenticate-to-rest-api-with-access-token.html#get_an_access_token) with `fr:am:*` scope, or reuse an existing access token to minimize access management session consumption. 2. Run the following command: ```shell $ curl \ --request DELETE 'https:///am/json/realms/root/realms//realm-config/agents/AIAgent/' \(1)(2)(3) --header 'Accept-API-Version: resource=2.0' \ --header 'Authorization: Bearer '(4) ``` > **Collapse: Show request guidance** > > | | | > | ----- | ------------------------------------------------------------------------------------------- | > | **1** | Replace \ with the FQDN of your tenant environment. | > | **2** | Replace \ with `alpha` or `bravo`. | > | **3** | Replace \ with the OAuth 2.0 client ID of the AI agent identity to delete. | > | **4** | Replace \ with your service account access token. | The request returns an HTTP 200 status code on success. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Deleting an AI agent identity cascades immediately to delete the linked identity management `alpha_aiagent` object and all `alpha_aiagentprivilege` records associated with the identity. There's no need to delete privileges first. If you recreate an identity with the same client ID, it gets a new identity management UUID and you must recreate its privileges from scratch. Learn more in [Cascade behavior](ai-agent-identities-supplementary-information.html#cascade-behavior). | ## Manage AI agent identity privileges All privilege operations use the identity management REST API at `managed/alpha_aiagentprivilege` and require `fr:idm:*` scope. Privilege request bodies use identity management UUID references, not OAuth 2.0 client IDs. Use [Look up identity management UUIDs](#look-up-identity-management-uuids) to resolve human-readable IDs to identity management UUIDs before creating or updating privileges. ### Get all AI agent identity privileges 1. [Get an access token](../developer-docs/authenticate-to-rest-api-with-access-token.html#get_an_access_token) with `fr:idm:*` scope. 2. Run the following command: ```shell $ curl -G \ --request GET 'https:///openidm/managed/_aiagentprivilege' \(1)(2) --header 'Authorization: Bearer ' \(3) --data-urlencode '_queryFilter=true'(4) ``` > **Collapse: Show request guidance** > > | | | > | ----- | ---------------------------------------------------------------------------------------------------------------------------------------- | > | **1** | Replace \ with the FQDN of your tenant environment. | > | **2** | Replace \ with `alpha` or `bravo`. | > | **3** | Replace \ with your service account access token. | > | **4** | To filter by a specific AI agent identity, replace `true` with `agentOAuth2ClientId eq ""` (curl handles URL-encoding). | ```json { "result": [ { "_id": "cfdd1e7f-2750-4c6d-8730-2d689450b223", (1) "_rev": "696f19cc-4cda-4f9b-aad8-6fbd6d933672-1069810", "agentID": "19301b4f-27ae-43fd-adc3-04389fd97f42", (2) ... "agentOAuth2ClientId": "digital-assistant-ai-agent" (3) }, { "_id": "0fbe36e5-adff-481c-9adc-f7f8d08114a1", (1) "_rev": "696f19cc-4cda-4f9b-aad8-6fbd6d933672-1316846", "agentID": "2835a79f-aa51-446c-808d-0195b2fec75c", (2) ... "agentOAuth2ClientId": "bot-traffic-analyzer-agent" (3) } ], "resultCount": 2, ... } ``` > **Collapse: Show response guidance** > > | | | > | ----- | ------------------------------------------------------------------------------- | > | **1** | The UUID of the privilege. | > | **2** | The UUID of the AI agent identity associated with the privilege. | > | **3** | The OAuth 2.0 client ID of the AI agent identity associated with the privilege. | ### Get an AI agent identity privilege 1. [Get an access token](../developer-docs/authenticate-to-rest-api-with-access-token.html#get_an_access_token) with `fr:idm:*` scope. 2. Run the following command: ```shell $ curl \ --request GET 'https:///openidm/managed/_aiagentprivilege/' \(1)(2)(3) --header 'Authorization: Bearer '(4) ``` > **Collapse: Show request guidance** > > | | | > | ----- | --------------------------------------------------------------------------- | > | **1** | Replace \ with the FQDN of your tenant environment. | > | **2** | Replace \ with `alpha` or `bravo`. | > | **3** | Replace \ with the identity management UUID of the privilege. | > | **4** | Replace \ with your service account access token. | ```json { "_id": "cfdd1e7f-2750-4c6d-8730-2d689450b223", (1) "_rev": "696f19cc-4cda-4f9b-aad8-6fbd6d933672-1069810", "agentID": "19301b4f-27ae-43fd-adc3-04389fd97f42", (2) "subjectIDs": [ "fc87eea4-3c96-49d1-9620-bf23aca9bd97" (3) ], "permissions": [ { "type": "scopes", "values": [ (4) "read-data", "write-data" ] } ], "resourceData": { "ssoEntities": { "oidcId": "digital-assistant-web-app" (5) }, "_rev": "696f19cc-4cda-4f9b-aad8-6fbd6d933672-1057044", "_id": "7dd5b63f-274e-4984-8306-824d1c51ec35", "_refResourceCollection": "managed/alpha_application", "_refResourceId": "7dd5b63f-274e-4984-8306-824d1c51ec35", "_ref": "managed/alpha_application/7dd5b63f-274e-4984-8306-824d1c51ec35" }, "description": null, "agentOAuth2ClientId": "digital-assistant-ai-agent" (6) } ``` > **Collapse: Show response guidance** > > | | | > | ----- | ------------------------------------------------------------------------------------ | > | **1** | The UUID of the privilege. | > | **2** | The UUID of the AI agent identity associated with the privilege. | > | **3** | The UUIDs of permitted users (subjects) for this privilege. | > | **4** | The scopes the AI agent identity can request in a token exchange for this privilege. | > | **5** | The OAuth 2.0 client ID of the application associated with the privilege. | > | **6** | The OAuth 2.0 client ID of the AI agent identity associated with the privilege. | ### Create an AI agent identity privilege 1. [Get an access token](../developer-docs/authenticate-to-rest-api-with-access-token.html#get_an_access_token) with `fr:idm:*` scope. 2. Run the following command: ```shell $ curl \ --request POST 'https:///openidm/managed/_aiagentprivilege?_action=create' \(1)(2) --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \(3) --data-raw '{ "agent": { "_ref": "managed/alpha_aiagent/",(4) "_refProperties": {} }, "resource": { "_ref": "managed/alpha_application/",(5) "_refProperties": {} }, "subjects": [{ "_ref": "managed/alpha_user/",(6) "_refProperties": {} }], "subjectGroups": [], "permissions": [{ "type": "scopes", "values": (7) }] }' ``` > **Collapse: Show request guidance** > > | | | > | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | > | **1** | Replace \ with the FQDN of your tenant environment. | > | **2** | Replace \ with `alpha` or `bravo`. | > | **3** | Replace \ with your service account access token. | > | **4** | Replace \ with the identity management UUID of the AI agent identity. Learn more in [Look up identity management UUIDs](#look-up-identity-management-uuids). | > | **5** | Replace \ with the identity management UUID of the application. Learn more in [Look up identity management UUIDs](#look-up-identity-management-uuids). | > | **6** | For an on-behalf-of privilege, replace \ with the identity management UUID of a permitted user. For an autonomous privilege (no user subject), set `"subjects": []`. | > | **7** | Replace \ with a JSON array of scopes the identity can request in a token exchange, for example, `["openid", "profile", "email"]`. To allow any scope permitted by both the AI agent identity and application, set `"values": []`. | ```json { "_id": "cfdd1e7f-2750-4c6d-8730-2d689450b223", (1) "_rev": "696f19cc-4cda-4f9b-aad8-6fbd6d933672-1069810", "agentID": "19301b4f-27ae-43fd-adc3-04389fd97f42", (2) "subjectIDs": [ "fc87eea4-3c96-49d1-9620-bf23aca9bd97" (3) ], "permissions": [ { "type": "scopes", "values": [ (4) "read-data", "write-data" ] } ], "resourceData": { "ssoEntities": { "oidcId": "digital-assistant-web-app" (5) }, "_rev": "696f19cc-4cda-4f9b-aad8-6fbd6d933672-1057044", "_id": "7dd5b63f-274e-4984-8306-824d1c51ec35", "_refResourceCollection": "managed/alpha_application", "_refResourceId": "7dd5b63f-274e-4984-8306-824d1c51ec35", "_ref": "managed/alpha_application/7dd5b63f-274e-4984-8306-824d1c51ec35" }, "description": null, "agentOAuth2ClientId": "digital-assistant-ai-agent" (6) } ``` > **Collapse: Show response guidance** > > | | | > | ----- | ------------------------------------------------------------------------------------ | > | **1** | The UUID of the privilege. | > | **2** | The UUID of the AI agent identity associated with the privilege. | > | **3** | The UUIDs of permitted users (subjects) for this privilege. | > | **4** | The scopes the AI agent identity can request in a token exchange for this privilege. | > | **5** | The OAuth 2.0 client ID of the application associated with the privilege. | > | **6** | The OAuth 2.0 client ID of the AI agent identity associated with the privilege. | The response is denormalized, which means that identity management resolves reference fields and returns computed values. The key differences between the POST request body and the response are: | Read field | Write field | Notes | | --------------------- | ----------------- | --------------------------------------------------------------------------------------------------- | | `agentID` | `agent._ref` | Identity management UUID of the AI agent identity | | `agentOAuth2ClientId` | (computed) | OAuth 2.0 client ID of the AI agent identity (useful for filtering) | | `subjectIDs[]` | `subjects[]._ref` | Identity management UUIDs of permitted users | | `resourceData` | `resource._ref` | Resolved application object, including `ssoEntities.oidcId` (the application's OAuth 2.0 client ID) | | `permissions` | `permissions` | Same structure in both directions | | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | A privilege that omits the `permissions` field entirely, or omits `resource`, never matches at token-exchange time even if the identity management API accepts the object. Always include both fields. | ### Update an AI agent identity privilege Identity management supports partial updates to privileges using PATCH operations. Use the write field names (for example, `subjects`, `resource`), not the denormalized read field names returned in responses (for example, `subjectIDs`, `resourceData`). 1. [Get an access token](../developer-docs/authenticate-to-rest-api-with-access-token.html#get_an_access_token) with `fr:idm:*` scope. 2. Run the following command: ```shell $ curl \ --request PATCH 'https:///openidm/managed/_aiagentprivilege/' \(1)(2)(3) --header 'Content-Type: application/json' \ --header 'Authorization: Bearer ' \(4) --data-raw '[{ "operation": "replace", "field": "/permissions", "value": [{ "type": "scopes", "values": ["openid", "profile", "email"] }] }]' ``` > **Collapse: Show request guidance** > > | | | > | ----- | --------------------------------------------------------------------------- | > | **1** | Replace \ with the FQDN of your tenant environment. | > | **2** | Replace \ with `alpha` or `bravo`. | > | **3** | Replace \ with the identity management UUID of the privilege. | > | **4** | Replace \ with your service account access token. | ```json { "_id": "cfdd1e7f-2750-4c6d-8730-2d689450b223", "_rev": "696f19cc-4cda-4f9b-aad8-6fbd6d933672-1069810", ... "permissions": [ { "type": "scopes", "values": [ (1) "openid", "profile", "email" ] } ], ... "agentOAuth2ClientId": "digital-assistant-ai-agent" } ``` > **Collapse: Show response guidance** > > | | | > | ----- | -------------------------------------------------------------------------------------------- | > | **1** | The updated scopes the AI agent identity can request in a token exchange for this privilege. | The following table shows supported PATCH operations for privilege updates: | Field | Operation | Result | | -------------- | --------- | ------------------------------------------------------------------------------------------------------------- | | `/permissions` | `replace` | Replaces the full permissions array. Returns HTTP 200. | | `/subjects` | `replace` | Replaces the full subjects array, including replacing with an empty `[]`. Returns HTTP 200. | | `/subjects/-` | `add` | Appends a single `_ref` object to the subjects list. Returns HTTP 200. | | `/resource` | `replace` | Replaces the resource reference (changes which application the privilege grants access to). Returns HTTP 200. | To remove a specific user from subjects, use `replace` with a filtered array. The GET response returns subject UUIDs in the flat `subjectIDs` array. Reconstruct `_ref` objects from those UUIDs, filter out the UUID to remove, then PATCH with the updated array. ### Delete an AI agent identity privilege 1. [Get an access token](../developer-docs/authenticate-to-rest-api-with-access-token.html#get_an_access_token) with `fr:idm:*` scope. 2. Run the following command: ```shell $ curl \ --request DELETE 'https:///openidm/managed/_aiagentprivilege/' \(1)(2)(3) --header 'Authorization: Bearer '(4) ``` > **Collapse: Show request guidance** > > | | | > | ----- | --------------------------------------------------------------------------- | > | **1** | Replace \ with the FQDN of your tenant environment. | > | **2** | Replace \ with `alpha` or `bravo`. | > | **3** | Replace \ with the identity management UUID of the privilege. | > | **4** | Replace \ with your service account access token. | The request returns an HTTP 200 status code on success. The referenced AI agent identity and application are unaffected. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | Privilege changes take effect after the privilege cache expires (10 seconds by default). If you delete a privilege and immediately test a token exchange, you may still get a successful response until the cache expires. | ## Look up identity management UUIDs Privilege request bodies require identity management UUIDs, not OAuth 2.0 client IDs. Use these queries to resolve human-readable identifiers to identity management UUIDs. All lookups require `fr:idm:*` scope. ### Look up an AI agent identity UUID 1. [Get an access token](../developer-docs/authenticate-to-rest-api-with-access-token.html#get_an_access_token) with `fr:idm:*` scope. 2. Run the following command: ```shell $ curl -G \ --request GET 'https:///openidm/managed/_aiagent' \(1)(2) --header 'Authorization: Bearer ' \(3) --data-urlencode '_queryFilter=oauth2ClientId eq ""' \(4) --data '_fields=_id' ``` > **Collapse: Show request guidance** > > | | | > | ----- | ---------------------------------------------------------------------------------------------------------- | > | **1** | Replace \ with the FQDN of your tenant environment. | > | **2** | Replace \ with `alpha` or `bravo`. | > | **3** | Replace \ with your service account access token. | > | **4** | Replace \ with the OAuth 2.0 client ID of the AI agent identity, for example, `my-agent`. | ```json { "result": [ { "_id": "19301b4f-27ae-43fd-adc3-04389fd97f42", (1) "_rev": "696f19cc-4cda-4f9b-aad8-6fbd6d933672-1064136" } ], "resultCount": 1, ... } ``` > **Collapse: Show response guidance** > > | | | > | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | > | **1** | The UUID is in `.result[0]._id` of the response. You can also find the UUID in the `aiAgentIdentityUid.value` field of the response in [Get an AI agent identity](#get-an-ai-agent-identity). | ### Look up an application UUID 1. [Get an access token](../developer-docs/authenticate-to-rest-api-with-access-token.html#get_an_access_token) with `fr:idm:*` scope. 2. Run the following command: ```shell $ curl -G \ --request GET 'https:///openidm/managed/_application' \(1)(2) --header 'Authorization: Bearer ' \(3) --data-urlencode '_queryFilter=ssoEntities/oidcId eq ""' \(4) --data '_fields=_id' ``` > **Collapse: Show request guidance** > > | | | > | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | > | **1** | Replace \ with the FQDN of your tenant environment. | > | **2** | Replace \ with `alpha` or `bravo`. | > | **3** | Replace \ with your service account access token. | > | **4** | Replace \ with the OAuth 2.0 client ID of the application, for example, `my-app`. The filter uses `ssoEntities/oidcId`, which stores the OAuth 2.0 client ID on the application object. | ```json { "result": [ { "_id": "7dd5b63f-274e-4984-8306-824d1c51ec35", (1) "_rev": "696f19cc-4cda-4f9b-aad8-6fbd6d933672-1057044", } ], "resultCount": 1, ... } ``` > **Collapse: Show response guidance** > > | | | > | ----- | ------------------------------------------------ | > | **1** | The UUID is in `.result[0]._id` of the response. | ### Look up a user UUID 1. [Get an access token](../developer-docs/authenticate-to-rest-api-with-access-token.html#get_an_access_token) with `fr:idm:*` scope. 2. Run the following command: ```shell $ curl -G \ --request GET 'https:///openidm/managed/_user' \(1)(2) --header 'Authorization: Bearer ' \(3) --data-urlencode '_queryFilter=userName eq ""' \(4) --data '_fields=_id' ``` > **Collapse: Show request guidance** > > | | | > | ----- | ------------------------------------------------------------------------ | > | **1** | Replace \ with the FQDN of your tenant environment. | > | **2** | Replace \ with `alpha` or `bravo`. | > | **3** | Replace \ with your service account access token. | > | **4** | Replace \ with the username of the user, for example, `alice`. | ```json { "result": [ { "_id": "fc87eea4-3c96-49d1-9620-bf23aca9bd97", (1) "_rev": "696f19cc-4cda-4f9b-aad8-6fbd6d933672-1057047", } ], "resultCount": 1, ... } ``` > **Collapse: Show response guidance** > > | | | > | ----- | ------------------------------------------------ | > | **1** | The UUID is in `.result[0]._id` of the response. |