Assign organization member role | Management API Reference

Assign or change an organization member role

patch/v2/organizations/{slug}/members/{user_id}/roles

Assigns an org-wide role when projects is omitted, or creates a project-scoped assignment when projects is provided. Uses an org-level role template id from GET /v2/organizations/{slug}/roles. Stale role assignments are automatically cleaned up: if a role no longer has any projects, it is deleted; overlapping project assignments in other roles are automatically removed to avoid duplication.

OAuth scopes

organizations:write

This endpoint is only available on the following plans:

Team
Enterprise

The fine-grained token must include the following permissions to access this endpoint:

organization_admin_write

Path parameters

slug
Required
string
Organization slug
user_id
Required
string

Body

data
Required
object

Response codes

Response (200)

1
{
2
  "data": {
3
    "type": "organization_member_role",
4
    "attributes": {
5
      "name": "developer",
6
      "scope": "organization",
7
      "projects": [
8
        {
9
          "ref": "lorem",
10
          "name": "lorem"
11
        }
12
      ]
13
    }
14
  }
15
}

1
{
2
  "type": "object",
3
  "properties": {
4
    "data": {
5
      "type": "object",
6
      "properties": {
7
        "type": {
8
          "type": "string",
9
          "description": "Resource type.",
10
          "enum": [
11
            "organization_member_role"
12
          ]
13
        },
14
        "attributes": {
15
          "type": "object",
16
          "properties": {
17
            "name": {
18
              "type": "string",
19
              "description": "Role name. For project-scoped assignments this is the base role name.",
20
              "example": "developer"
21
            },
22
            "scope": {
23
              "type": "string",
24
              "enum": [
25
                "organization",
26
                "project"
27
              ],
28
              "description": "Whether this role applies org-wide or is scoped to specific projects for the user."
29
            },
30
            "projects": {
31
              "type": "array",
32
              "items": {
33
                "type": "object",
34
                "properties": {
35
                  "ref": {
36
                    "type": "string"
37
                  },
38
                  "name": {
39
                    "type": "string"
40
                  }
41
                },
42
                "required": [
43
                  "ref",
44
                  "name"
45
                ]
46
              },
47
              "description": "Project refs this role is scoped to. Empty array for org-level roles."
48
            }
49
          },
50
          "required": [
51
            "name",
52
            "scope",
53
            "projects"
54
          ]
55
        }
56
      },
57
      "required": [
58
        "type",
59
        "attributes"
60
      ]
61
    }
62
  },
63
  "required": [
64
    "data"
65
  ]
66
}