Teams

Teams is an Enterprise feature

Teams is available to customers on an Enterprise plan. To learn more, read about our pricing. To upgrade your plan, contact Sales.

A team is a group of members in your LaunchDarkly account. A team can have maintainers who are able to add and remove team members. It also can have custom roles assigned to it that allows shared access to those roles for all team members. To learn more, read Teams.

The Teams API allows you to create, read, update, and delete a team.

List teams

Return a list of teams.

By default, this returns the first 20 teams. Page through this list with the limit parameter and by following the first, prev, next, and last links in the _links field that returns. If those links do not appear, the pages they refer to don't exist. For example, the first and prev links will be missing from the response on the first page, because there is no previous page and you cannot return to the first page when you are already on the first page.

Filtering teams

LaunchDarkly supports the following fields for filters:

  • query is a string that matches against the teams' names and keys. It is not case-sensitive.
    • A request with query:abc returns teams with the string abc in their name or key.
  • nomembers is a boolean that filters the list of teams who have 0 members
    • A request with nomembers:true returns teams that have 0 members
    • A request with nomembers:false returns teams that have 1 or more members

Expanding the teams response

LaunchDarkly supports four fields for expanding the "List teams" 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.

Request
query Parameters
limit
integer <int64>

The number of teams to return in the response. Defaults to 20.

offset
integer <int64>

Where to start in the list. Use this with pagination. For example, an offset of 10 skips the first ten items and returns the next limit items.

filter
string <string>

A comma-separated list of filters. Each filter is constructed as field:value.

expand
string <string>

A comma-separated list of properties that can reveal additional information in the response.

Responses
200

Teams collection response

401

Invalid access token

405

Method not allowed

429

Rate limited

get/api/v2/teams
Request samples
Response samples
application/json
{
  • "items": [
    ],
  • "_links": {
    },
  • "totalCount": 1
}

Create team

Create a team. To learn more, read Creating a team.

Expanding the teams response

LaunchDarkly supports four fields for expanding the "Create 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.

Request
query Parameters
expand
string <string>

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

Request Body schema: application/json
customRoleKeys
Array of strings

List of custom role keys the team will access

description
string

A description of the team

key
required
string

The team key

memberIDs
Array of strings

A list of member IDs who belong to the team

name
required
string

A human-friendly name for the team

Array of objects (permissionGrantInput)

A list of permission grants. Permission grants allow access to a specific action, without having to create or update a custom role.

Responses
201

Teams response

400

Invalid request

401

Invalid access token

405

Method not allowed

429

Rate limited

post/api/v2/teams
Request samples
application/json
{
  • "customRoleKeys": [
    ],
  • "description": "An example team",
  • "key": "example-team",
  • "memberIDs": [
    ],
  • "name": "Example team"
}
Response samples
application/json
{
  • "description": "Description for this team.",
  • "key": "example-team",
  • "name": "Example team",
  • "_access": {
    },
  • "_creationDate": 0,
  • "_links": {
    },
  • "_lastModified": 0,
  • "_version": 3,
  • "_idpSynced": true,
  • "roles": {
    },
  • "members": {
    },
  • "projects": {
    },
  • "maintainers": {
    }
}

Get team

Fetch a team by key.

Expanding the teams response

LaunchDarkly supports four fields for expanding the "Get 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.

Request
path Parameters
teamKey
required
string <string>

The team key.

query Parameters
expand
string <string>

A comma-separated list of properties that can reveal additional information in the response.

Responses
200

Teams response

400

Invalid request

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

405

Method not allowed

429

Rate limited

get/api/v2/teams/{teamKey}
Request samples
Response samples
application/json
{
  • "description": "Description for this team.",
  • "key": "example-team",
  • "name": "Example team",
  • "_access": {
    },
  • "_creationDate": 0,
  • "_links": {
    },
  • "_lastModified": 0,
  • "_version": 3,
  • "_idpSynced": true,
  • "roles": {
    },
  • "members": {
    },
  • "projects": {
    },
  • "maintainers": {
    }
}

Update team

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.

addCustomRoles

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

Parameters
  • values: List of custom role keys.

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.

addMembers

Adds members to the team.

Parameters
  • values: List of member IDs.

removeMembers

Removes members from the team.

Parameters
  • values: List of member IDs.

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.

removePermissionGrants

Removes permission grants from members for the team. 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.

updateDescription

Updates the description of the team.

Parameters
  • value: The new description.

updateName

Updates the name of the team.

Parameters
  • value: The new name.

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.

Request
path Parameters
teamKey
required
string <string>

The team key

query Parameters
expand
string <string>

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

Request Body schema: application/json
comment
string

Optional comment describing the update

required
Array of objects (Instructions)
Responses
200

Teams response

400

Invalid request

401

Invalid access token

404

Invalid resource identifier

405

Method not allowed

409

Status conflict

429

Rate limited

patch/api/v2/teams/{teamKey}
Request samples
application/json
{
  • "comment": "Optional comment about the update",
  • "instructions": [
    ]
}
Response samples
application/json
{
  • "description": "Description for this team.",
  • "key": "example-team",
  • "name": "Example team",
  • "_access": {
    },
  • "_creationDate": 0,
  • "_links": {
    },
  • "_lastModified": 0,
  • "_version": 3,
  • "_idpSynced": true,
  • "roles": {
    },
  • "members": {
    },
  • "projects": {
    },
  • "maintainers": {
    }
}

Delete team

Delete a team by key. To learn more, read Deleting a team.

Request
path Parameters
teamKey
required
string <string>

The team key

Responses
204

Action succeeded

401

Invalid access token

404

Invalid resource identifier

429

Rate limited

delete/api/v2/teams/{teamKey}
Request samples
Response samples
application/json
{
  • "code": "unauthorized",
  • "message": "Invalid access token"
}

Get team maintainers

Fetch the maintainers that have been assigned to the team. To learn more, read Managing team maintainers.

Request
path Parameters
teamKey
required
string <string>

The team key

query Parameters
limit
integer <int64>

The number of maintainers to return in the response. Defaults to 20.

offset
integer <int64>

Where to start in the list. This is for use with pagination. For example, an offset of 10 skips the first ten items and then returns the next items in the list, up to the query limit.

Responses
200

Team maintainers response

400

Invalid request

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

405

Method not allowed

429

Rate limited

get/api/v2/teams/{teamKey}/maintainers
Request samples
Response samples
application/json
{
  • "totalCount": 1,
  • "items": [
    ],
  • "_links": {
    }
}

Add multiple members to team

Add multiple members to an existing team by uploading a CSV file of member email addresses. Your CSV file must include email addresses in the first column. You can include data in additional columns, but LaunchDarkly ignores all data outside the first column. Headers are optional. To learn more, read Managing team members.

Members are only added on a 201 response. A 207 indicates the CSV file contains a combination of valid and invalid entries. A 207 results in no members being added to the team.

On a 207 response, if an entry contains bad user input, the message field contains the row number as well as the reason for the error. The message field is omitted if the entry is valid.

Example 207 response:

{
  "items": [
    {
      "status": "success",
      "value": "a-valid-email@launchdarkly.com"
    },
    {
      "message": "Line 2: empty row",
      "status": "error",
      "value": ""
    },
    {
      "message": "Line 3: email already exists in the specified team",
      "status": "error",
      "value": "existing-team-member@launchdarkly.com"
    },
    {
      "message": "Line 4: invalid email formatting",
      "status": "error",
      "value": "invalid email format"
    }
  ]
}
Message Resolution
Empty row This line is blank. Add an email address and try again.
Duplicate entry This email address appears in the file twice. Remove the email from the file and try again.
Email already exists in the specified team This member is already on your team. Remove the email from the file and try again.
Invalid formatting This email address is not formatted correctly. Fix the formatting and try again.
Email does not belong to a LaunchDarkly member The email address doesn't belong to a LaunchDarkly account member. Invite them to LaunchDarkly, then re-add them to the team.

On a 400 response, the message field may contain errors specific to this endpoint.

Example 400 response:

{
  "code": "invalid_request",
  "message": "Unable to process file"
}
Message Resolution
Unable to process file LaunchDarkly could not process the file for an unspecified reason. Review your file for errors and try again.
File exceeds 25mb Break up your file into multiple files of less than 25mbs each.
All emails have invalid formatting None of the email addresses in the file are in the correct format. Fix the formatting and try again.
All emails belong to existing team members All listed members are already on this team. Populate the file with member emails that do not belong to the team and try again.
File is empty The CSV file does not contain any email addresses. Populate the file and try again.
No emails belong to members of your LaunchDarkly organization None of the email addresses belong to members of your LaunchDarkly account. Invite these members to LaunchDarkly, then re-add them to the team.
Request
path Parameters
teamKey
required
string <string>

The team key

Request Body schema: multipart/form-data
file
string <binary>

CSV file containing email addresses

Responses
201

Team member imports response

207

Partial Success

400

Invalid request

401

Invalid access token

405

Method not allowed

429

Rate limited

post/api/v2/teams/{teamKey}/members
Request samples
Response samples
application/json
{
  • "items": [
    ]
}

Get team custom roles

Fetch the custom roles that have been assigned to the team. To learn more, read Managing team permissions.

Request
path Parameters
teamKey
required
string <string>

The team key

query Parameters
limit
integer <int64>

The number of roles to return in the response. Defaults to 20.

offset
integer <int64>

Where to start in the list. This is for use with pagination. For example, an offset of 10 skips the first ten items and then returns the next items in the list, up to the query limit.

Responses
200

Team roles response

400

Invalid request

401

Invalid access token

403

Forbidden

404

Invalid resource identifier

405

Method not allowed

429

Rate limited

get/api/v2/teams/{teamKey}/roles
Request samples
Response samples
application/json
{
  • "totalCount": 1,
  • "items": [
    ],
  • "_links": {
    }
}