Revoke Multiple Permissions on an Agent

DELETE

/api/v2/agents/{agent_id}/permissions/batch

Removes the roles of several users and teams on an agent in one call. Each item is applied on
its own, in order: an item that fails doesn't stop the others, and the items already applied
stay applied.

The response is 200 even when every item fails; read data.failed to find the items that
weren't applied. Each item follows the rules of DELETE /api/v2/agents/{agent_id}/permissions.

Requires edit_agent on the agent; organizations that don't use permission sets check
manage instead.

Request

Path Params

Header Params

Body Params

application/json

Required

Examples

Responses

🟢200

application/json

Every item was tried. This status is sent even when every item failed: data.revoked lists the items applied and data.failed the rest.

Headers

Bodyapplication/json

🟠400

🟠401

🟠403

🟠404

🔴500

🔴503

Request Example

Shell

JavaScript

Java

Swift

curl --location --globoff --request DELETE 'https:///api/v2/agents//permissions/batch' \
--header 'X-Authorization-Consistency-Token;' \
--header 'Organization-Id;' \
--header 'Ocp-Apim-Subscription-Key: ' \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{
    "revokes": [
        {
            "subject_type": "user",
            "subject_id": "456",
            "relation": "all"
        },
        {
            "subject_type": "team",
            "subject_id": "10",
            "relation": "member"
        }
    ]
}'

Response Example

200 - Some items failed

{
    "success": true,
    "message": "Batch revoke completed: 2 revoked, 1 failed",
    "data": {
        "agent_id": 42,
        "revoked": [
            {
                "subject_type": "user",
                "subject_id": "21",
                "subject_name": "Sam Ortiz",
                "revoked_relations": [
                    "member"
                ],
                "revoked_roles": [
                    "member"
                ]
            },
            {
                "subject_type": "team",
                "subject_id": "9",
                "subject_name": "Support Leads",
                "revoked_relations": [
                    "admin (team admins)",
                    "admin (team members)",
                    "member (team admins)",
                    "member (team members)"
                ],
                "revoked_roles": [
                    "admin",
                    "member"
                ]
            }
        ],
        "failed": [
            {
                "subject_type": "user",
                "subject_id": "15",
                "subject_name": "Dana Lee",
                "error": "User does not have member permission"
            }
        ],
        "revoked_at": "2026-10-28T14:14:09.873001+00:00"
    }
}

Grant Multiple Permissions on an Agent

Get User Permissions on a Specific Agent