This version of GitHub Enterprise Server was discontinued on 2024-07-09. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise Server. For help with the upgrade, contact GitHub Enterprise support.
REST API endpoints for external groups
Use the REST API 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.
About external groups
Note: SCIM for GitHub Enterprise Server is currently in private beta and is subject to change. For access to the beta, contact your account manager on GitHub's Sales team. Please provide feedback in the GitHub Community discussion.
Warning: The beta is exclusively for testing and feedback, and no support is available. GitHub recommends testing with a staging instance. For more information, see "Setting up a staging instance."
To use these endpoints, the authenticated user must be a team maintainer or an owner of the organization associated with the team.
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.
Parameters for "Get an external group"
| Name, Type, Description |
|---|
accept string Setting to |
| Name, Type, Description |
|---|
org string RequiredThe organization name. The name is not case sensitive. |
group_id integer RequiredThe unique identifier of the group. |
HTTP response status codes for "Get an external group"
| Status code | Description |
|---|---|
200 | OK |
Code samples for "Get an external group"
Request example
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/orgs/ORG/external-group/GROUP_IDResponse
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"
}
]
}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 Enterprise Server 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.
Parameters for "List external groups in an organization"
| Name, Type, Description |
|---|
accept string Setting to |
| Name, Type, Description |
|---|
org string RequiredThe organization name. The name is not case sensitive. |
| Name, Type, Description |
|---|
per_page integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: |
page integer Page token |
display_name string Limits the list to groups containing the text in the group name |
HTTP response status codes for "List external groups in an organization"
| Status code | Description |
|---|---|
200 | OK |
Code samples for "List external groups in an organization"
Request example
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/orgs/ORG/external-groupsResponse
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"
}
]
}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.
Parameters for "List a connection between an external group and a team"
| Name, Type, Description |
|---|
accept string Setting to |
| Name, Type, Description |
|---|
org string RequiredThe organization name. The name is not case sensitive. |
team_slug string RequiredThe slug of the team name. |
HTTP response status codes for "List a connection between an external group and a team"
| Status code | Description |
|---|---|
200 | OK |
Code samples for "List a connection between an external group and a team"
Request example
curl -L \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/orgs/ORG/teams/TEAM_SLUG/external-groupsResponse
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"
}
]
}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.
Parameters for "Update the connection between an external group and a team"
| Name, Type, Description |
|---|
accept string Setting to |
| Name, Type, Description |
|---|
org string RequiredThe organization name. The name is not case sensitive. |
team_slug string RequiredThe slug of the team name. |
| Name, Type, Description |
|---|
group_id integer RequiredExternal Group Id |
HTTP response status codes for "Update the connection between an external group and a team"
| Status code | Description |
|---|---|
200 | OK |
Code samples for "Update the connection between an external group and a team"
Request example
curl -L \
-X PATCH \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/orgs/ORG/teams/TEAM_SLUG/external-groups \
-d '{"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"
}
]
}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.
Parameters for "Remove the connection between an external group and a team"
| Name, Type, Description |
|---|
accept string Setting to |
| Name, Type, Description |
|---|
org string RequiredThe organization name. The name is not case sensitive. |
team_slug string RequiredThe slug of the team name. |
HTTP response status codes for "Remove the connection between an external group and a team"
| Status code | Description |
|---|---|
204 | No Content |
Code samples for "Remove the connection between an external group and a team"
Request example
curl -L \
-X DELETE \
-H "Accept: application/vnd.github+json" \
-H "Authorization: Bearer <YOUR-TOKEN>" \
-H "X-GitHub-Api-Version: 2022-11-28" \
http(s)://HOSTNAME/api/v3/orgs/ORG/teams/TEAM_SLUG/external-groupsResponse
Status: 204