Grant Permission on a Project

POST

/api/v2/projects/{project_id}/permissions

Shares a project with a user or a team by giving them a role on it. A role on a project also
applies to every agent in the project.

Granting adds the role to any role the user or team already holds on the project; to change a
role, use PUT /api/v2/projects/{project_id}/permissions. A user given a role also starts
receiving the project's notifications, such as new comments on its agents.

Requires manage on the project, which project admins (directly or through a team) and
organization admins have.

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/projects//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": {
        "project_id": 7,
        "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 a Project

Update a Permission on a Project