External Groups - GitHub Docs

The external groups API allows you to view the external identity provider groups that are available to your organization and manage the connection between external groups and teams in your organization.

To use this API, the authenticated user must be a team maintainer or an owner of the organization associated with the team.

Notes:

The external groups API is only available for organizations that are part of a enterprise using Enterprise Managed Users. For more information, see "About Enterprise Managed Users."
If your organization uses team synchronization, you can use the Team Synchronization API. For more information, see "Team synchronization API."

Get an external group

Displays information about the specific group's usage. Provides a list of the group's external members as well as a list of teams that this group is connected to.

You can manage team membership with your identity provider using Enterprise Managed Users for GitHub Enterprise Cloud. For more information, see "GitHub's products" in the GitHub Help documentation.

get /orgs/{org}/external-group/{group_id}

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`org`	string	path
`group_id`	integer	path	group_id parameter

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/external-group/GROUP_ID

JavaScript @octokit/core.js

await octokit.request('GET /orgs/{org}/external-group/{group_id}', {
  org: 'ORG',
  group_id: 'GROUP_ID'
})

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  /orgs/ORG/external-group/GROUP_ID

Response

Status: 200

{
  "group_id": "123",
  "group_name": "Octocat admins",
  "updated_at": "2021-01-24T11:31:04-06:00",
  "teams": [
    {
      "team_id": 1,
      "team_name": "team-test"
    },
    {
      "team_id": 2,
      "team_name": "team-test2"
    }
  ],
  "members": [
    {
      "member_id": 1,
      "member_login": "mona-lisa_eocsaxrs",
      "member_name": "Mona Lisa",
      "member_email": "mona_lisa@github.com"
    },
    {
      "member_id": 2,
      "member_login": "octo-lisa_eocsaxrs",
      "member_name": "Octo Lisa",
      "member_email": "octo_lisa@github.com"
    }
  ]
}

Status codes

HTTP Status Code	Description
`200`	OK

Notes

Works with GitHub Apps

List external groups in an organization

Lists external groups available in an organization. You can query the groups using the display_name parameter, only groups with a group_name containing the text provided in the display_name parameter will be returned. You can also limit your page results using the per_page parameter. GitHub generates a url-encoded page token using a cursor value for where the next page begins. For more information on cursor pagination, see "Offset and Cursor Pagination explained."

You can manage team membership with your identity provider using Enterprise Managed Users for GitHub Enterprise Cloud. For more information, see "GitHub's products" in the GitHub Help documentation.

get /orgs/{org}/external-groups

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`org`	string	path
`per_page`	integer	query	Results per page (max 100) Default: `30`
`page`	integer	query	Page token
`display_name`	string	query	Limits the list to groups containing the text in the group name

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/external-groups

JavaScript @octokit/core.js

await octokit.request('GET /orgs/{org}/external-groups', {
  org: 'ORG'
})

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  /orgs/ORG/external-groups

Response

Status: 200

{
  "groups": [
    {
      "group_id": "123",
      "group_name": "Octocat admins",
      "updated_at": "2021-01-24T11:31:04-06:00"
    },
    {
      "group_id": "456",
      "group_name": "Octocat docs members",
      "updated_at": "2021-03-24T11:31:04-06:00"
    }
  ]
}

Status codes

HTTP Status Code	Description
`200`	OK

Notes

Works with GitHub Apps

List a connection between an external group and a team

Lists a connection between a team and an external group.

You can manage team membership with your identity provider using Enterprise Managed Users for GitHub Enterprise Cloud. For more information, see "GitHub's products" in the GitHub Help documentation.

get /orgs/{org}/teams/{team_slug}/external-groups

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`org`	string	path
`team_slug`	string	path	team_slug parameter

Code samples

Example

Shell

curl \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/teams/TEAM_SLUG/external-groups

JavaScript @octokit/core.js

await octokit.request('GET /orgs/{org}/teams/{team_slug}/external-groups', {
  org: 'ORG',
  team_slug: 'TEAM_SLUG'
})

GitHub CLI gh api

gh api \
  -H "Accept: application/vnd.github.v3+json" \
  /orgs/ORG/teams/TEAM_SLUG/external-groups

Response

Status: 200

{
  "groups": [
    {
      "group_id": "123",
      "group_name": "Octocat admins",
      "updated_at": "2021-01-24T11:31:04-06:00"
    },
    {
      "group_id": "456",
      "group_name": "Octocat docs members",
      "updated_at": "2021-03-24T11:31:04-06:00"
    }
  ]
}

Status codes

HTTP Status Code	Description
`200`	OK

Notes

Works with GitHub Apps

Update the connection between an external group and a team

Creates a connection between a team and an external group. Only one external group can be linked to a team.

You can manage team membership with your identity provider using Enterprise Managed Users for GitHub Enterprise Cloud. For more information, see "GitHub's products" in the GitHub Help documentation.

patch /orgs/{org}/teams/{team_slug}/external-groups

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`org`	string	path
`team_slug`	string	path	team_slug parameter
`group_id`	integer	body	Required. External Group Id

Code samples

Example

Shell

curl \
  -X PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/teams/TEAM_SLUG/external-groups \
  -d '{"group_id":123}'

JavaScript @octokit/core.js

await octokit.request('PATCH /orgs/{org}/teams/{team_slug}/external-groups', {
  org: 'ORG',
  team_slug: 'TEAM_SLUG',
  group_id: 123
})

GitHub CLI gh api

gh api \
  --method PATCH \
  -H "Accept: application/vnd.github.v3+json" \
  /orgs/ORG/teams/TEAM_SLUG/external-groups \
  -F group_id=123

Response

Status: 200

{
  "group_id": "123",
  "group_name": "Octocat admins",
  "updated_at": "2021-01-24T11:31:04-06:00",
  "teams": [
    {
      "team_id": 1,
      "team_name": "team-test"
    },
    {
      "team_id": 2,
      "team_name": "team-test2"
    }
  ],
  "members": [
    {
      "member_id": 1,
      "member_login": "mona-lisa_eocsaxrs",
      "member_name": "Mona Lisa",
      "member_email": "mona_lisa@github.com"
    },
    {
      "member_id": 2,
      "member_login": "octo-lisa_eocsaxrs",
      "member_name": "Octo Lisa",
      "member_email": "octo_lisa@github.com"
    }
  ]
}

Status codes

HTTP Status Code	Description
`200`	OK

Remove the connection between an external group and a team

Deletes a connection between a team and an external group.

You can manage team membership with your IdP using Enterprise Managed Users for GitHub Enterprise Cloud. For more information, see GitHub's products in the GitHub Help documentation.

delete /orgs/{org}/teams/{team_slug}/external-groups

Parameters

Name	Type	In	Description
`accept`	string	header	Setting to`application/vnd.github.v3+json` is recommended.
`org`	string	path
`team_slug`	string	path	team_slug parameter

Code samples

Example

Shell

curl \
  -X DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/orgs/ORG/teams/TEAM_SLUG/external-groups

JavaScript @octokit/core.js

await octokit.request('DELETE /orgs/{org}/teams/{team_slug}/external-groups', {
  org: 'ORG',
  team_slug: 'TEAM_SLUG'
})

GitHub CLI gh api

gh api \
  --method DELETE \
  -H "Accept: application/vnd.github.v3+json" \
  /orgs/ORG/teams/TEAM_SLUG/external-groups

Response

Status: 204

Status codes

HTTP Status Code	Description
`204`	No Content