Revoke Permission on an Agent

DELETE

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

Removes a user's or team's role on an agent. They keep any access that comes from elsewhere,
such as a role on the agent's project, a team they belong to, or being an organization admin.

With relation set to all, a user loses every role they hold on the agent, including the
owner role. Removing a role from a team succeeds even when the team didn't hold it. When
staging is on, the user or team also loses every role on the agent's staging copy.

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

The roles were removed.

Headers

Bodyapplication/json

🟠400

🟠401

🟠403

🟠404

🔴500

🔴503

Request Example

Shell

JavaScript

Java

Swift

cURL

Revoke all permissions from userRevoke specific permission from teamRevoke admin permission only

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

Response Example

200 - All roles removed from a user

{
    "success": true,
    "message": "Permission revoked successfully",
    "data": {
        "agent_id": 42,
        "subject_type": "user",
        "subject_id": "21",
        "subject_name": "Sam Ortiz",
        "revoked_relations": [
            "member",
            "member_user"
        ],
        "revoked_roles": [
            "member",
            "member_user"
        ],
        "revoked_at": "2026-10-28T14:10:31.704422+00:00"
    }
}

Update a Permission on an Agent

Grant Multiple Permissions on an Agent