GitHub Enterprise-Admin - Scim API

openapi: 3.2.0
info:
  version: 1.1.4
  title: GitHub v3 REST Enterprise-Admin - Scim API
  description: GitHub's v3 REST API.
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  termsOfService: https://docs.github.com/articles/github-terms-of-service
  contact:
    name: Support
    url: https://support.github.com/contact?tags=dotcom-rest-api
  x-github-plan: ghes
  x-github-release: 3.9
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: Enterprise-Admin - Scim
paths:
  /scim/v2/Groups:
    get:
      summary: GitHub List Provisioned SCIM Groups for an Enterprise
      description: '**Note:** The SCIM API endpoints for enterprise accounts are currently in *private* beta and are subject to change.


        Lists provisioned SCIM groups in an enterprise.


        You can improve query search time by using the `excludedAttributes` query parameter with a value of `members` to exclude members from the response.'
      operationId: enterprise-admin/list-provisioned-groups-enterprise
      tags:
      - Enterprise-Admin - Scim
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/scim#list-provisioned-scim-groups-for-an-enterprise
      parameters:
      - name: filter
        description: If specified, only results that match the specified filter will be returned. Multiple filters are not supported. Possible filters are `externalId`, `id`, and `displayName`. For example, `?filter="externalId eq '9138790-10932-109120392-12321'"`.
        in: query
        required: false
        schema:
          type: string
        examples:
          displayName:
            value: Engineering
          externalId:
            value: 8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159
        example: example_value
      - $ref: '#/components/parameters/excluded-attributes'
      - $ref: '#/components/parameters/start-index'
      - $ref: '#/components/parameters/count'
      responses:
        '200':
          description: Success, either groups were found or not found
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/scim-enterprise-group-list'
              examples:
                default:
                  $ref: '#/components/examples/scim-enterprise-group-list'
        '400':
          $ref: '#/components/responses/scim_bad_request'
        '401':
          $ref: '#/components/responses/authorization_failure'
        '403':
          $ref: '#/components/responses/permission_denied'
        '429':
          $ref: '#/components/responses/scim_too_many_requests'
        '500':
          $ref: '#/components/responses/scim_internal_error'
      x-github:
        enabledForGitHubApps: true
        githubCloudOnly: true
        category: enterprise-admin
        subcategory: scim
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    scim-error:
      title: Scim Error
      description: Scim Error
      type: object
      properties:
        message:
          type:
          - string
          - 'null'
          example: Example body text
        documentation_url:
          type:
          - string
          - 'null'
          example: https://api.github.com/repos/octocat/Hello-World
        detail:
          type:
          - string
          - 'null'
          example: example_value
        status:
          type: integer
          example: 42
        scimType:
          type:
          - string
          - 'null'
          example: User
        schemas:
          type: array
          items:
            type: string
    scim-enterprise-group-list:
      type: object
      required:
      - schemas
      - totalResults
      - Resources
      - startIndex
      - itemsPerPage
      properties:
        schemas:
          type: array
          description: The URIs that are used to indicate the namespaces of the list SCIM schemas.
          items:
            type: string
            enum:
            - urn:ietf:params:scim:api:messages:2.0:ListResponse
          example:
          - urn:ietf:params:scim:api:messages:2.0:ListResponse
        totalResults:
          type: integer
          description: Number of results found
          example: 1
        Resources:
          type: array
          description: Information about each provisioned group.
          items:
            $ref: '#/components/schemas/scim-enterprise-group-response'
        startIndex:
          type: integer
          description: A starting index for the returned page
          example: 1
        itemsPerPage:
          type: integer
          description: Number of objects per page
          example: 20
    scim-enterprise-group-response:
      allOf:
      - $ref: '#/components/schemas/group-response'
      - type: object
        properties:
          id:
            type: string
            description: The internally generated id for the group object.
            example: 7fce0092-d52e-4f76-b727-3955bd72c939
          members:
            type: array
            items:
              type: object
              properties:
                value:
                  type: string
                $ref:
                  type: string
                display:
                  type: string
            description: The security group members.
            example:
            - value: 879db59-3bdf-4490-ad68-ab880a2694745
              $+ref: https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745
              displayName: User 1
            - value: 0db508eb-91e2-46e4-809c-30dcbda0c685
              $+ref: https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685
              displayName: User 2
          meta:
            $ref: '#/components/schemas/meta'
    group-response:
      type: object
      required:
      - schemas
      properties:
        schemas:
          type: array
          description: The URIs that are used to indicate the namespaces of the SCIM schemas.
          items:
            type: string
            enum:
            - urn:ietf:params:scim:schemas:core:2.0:Group
            - urn:ietf:params:scim:api:messages:2.0:ListResponse
          example:
          - urn:ietf:params:scim:schemas:core:2.0:Group
        externalId:
          type:
          - string
          - 'null'
          description: A unique identifier for the resource as defined by the provisioning client.
          example: 8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159
        displayName:
          type:
          - string
          - 'null'
          description: A human-readable name for a security group.
          example: Engineering
        members:
          type: array
          description: The group members.
          items:
            type: object
            required:
            - value
            - $ref
            properties:
              value:
                type: string
                description: The local unique identifier for the member
                example: 23a35c27-23d3-4c03-b4c5-6443c09e7173
              $ref:
                type: string
              display:
                type: string
                description: The display name associated with the member
                example: Monalisa Octocat
    meta:
      type: object
      description: The metadata associated with the creation/updates to the user.
      required:
      - resourceType
      properties:
        resourceType:
          type: string
          description: A type of a resource
          enum:
          - User
          - Group
          example: User
        created:
          type: string
          description: A date and time when the user was created.
          example: '2022-03-27T19:59:26.000Z'
        lastModified:
          type: string
          description: A data and time when the user was last modified.
          example: '2022-03-27T19:59:26.000Z'
        location:
          type: string
          description: A URL location of an object
          example: example_value
  responses:
    scim_bad_request:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/scim-error'
        application/scim+json:
          schema:
            $ref: '#/components/schemas/scim-error'
    permission_denied:
      description: Permission denied
    scim_internal_error:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/scim-error'
        application/scim+json:
          schema:
            $ref: '#/components/schemas/scim-error'
    authorization_failure:
      description: Authorization failure
    scim_too_many_requests:
      description: Too many requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/scim-error'
        application/scim+json:
          schema:
            $ref: '#/components/schemas/scim-error'
  parameters:
    start-index:
      name: startIndex
      description: 'Used for pagination: the starting index of the first result to return when paginating through values.'
      in: query
      required: false
      schema:
        type: integer
        default: 1
        format: int32
        example: 1
    count:
      name: count
      description: 'Used for pagination: the number of results to return per page.'
      in: query
      required: false
      schema:
        type: integer
        default: 30
        format: int32
        example: 1
    excluded-attributes:
      name: excludedAttributes
      description: Excludes the specified attribute from being returned in the results. Using this parameter can speed up response time.
      in: query
      required: false
      schema:
        type: string
        example: members
  examples:
    scim-enterprise-group-list:
      value:
        schemas:
        - urn:ietf:params:scim:api:messages:2.0:ListResponse
        totalResults: 1
        Resources:
        - schemas:
          - urn:ietf:params:scim:schemas:core:2.0:Group
          externalId: 8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159
          id: 927fa2c08dcb4a7fae9e
          displayName: Engineering
          members:
          - value: 879db59-3bdf-4490-ad68-ab880a2694745
            $+ref: https://api.github.localhost/scim/v2/Users/879db59-3bdf-4490-ad68-ab880a2694745
            displayName: User 1
          - value: 0db508eb-91e2-46e4-809c-30dcbda0c685
            $+ref: https://api.github.localhost/scim/v2/Users/0db508eb-91e2-46e4-809c-30dcbda0c685
            displayName: User 2
          meta:
            resourceType: Group
            created: '2012-03-27T19:59:26.000Z'
            lastModified: '2018-03-27T19:59:26.000Z'
            location: https://api.github.localhost/scim/v2/Groups/927fa2c08dcb4a7fae9e
        startIndex: 1
        itemsPerPage: 20
externalDocs:
  description: GitHub Enterprise Developer Docs
  url: https://docs.github.com/enterprise-server@3.9/rest/