Grant Permission on an Agent

POST

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

Shares an agent with a user or a team by giving them a role on it. A permission is a role held
by one user or team, its subject, on one resource such as an agent, corpus, workflow, project or
team; the role is the level of access it grants, such as admin or member.

Granting adds the role to any role the subject already holds on the agent; to change a role,
use PUT /api/v2/agents/{agent_id}/permissions. When staging is on and the role is admin,
the agent's staging copy gets the same role.

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

🟢201

application/json

The role was given.

Headers

Bodyapplication/json

🟠400

🟠401

🟠403

🟠404

🔴500

🔴503

Request Example

Shell

JavaScript

Java

Swift

cURL

Grant user permissionGrant team permission

curl --location --globoff '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": "admin"
}'

Response Example

201 - Role given to a user

{
    "success": true,
    "message": "Permission granted successfully",
    "data": {
        "agent_id": 42,
        "subject_type": "user",
        "subject_id": "15",
        "subject_name": "Dana Lee",
        "relation": "admin",
        "granted_at": "2026-10-28T14:05:12.481203+00:00",
        "granted_by": {
            "user_id": "7",
            "email": "[email protected]",
            "name": "Alex Kim"
        }
    }
}

List all Permissions on an Agent

Update a Permission on an Agent