Grant Multiple Permissions on a Team

POST

/api/v2/teams/{team_id}/permissions/batch

Adds several users to a team, or gives them roles on it, 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/teams/{team_id}/permissions.

Requires manage on the team: being one of its admins, or an organization admin.

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. A user who isn't in the team's organization is listed in failed, then listed a second time, matching the last earlier item whose role was tried: in failed again with that item's error, or in granted under that item's name when that item was applied. With no such earlier item, the second entry is in failed with an unexpected error's text. Either way the user gets no role on the team.

Headers

Bodyapplication/json

🟠400

🟠401

🟠403

🟠404

🔴500

🔴503

Request Example

Shell

JavaScript

Java

Swift

curl --location --globoff 'https:///api/v2/teams//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": "user",
            "subject_id": "321",
            "relation": "member"
        }
    ]
}'

Response Example

200 - Some items failed

{
    "success": true,
    "message": "Batch grant completed: 2 granted, 1 failed",
    "data": {
        "team_id": 9,
        "granted": [
            {
                "subject_type": "user",
                "subject_id": "15",
                "subject_name": "Dana Lee",
                "relation": "admin"
            },
            {
                "subject_type": "user",
                "subject_id": "21",
                "subject_name": "Sam Ortiz",
                "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 a Team

Revoke Multiple Permissions on a Team