Update team | LaunchDarkly

Perform a partial update to a team. Updating a team uses the semantic patch format.

To make a semantic patch request, you must append domain-model=launchdarkly.semanticpatch to your Content-Type header. To learn more, read Updates using semantic patch.

Instructions

Semantic patch requests support the following kind instructions for updating teams. Several of the instructions require one or more member IDs as parameters. The member ID is returned as part of the List account members response. It is the _id field of each element in the items array.

Click to expand instructions for updating teams

addCustomRoles

Adds custom roles to the team. Team members will have these custom roles granted to them.

Parameters

values: List of custom role keys.

Here’s an example:

1 {
2   "instructions": [{
3     "kind": "addCustomRoles",
4     "values": [ "example-custom-role" ]
5   }]
6 }

addMembers

Adds members to the team.

Parameters

values: List of member IDs to add.

Here’s an example:

1 {
2   "instructions": [{
3     "kind": "addMembers",
4     "values": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ]
5   }]
6 }

addPermissionGrants

Adds permission grants to members for the team. For example, a permission grant could allow a member to act as a team maintainer. A permission grant may have either an actionSet or a list of actions but not both at the same time. The members do not have to be team members to have a permission grant for the team.

Parameters

actionSet: Name of the action set.
actions: List of actions.
memberIDs: List of member IDs.

Here’s an example:

1 {
2   "instructions": [{
3     "kind": "addPermissionGrants",
4     "actions": [ "updateTeamName", "updateTeamDescription" ],
5     "memberIDs": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ]
6   }]
7 }

addRoleAttribute

Adds a role attribute to a team. Team members will have these role attribute values scoped for all custom roles granted to them.

Parameters

key: The role attribute key to add.
values: List of role attribute values for that key.

Here’s an example:

1 {
2   "instructions": [
3     {
4       "kind": "addRoleAttribute",
5       "key": "testAttribute",
6       "values": ["someNewValue", "someOtherNewValue"]
7     }
8   ]
9 }

removeCustomRoles

Removes custom roles from the team. The app will no longer grant these custom roles to the team members.

Parameters

values: List of custom role keys.

Here’s an example:

1 {
2   "instructions": [{
3     "kind": "removeCustomRoles",
4     "values": [ "example-custom-role" ]
5   }]
6 }

removeMembers

Removes members from the team.

Parameters

values: List of member IDs to remove.

Here’s an example:

1 {
2   "instructions": [{
3     "kind": "removeMembers",
4     "values": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ]
5   }]
6 }

removePermissionGrants

Removes permission grants from members for the team. A permission grant may have either an actionSet or a list of actions but not both at the same time. The actionSet and actions must match an existing permission grant.

Parameters

actionSet: Name of the action set.
actions: List of actions.
memberIDs: List of member IDs.

Here’s an example:

1 {
2   "instructions": [{
3     "kind": "removePermissionGrants",
4     "actions": [ "updateTeamName", "updateTeamDescription" ],
5     "memberIDs": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ]
6   }]
7 }

removeRoleAttribute

Removes a role attribute from the team.

Parameters

key: The role attribute key to remove.

Here’s an example:

1 {
2   "instructions": [
3     {
4       "kind": "removeRoleAttribute",
5       "key": "testAttribute"
6     }
7   ]
8 }

replaceMembers

Replaces the existing members of the team with the new members.

Parameters

values: List of member IDs of the new members.

Here’s an example:

1 {
2   "instructions": [{
3     "kind": "replaceMembers",
4     "values": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ]
5   }]
6 }

replaceRoleAttributes

Replaces the existing role attributes for the team with new role attributes.

Parameters

value: A map of role attribute keys to lists of role attribute values

Here’s an example:

1 {
2   "instructions": [{
3     "kind": "replaceRoleAttributes",
4     "value": {
5       "testAttribute": [ "someNewValue", "someOtherNewValue" ],
6       "projectRoleAttribute": [ "project1", "project2"]
7     }
8   }]
9 }

updateDescription

Updates the description of the team.

Parameters

value: The new description.

Here’s an example:

1 {
2   "instructions": [{
3     "kind": "updateDescription",
4     "value": "Updated team description"
5   }]
6 }

updateName

Updates the name of the team.

Parameters

value: The new name.

Here’s an example:

1 {
2   "instructions": [{
3     "kind": "updateName",
4     "value": "Updated team name"
5   }]
6 }

updateRoleAttribute

Updates a role attribute on the team. Any existing values for the given key will be replaced with the new values. Team members will have these role attribute values scoped for all custom roles granted to them.

Parameters

key: The role attribute key to update.
values: List of role attribute values for that key.

Here’s an example:

1 {
2   "instructions": [
3     {
4       "kind": "updateRoleAttribute",
5       "key": "testAttribute",
6       "values": ["someNewValue", "someOtherNewValue"]
7     }
8   ]
9 }

Expanding the teams response

LaunchDarkly supports four fields for expanding the “Update team” response. By default, these fields are not included in the response.

To expand the response, append the expand query parameter and add a comma-separated list with any of the following fields:

members includes the total count of members that belong to the team.
roles includes a paginated list of the custom roles that you have assigned to the team.
projects includes a paginated list of the projects that the team has any write access to.
maintainers includes a paginated list of the maintainers that you have assigned to the team.

For example, expand=members,roles includes the members and roles fields in the response.

Perform a partial update to a team. Updating a team uses the semantic patch format. To make a semantic patch request, you must append `domain-model=launchdarkly.semanticpatch` to your `Content-Type` header. To learn more, read [Updates using semantic patch](https://launchdarkly.com/docs/api#updates-using-semantic-patch). ### Instructions Semantic patch requests support the following `kind` instructions for updating teams. Several of the instructions require one or more member IDs as parameters. The member ID is returned as part of the [List account members](https://launchdarkly.com/docs/ld-docs/api/account-members/get-members) response. It is the `_id` field of each element in the `items` array. <details> <summary>Click to expand instructions for <strong>updating teams</strong></summary> #### addCustomRoles Adds custom roles to the team. Team members will have these custom roles granted to them. ##### Parameters - `values`: List of custom role keys. Here's an example: ```json { "instructions": [{ "kind": "addCustomRoles", "values": [ "example-custom-role" ] }] } ``` #### addMembers Adds members to the team. ##### Parameters - `values`: List of member IDs to add. Here's an example: ```json { "instructions": [{ "kind": "addMembers", "values": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ] }] } ``` #### addPermissionGrants Adds permission grants to members for the team. For example, a permission grant could allow a member to act as a team maintainer. A permission grant may have either an `actionSet` or a list of `actions` but not both at the same time. The members do not have to be team members to have a permission grant for the team. ##### Parameters - `actionSet`: Name of the action set. - `actions`: List of actions. - `memberIDs`: List of member IDs. Here's an example: ```json { "instructions": [{ "kind": "addPermissionGrants", "actions": [ "updateTeamName", "updateTeamDescription" ], "memberIDs": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ] }] } ``` #### addRoleAttribute Adds a role attribute to a team. Team members will have these role attribute values scoped for all custom roles granted to them. ##### Parameters - `key`: The role attribute key to add. - `values`: List of role attribute values for that key. Here's an example: ```json { "instructions": [ { "kind": "addRoleAttribute", "key": "testAttribute", "values": ["someNewValue", "someOtherNewValue"] } ] } ``` #### removeCustomRoles Removes custom roles from the team. The app will no longer grant these custom roles to the team members. ##### Parameters - `values`: List of custom role keys. Here's an example: ```json { "instructions": [{ "kind": "removeCustomRoles", "values": [ "example-custom-role" ] }] } ``` #### removeMembers Removes members from the team. ##### Parameters - `values`: List of member IDs to remove. Here's an example: ```json { "instructions": [{ "kind": "removeMembers", "values": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ] }] } ``` #### removePermissionGrants Removes permission grants from members for the team. A permission grant may have either an `actionSet` or a list of `actions` but not both at the same time. The `actionSet` and `actions` must match an existing permission grant. ##### Parameters - `actionSet`: Name of the action set. - `actions`: List of actions. - `memberIDs`: List of member IDs. Here's an example: ```json { "instructions": [{ "kind": "removePermissionGrants", "actions": [ "updateTeamName", "updateTeamDescription" ], "memberIDs": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ] }] } ``` #### removeRoleAttribute Removes a role attribute from the team. ##### Parameters - `key`: The role attribute key to remove. Here's an example: ```json { "instructions": [ { "kind": "removeRoleAttribute", "key": "testAttribute" } ] } ``` #### replaceMembers Replaces the existing members of the team with the new members. ##### Parameters - `values`: List of member IDs of the new members. Here's an example: ```json { "instructions": [{ "kind": "replaceMembers", "values": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ] }] } ``` #### replaceRoleAttributes Replaces the existing role attributes for the team with new role attributes. ##### Parameters - `value`: A map of role attribute keys to lists of role attribute values Here's an example: ```json { "instructions": [{ "kind": "replaceRoleAttributes", "value": { "testAttribute": [ "someNewValue", "someOtherNewValue" ], "projectRoleAttribute": [ "project1", "project2"] } }] } ``` #### updateDescription Updates the description of the team. ##### Parameters - `value`: The new description. Here's an example: ```json { "instructions": [{ "kind": "updateDescription", "value": "Updated team description" }] } ``` #### updateName Updates the name of the team. ##### Parameters - `value`: The new name. Here's an example: ```json { "instructions": [{ "kind": "updateName", "value": "Updated team name" }] } ``` #### updateRoleAttribute Updates a role attribute on the team. Any existing values for the given key will be replaced with the new values. Team members will have these role attribute values scoped for all custom roles granted to them. ##### Parameters - `key`: The role attribute key to update. - `values`: List of role attribute values for that key. Here's an example: ```json { "instructions": [ { "kind": "updateRoleAttribute", "key": "testAttribute", "values": ["someNewValue", "someOtherNewValue"] } ] } ``` </details> ### Expanding the teams response LaunchDarkly supports four fields for expanding the "Update team" response. By default, these fields are **not** included in the response. To expand the response, append the `expand` query parameter and add a comma-separated list with any of the following fields: * `members` includes the total count of members that belong to the team. * `roles` includes a paginated list of the custom roles that you have assigned to the team. * `projects` includes a paginated list of the projects that the team has any write access to. * `maintainers` includes a paginated list of the maintainers that you have assigned to the team. For example, `expand=members,roles` includes the `members` and `roles` fields in the response.

Path parameters

teamKeystringRequired

The team key

Query parameters

expandstringOptional

A comma-separated list of properties that can reveal additional information in the response. Supported fields are explained above.

Request

This endpoint expects an object.

instructionslist of maps from strings to anyRequired

The instructions to perform when updating. This should be an array with objects that look like <code>{“kind”: “update_action”}</code>. Some instructions also require additional parameters as part of this object.

commentstringOptional

Optional comment describing the update

Response

Teams response

descriptionstring or null

A description of the team

keystring or null

The team key

namestring or null

A human-friendly name for the team

_accessobject or null

Details on the allowed and denied actions for this team

_creationDatelong or null

Timestamp of when the team was created

_linksmap from strings to objects or null

The location and content type of related resources

_lastModifiedlong or null

Timestamp of when the team was most recently updated

_versioninteger or null

The team version

_idpSyncedboolean or null

Whether the team has been synced with an external identity provider (IdP). Team sync is available to customers on an Enterprise plan.

roleAttributesmap from strings to lists of strings or null

A map of role attributes for the team

rolesobject or null

Paginated list of the custom roles assigned to this team. Only included if specified in the expand query parameter.

membersobject or null

Details on the total count of members that belong to the team. Only included if specified in the expand query parameter.

projectsobject or null

Paginated list of the projects that the team has any write access to. Only included if specified in the expand query parameter.

maintainersobject or null

Paginated list of the maintainers assigned to this team. Only included if specified in the expand query parameter.

Errors

Perform a partial update to a team. Updating a team uses the semantic patch format.

To make a semantic patch request, you must append domain-model=launchdarkly.semanticpatch to your Content-Type header. To learn more, read Updates using semantic patch.

Instructions

Click to expand instructions for updating teams

addCustomRoles

Adds custom roles to the team. Team members will have these custom roles granted to them.

Parameters

values: List of custom role keys.

Here’s an example:

1 {
2   "instructions": [{
3     "kind": "addCustomRoles",
4     "values": [ "example-custom-role" ]
5   }]
6 }

addMembers

Adds members to the team.

Parameters

values: List of member IDs to add.

Here’s an example:

1 {
2   "instructions": [{
3     "kind": "addMembers",
4     "values": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ]
5   }]
6 }

addPermissionGrants

Parameters

actionSet: Name of the action set.
actions: List of actions.
memberIDs: List of member IDs.

Here’s an example:

1 {
2   "instructions": [{
3     "kind": "addPermissionGrants",
4     "actions": [ "updateTeamName", "updateTeamDescription" ],
5     "memberIDs": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ]
6   }]
7 }

addRoleAttribute

Adds a role attribute to a team. Team members will have these role attribute values scoped for all custom roles granted to them.

Parameters

key: The role attribute key to add.
values: List of role attribute values for that key.

Here’s an example:

1 {
2   "instructions": [
3     {
4       "kind": "addRoleAttribute",
5       "key": "testAttribute",
6       "values": ["someNewValue", "someOtherNewValue"]
7     }
8   ]
9 }

removeCustomRoles

Removes custom roles from the team. The app will no longer grant these custom roles to the team members.

Parameters

values: List of custom role keys.

Here’s an example:

1 {
2   "instructions": [{
3     "kind": "removeCustomRoles",
4     "values": [ "example-custom-role" ]
5   }]
6 }

removeMembers

Removes members from the team.

Parameters

values: List of member IDs to remove.

Here’s an example:

1 {
2   "instructions": [{
3     "kind": "removeMembers",
4     "values": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ]
5   }]
6 }

removePermissionGrants

Parameters

actionSet: Name of the action set.
actions: List of actions.
memberIDs: List of member IDs.

Here’s an example:

1 {
2   "instructions": [{
3     "kind": "removePermissionGrants",
4     "actions": [ "updateTeamName", "updateTeamDescription" ],
5     "memberIDs": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ]
6   }]
7 }

removeRoleAttribute

Removes a role attribute from the team.

Parameters

key: The role attribute key to remove.

Here’s an example:

1 {
2   "instructions": [
3     {
4       "kind": "removeRoleAttribute",
5       "key": "testAttribute"
6     }
7   ]
8 }

replaceMembers

Replaces the existing members of the team with the new members.

Parameters

values: List of member IDs of the new members.

Here’s an example:

1 {
2   "instructions": [{
3     "kind": "replaceMembers",
4     "values": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ]
5   }]
6 }

replaceRoleAttributes

Replaces the existing role attributes for the team with new role attributes.

Parameters

value: A map of role attribute keys to lists of role attribute values

Here’s an example:

1 {
2   "instructions": [{
3     "kind": "replaceRoleAttributes",
4     "value": {
5       "testAttribute": [ "someNewValue", "someOtherNewValue" ],
6       "projectRoleAttribute": [ "project1", "project2"]
7     }
8   }]
9 }

updateDescription

Updates the description of the team.

Parameters

value: The new description.

Here’s an example:

1 {
2   "instructions": [{
3     "kind": "updateDescription",
4     "value": "Updated team description"
5   }]
6 }

updateName

Updates the name of the team.

Parameters

value: The new name.

Here’s an example:

1 {
2   "instructions": [{
3     "kind": "updateName",
4     "value": "Updated team name"
5   }]
6 }

updateRoleAttribute

Parameters

key: The role attribute key to update.
values: List of role attribute values for that key.

Here’s an example:

1 {
2   "instructions": [
3     {
4       "kind": "updateRoleAttribute",
5       "key": "testAttribute",
6       "values": ["someNewValue", "someOtherNewValue"]
7     }
8   ]
9 }

Expanding the teams response

LaunchDarkly supports four fields for expanding the “Update team” response. By default, these fields are not included in the response.

To expand the response, append the expand query parameter and add a comma-separated list with any of the following fields:

members includes the total count of members that belong to the team.
roles includes a paginated list of the custom roles that you have assigned to the team.
projects includes a paginated list of the projects that the team has any write access to.
maintainers includes a paginated list of the maintainers that you have assigned to the team.

For example, expand=members,roles includes the members and roles fields in the response.

1	import requests
2
3	url = "https://app.launchdarkly.com/api/v2/teams/teamKey"
4
5	payload = {
6	"instructions": [
7	{
8	"kind": "updateDescription",
9	"value": "New description for the team"
10	}
11	],
12	"comment": "Optional comment about the update"
13	}
14	headers = {
15	"Authorization": "<apiKey>",
16	"Content-Type": "application/json"
17	}
18
19	response = requests.patch(url, json=payload, headers=headers)
20
21	print(response.json())

1	{
2	"description": "Description for this team.",
3	"key": "team-key-123abc",
4	"name": "Example team",
5	"_access": {
6	"denied": [
7	{
8	"action": "action",
9	"reason": {
10	"effect": "allow"
11	}
12	}
13	],
14	"allowed": [
15	{
16	"action": "action",
17	"reason": {
18	"effect": "allow"
19	}
20	}
21	]
22	},
23	"_creationDate": 1000000,
24	"_links": {
25	"parent": {
26	"href": "/api/v2/teams",
27	"type": "application/json"
28	},
29	"roles": {
30	"href": "/api/v2/teams/example-team/roles",
31	"type": "application/json"
32	},
33	"self": {
34	"href": "/api/v2/teams/example-team",
35	"type": "application/json"
36	}
37	},
38	"_lastModified": 1000000,
39	"_version": 3,
40	"_idpSynced": true,
41	"roleAttributes": {
42	"key": [
43	"value"
44	]
45	},
46	"roles": {
47	"totalCount": 1,
48	"items": [
49	{
50	"key": "role-key-123abc",
51	"name": "Example role"
52	}
53	],
54	"_links": {
55	"self": {
56	"href": "/api/v2/teams/example-team/roles?limit=25",
57	"type": "application/json"
58	}
59	}
60	},
61	"members": {
62	"totalCount": 15
63	},
64	"projects": {
65	"totalCount": 1,
66	"items": [
67	{
68	"_id": "57be1db38b75bf0772d11383",
69	"_links": {
70	"environments": {
71	"href": "/api/v2/projects/example-project/environments",
72	"type": "application/json"
73	},
74	"self": {
75	"href": "/api/v2/projects/example-project",
76	"type": "application/json"
77	}
78	},
79	"key": "project-key-123abc",
80	"name": "Example project"
81	}
82	]
83	},
84	"maintainers": {
85	"totalCount": 1,
86	"items": [
87	{
88	"_links": {
89	"self": {
90	"href": "/api/v2/members/569f183514f4432160000007",
91	"type": "application/json"
92	}
93	},
94	"_id": "569f183514f4432160000007",
95	"role": "reader",
96	"email": "ariel@acme.com",
97	"firstName": "Ariel",
98	"lastName": "Flores"
99	}
100	],
101	"_links": {
102	"self": {
103	"href": "/api/v2/teams/example-team/maintainers?limit=20",
104	"type": "application/json"
105	}
106	}
107	}
108	}

1	{
2	"instructions": [{
3	"kind": "addCustomRoles",
4	"values": [ "example-custom-role" ]
5	}]
6	}

1	{
2	"instructions": [{
3	"kind": "addMembers",
4	"values": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ]
5	}]
6	}

1	{
2	"instructions": [{
3	"kind": "addPermissionGrants",
4	"actions": [ "updateTeamName", "updateTeamDescription" ],
5	"memberIDs": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ]
6	}]
7	}

1	{
2	"instructions": [
3	{
4	"kind": "addRoleAttribute",
5	"key": "testAttribute",
6	"values": ["someNewValue", "someOtherNewValue"]
7	}
8	]
9	}

1	{
2	"instructions": [{
3	"kind": "removeCustomRoles",
4	"values": [ "example-custom-role" ]
5	}]
6	}

1	{
2	"instructions": [{
3	"kind": "removeMembers",
4	"values": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ]
5	}]
6	}

1	{
2	"instructions": [{
3	"kind": "removePermissionGrants",
4	"actions": [ "updateTeamName", "updateTeamDescription" ],
5	"memberIDs": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ]
6	}]
7	}

1	{
2	"instructions": [
3	{
4	"kind": "removeRoleAttribute",
5	"key": "testAttribute"
6	}
7	]
8	}

1	{
2	"instructions": [{
3	"kind": "replaceMembers",
4	"values": [ "1234a56b7c89d012345e678f", "507f1f77bcf86cd799439011" ]
5	}]
6	}

1	{
2	"instructions": [{
3	"kind": "replaceRoleAttributes",
4	"value": {
5	"testAttribute": [ "someNewValue", "someOtherNewValue" ],
6	"projectRoleAttribute": [ "project1", "project2"]
7	}
8	}]
9	}

1	{
2	"instructions": [{
3	"kind": "updateDescription",
4	"value": "Updated team description"
5	}]
6	}

1	{
2	"instructions": [{
3	"kind": "updateName",
4	"value": "Updated team name"
5	}]
6	}

1	{
2	"instructions": [
3	{
4	"kind": "updateRoleAttribute",
5	"key": "testAttribute",
6	"values": ["someNewValue", "someOtherNewValue"]
7	}
8	]
9	}

Instructions

addCustomRoles

Parameters

addMembers

Parameters

addPermissionGrants

Parameters

addRoleAttribute

Parameters

removeCustomRoles

Parameters

removeMembers

Parameters

removePermissionGrants

Parameters

removeRoleAttribute

Parameters

replaceMembers

Parameters

replaceRoleAttributes

Parameters

updateDescription

Parameters

updateName

Parameters

updateRoleAttribute

Parameters

Expanding the teams response

Path parameters

Headers

Query parameters

Request

Response

Errors

Instructions

addCustomRoles

Parameters

addMembers

Parameters

addPermissionGrants

Parameters

addRoleAttribute

Parameters

removeCustomRoles

Parameters

removeMembers

Parameters

removePermissionGrants

Parameters

removeRoleAttribute

Parameters

replaceMembers

Parameters

replaceRoleAttributes

Parameters

updateDescription

Parameters

updateName

Parameters

updateRoleAttribute

Parameters

Expanding the teams response