Grant Multiple Permissions on an Agent

POST

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

Shares an agent with several users and teams 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 POST /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.granted 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 '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 '{
    "grants": [
        {
            "subject_type": "user",
            "subject_id": "456",
            "relation": "admin"
        },
        {
            "subject_type": "user",
            "subject_id": "789",
            "relation": "member"
        },
        {
            "subject_type": "team",
            "subject_id": "10",
            "relation": "member"
        }
    ]
}'

Response Example

200 - Some items failed

{
    "success": true,
    "message": "Batch grant completed: 2 granted, 1 failed",
    "data": {
        "agent_id": 42,
        "granted": [
            {
                "subject_type": "user",
                "subject_id": "15",
                "subject_name": "Dana Lee",
                "relation": "admin"
            },
            {
                "subject_type": "team",
                "subject_id": "9",
                "subject_name": "Support Leads",
                "relation": "member"
            }
        ],
        "failed": [
            {
                "subject_type": "user",
                "subject_id": "999",
                "subject_name": null,
                "error": "User not found"
            }
        ],
        "granted_at": "2026-10-28T14:12:44.300125+00:00"
    }
}

Revoke Permission on an Agent

Revoke Multiple Permissions on an Agent