GitHub External API

openapi: 3.2.0
info:
  title: Github External API
  version: 1.1.4
  contact:
    name: Support
    url: https://support.github.com/contact?tags=dotcom-rest-api
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  termsOfService: https://docs.github.com/articles/github-terms-of-service
  description: 'Operations tagged External across 2 of this provider''s published API definitions: github-organizations-openapi.yml, github-teams-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: '{protocol}://{hostname}/api/v3'
  variables:
    hostname:
      description: Self-hosted Enterprise Server hostname
      default: HOSTNAME
    protocol:
      description: Self-hosted Enterprise Server protocol
      default: http
tags:
- name: External
paths:
  /orgs/{org}/external-group/{group_id}:
    get:
      summary: GitHub Get an External Group
      description: '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](https://docs.github.com/enterprise-server@3.9/github/getting-started-with-github/githubs-products)" in the GitHub Help documentation.'
      tags:
      - External
      operationId: getAnExternalGroup
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/teams/external-groups#get-an-external-group
      parameters:
      - $ref: '#/components/parameters/org'
      - $ref: '#/components/parameters/group-id'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/external-group'
              examples:
                default:
                  $ref: '#/components/examples/external-group'
      x-github:
        githubCloudOnly: true
        enabledForGitHubApps: true
        category: teams
        subcategory: external-groups
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    servers:
    - url: '{protocol}://{hostname}/api/v3'
      variables:
        hostname:
          description: Self-hosted Enterprise Server hostname
          default: HOSTNAME
        protocol:
          description: Self-hosted Enterprise Server protocol
          default: http
  /orgs/{org}/external-groups:
    get:
      summary: GitHub List External Groups in an Organization
      description: '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](https://dev.to/jackmarchant/offset-and-cursor-pagination-explained-b89)."


        You can manage team membership with your identity provider using Enterprise Managed Users for GitHub Enterprise Cloud. For more information, see "[GitHub''s products](https://docs.github.com/enterprise-server@3.9/github/getting-started-with-github/githubs-products)" in the GitHub Help documentation.'
      tags:
      - External
      operationId: listExternalGroupsInAnOrganization
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/teams/external-groups#list-external-groups-in-an-organization
      parameters:
      - $ref: '#/components/parameters/org'
      - $ref: '#/components/parameters/per-page'
      - name: page
        description: Page token
        in: query
        schema:
          type: integer
        example: 42
      - name: display_name
        description: Limits the list to groups containing the text in the group name
        in: query
        schema:
          type: string
        example: octocat
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/external-groups'
              examples:
                default:
                  $ref: '#/components/examples/external-groups'
          headers:
            Link:
              example: <https://api.github.com/resource?per_page=2&page=url-encoded-next-page-token>; rel="next"
              schema:
                type: string
      x-github:
        githubCloudOnly: true
        enabledForGitHubApps: true
        category: teams
        subcategory: external-groups
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    servers:
    - url: '{protocol}://{hostname}/api/v3'
      variables:
        hostname:
          description: Self-hosted Enterprise Server hostname
          default: HOSTNAME
        protocol:
          description: Self-hosted Enterprise Server protocol
          default: http
  /orgs/{org}/teams/{team_slug}/external-groups:
    get:
      summary: GitHub List Connection Between an External Group and Team
      description: '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](https://docs.github.com/enterprise-server@3.9/github/getting-started-with-github/githubs-products)" in the GitHub Help documentation.'
      tags:
      - External
      operationId: listConnectionBetweenAnExternalGroupAndTeam
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/teams/external-groups#list-a-connection-between-an-external-group-and-a-team
      parameters:
      - $ref: '#/components/parameters/org'
      - $ref: '#/components/parameters/team-slug'
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/external-groups'
              examples:
                default:
                  $ref: '#/components/examples/external-groups'
      x-github:
        githubCloudOnly: true
        enabledForGitHubApps: true
        category: teams
        subcategory: external-groups
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      summary: GitHub Update the Connection Between an External Group and Team
      description: '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](https://docs.github.com/enterprise-server@3.9/github/getting-started-with-github/githubs-products)" in the GitHub Help documentation.'
      tags:
      - External
      operationId: updateTheConnectionBetweenAnExternalGroupAndTeam
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/teams/external-groups#update-the-connection-between-an-external-group-and-a-team
      parameters:
      - $ref: '#/components/parameters/org'
      - $ref: '#/components/parameters/team-slug'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                group_id:
                  type: integer
                  description: External Group Id
                  example: 1
              required:
              - group_id
            examples:
              default:
                value:
                  group_id: 123
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/external-group'
              examples:
                default:
                  $ref: '#/components/examples/external-group'
      x-github:
        githubCloudOnly: true
        enabledForGitHubApps: false
        category: teams
        subcategory: external-groups
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      summary: GitHub Remove the Connection Between an External Group and Team
      description: '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](https://docs.github.com/enterprise-server@3.9/github/getting-started-with-github/githubs-products) in the GitHub Help documentation.'
      tags:
      - External
      operationId: removeTheConnectionBetweenAnExternalGroupAndTeam
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/teams/external-groups#remove-the-connection-between-an-external-group-and-a-team
      parameters:
      - $ref: '#/components/parameters/org'
      - $ref: '#/components/parameters/team-slug'
      responses:
        '204':
          description: Response
      x-github:
        githubCloudOnly: true
        enabledForGitHubApps: false
        category: teams
        subcategory: external-groups
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    servers:
    - url: '{protocol}://{hostname}/api/v3'
      variables:
        hostname:
          description: Self-hosted Enterprise Server hostname
          default: HOSTNAME
        protocol:
          description: Self-hosted Enterprise Server protocol
          default: http
components:
  parameters:
    team-slug:
      name: team_slug
      description: The slug of the team name.
      in: path
      required: true
      schema:
        type: string
    per-page:
      name: per_page
      description: The number of results per page (max 100). For more information, see "[Using pagination in the REST API](https://docs.github.com/enterprise-server@3.9/rest/using-the-rest-api/using-pagination-in-the-rest-api)."
      in: query
      schema:
        type: integer
        default: 30
    group-id:
      name: group_id
      description: The unique identifier of the group.
      in: path
      required: true
      schema:
        type: integer
    org:
      name: org
      description: The organization name. The name is not case sensitive.
      in: path
      required: true
      schema:
        type: string
  schemas:
    external-groups:
      title: ExternalGroups
      description: A list of external groups available to be connected to a team
      type: object
      properties:
        groups:
          description: An array of external groups available to be mapped to a team
          example:
          - group_id: 1
            group_name: group-azuread-test
            updated_at: 2021-01-03 22:27:15:000 -700
          - group_id: 2
            group_name: group-azuread-test2
            updated_at: 2021-06-03 22:27:15:000 -700
          type: array
          items:
            type: object
            required:
            - group_id
            - group_name
            - updated_at
            properties:
              group_id:
                description: The internal ID of the group
                example: 1
                type: integer
              group_name:
                description: The display name of the group
                example: group-azuread-test
                type: string
              updated_at:
                description: The time of the last update for this group
                example: 2019-06-03 22:27:15:000 -700
                type: string
    external-group:
      title: ExternalGroup
      description: Information about an external group's usage and its members
      type: object
      required:
      - group_id
      - group_name
      - teams
      - members
      properties:
        group_id:
          description: The internal ID of the group
          example: 1
          type: integer
        group_name:
          description: The display name for the group
          example: group-azuread-test
          type: string
        updated_at:
          description: The date when the group was last updated_at
          example: 2021-01-03 22:27:15:000 -700
          type: string
        teams:
          description: An array of teams linked to this group
          example:
          - team_id: 1
            team_name: team-test
          - team_id: 2
            team_name: team-test2
          type: array
          items:
            type: object
            required:
            - team_id
            - team_name
            properties:
              team_id:
                description: The id for a team
                example: 1
                type: integer
              team_name:
                description: The name of the team
                example: team-test
                type: string
        members:
          description: An array of external members linked to this group
          example:
          - 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
          type: array
          items:
            type: object
            required:
            - member_id
            - member_login
            - member_name
            - member_email
            properties:
              member_id:
                description: The internal user ID of the identity
                example: 1
                type: integer
              member_login:
                description: The handle/login for the user
                example: mona-lisa_eocsaxrs
                type: string
              member_name:
                description: The user display name/profile name
                example: Mona Lisa
                type: string
              member_email:
                description: An email attached to a user
                example: mona_lisa@github.com
                type: string
  examples:
    external-group:
      value:
        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
    external-groups:
      value:
        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'
  securitySchemes:
    bearerHttpAuthentication:
      description: Bearer Token
      type: http
      scheme: Bearer
externalDocs:
  description: GitHub Enterprise Developer Docs
  url: https://docs.github.com/enterprise-server@3.9/rest/
x-refined-from:
- github-organizations-openapi.yml
- github-teams-openapi.yml