GitHub Identities API

openapi: 3.2.0
info:
  version: 1.1.4
  title: GitHub SCIM Identities API
  description: The GitHub SCIM (System for Cross-domain Identity Management) API enables automated user provisioning and deprovisioning for GitHub Enterprise Cloud organizations through identity providers like Azure AD, Okta, or OneLogin. This API allows IT administrators to programmatically manage user identities, group memberships, and access permissions by synchronizing user data from their organization's identity management system directly to GitHub. With SCIM, you can automatically create new users when employees join, update user information when it changes in your identity provider, remove access when employees leave, and manage team memberships based on directory groups—streamlining user lifecycle management and ensuring consistent access control across your organization's GitHub resources.
  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: Identities
paths:
  /scim/v2/Users:
    get:
      summary: GitHub List Scim Provisioned Identities 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 enterprise members.


        When a user with a SCIM-provisioned external identity is removed from an enterprise through a `patch` with `active` flag set to `false`, the account''s metadata is preserved to allow the user to re-join the enterprise in the future. However, the user''s account will be suspended and the user will not be able to sign-in. In order to permanently suspend the users account with no ability to re-join the enterprise in the future, use the `delete` request. Users that were not permanently deleted will be visible in the returned results.'
      operationId: listScimProvisionedIdentitiesForAnEnterprise
      tags:
      - Identities
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/scim#list-scim-provisioned-identities-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 `userName`, `externalId`, `id`, and `displayName`. For example, `?filter="externalId eq '9138790-10932-109120392-12321'"`.
        in: query
        required: false
        schema:
          type: string
        examples:
          userName:
            value: userName eq 'E012345'
          externalId:
            value: externalId eq 'E012345'
        example: example_value
      - $ref: '#/components/parameters/start-index'
      - $ref: '#/components/parameters/count'
      responses:
        '200':
          description: Success, either users were found or not found
          content:
            application/scim+json:
              schema:
                $ref: '#/components/schemas/scim-enterprise-user-list'
              examples:
                default:
                  $ref: '#/components/examples/scim-enterprise-user-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
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  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'
    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'
    permission_denied:
      description: Permission denied
    authorization_failure:
      description: Authorization failure
    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'
  schemas:
    user-name-response:
      type: object
      properties:
        formatted:
          type: string
          description: The full name, including all middle names, titles, and suffixes as appropriate, formatted for display.
          example: Ms. Mona Lisa Octocat
        familyName:
          type: string
          description: The family name of the user.
          example: Octocat
        givenName:
          type: string
          description: The given name of the user.
          example: Mona
        middleName:
          type: string
          description: The middle name(s) of the user.
          example: Lisa
    user-emails-response:
      type: array
      description: The emails for the user.
      items:
        type: object
        required:
        - value
        properties:
          value:
            type: string
            description: The email address.
            example: mlisa@example.com
          type:
            type: string
            description: The type of email address.
            example: work
          primary:
            type: boolean
            description: Whether this email address is the primary address.
            example: true
    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
    user-response:
      type: object
      required:
      - schemas
      - active
      - emails
      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:User
          example:
          - urn:ietf:params:scim:schemas:core:2.0:User
        externalId:
          type:
          - string
          - 'null'
          description: A unique identifier for the resource as defined by the provisioning client.
          example: E012345
        active:
          type: boolean
          description: Whether the user active in the IdP.
          example: true
        userName:
          type: string
          description: The username for the user.
          example: E012345
        name:
          $ref: '#/components/schemas/user-name-response'
        displayName:
          type:
          - string
          - 'null'
          description: A human-readable name for the user.
          example: Mona Lisa
        emails:
          $ref: '#/components/schemas/user-emails-response'
        roles:
          $ref: '#/components/schemas/user-role'
    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
    user-role:
      type: array
      description: The roles assigned to the user.
      items:
        type: object
        required:
        - value
        properties:
          display:
            type: string
          type:
            type: string
          value:
            type: string
            description: The role value representing a user role in GitHub.
            enum:
            - user
            - 27d9891d-2c17-4f45-a262-781a0e55c80a
            - guest_collaborator
            - 1ebc4a02-e56c-43a6-92a5-02ee09b90824
            - enterprise_owner
            - 981df190-8801-4618-a08a-d91f6206c954
            - ba4987ab-a1c3-412a-b58c-360fc407cb10
            - billing_manager
            - 0e338b8c-cc7f-498a-928d-ea3470d7e7e3
            - e6be2762-e4ad-4108-b72d-1bbe884a0f91
            example: user
          primary:
            type: boolean
            description: Is the role a primary role for the user.
            example: false
    scim-enterprise-user-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 account.
          items:
            $ref: '#/components/schemas/scim-enterprise-user-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-user-response:
      allOf:
      - $ref: '#/components/schemas/user-response'
      - type: object
        required:
        - id
        - meta
        properties:
          id:
            type: string
            description: The internally generated id for the user object.
            example: 7fce0092-d52e-4f76-b727-3955bd72c939
          groups:
            type: array
            items:
              type: object
              properties:
                value:
                  type: string
                $ref:
                  type: string
                display:
                  type: string
            description: Provisioned SCIM groups that the user is a member of.
          meta:
            $ref: '#/components/schemas/meta'
  examples:
    scim-enterprise-user-list:
      value:
        schemas:
        - urn:ietf:params:scim:api:messages:2.0:ListResponse
        totalResults: 1
        Resources:
        - schemas:
          - urn:ietf:params:scim:schemas:core:2.0:User
          externalId: E012345
          id: 7fce0092-d52e-4f76-b727-3955bd72c939
          active: true
          userName: E012345
          name:
            formatted: Ms. Mona Lisa Octocat
            familyName: Octocat
            givenName: Mona
            middleName: Lisa
          displayName: Mona Lisa
          emails:
          - value: mlisa@example.com
            type: work
            primary: true
          roles:
          - value: User
            primary: false
        startIndex: 1
        itemsPerPage: 20
  parameters:
    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
    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
  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/