GitHub OAuth API

openapi: 3.2.0
info:
  version: 1.1.4
  title: GitHub Auth OAuth API
  description: You can authenticate to the REST API to access more endpoints and have a higher rate limit. Many REST API endpoints require authentication or return additional information if you are authenticated. Additionally, you can make more requests per hour when you are authenticated.
  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: api.github.com
    protocol:
      description: Self-hosted Enterprise Server protocol
      default: https
tags:
- name: OAuth
paths:
  /admin/users/{username}/authorizations:
    post:
      summary: GitHub Create an Impersonation Oauth Token
      description: This API endpoint allows administrators to create an OAuth impersonation token for a specific GitHub user by making a POST request to /admin/users/{username}/authorizations. The operation enables authorized administrators to generate access tokens on behalf of other users, which can be useful for troubleshooting, performing administrative tasks, or assisting users with account-related issues. The endpoint requires admin privileges and accepts the target username as a path parameter, along with optional scopes in the request body to define the permissions granted to the impersonation token. Upon successful execution, it returns an OAuth token that can be used to authenticate API requests as if made by the specified user, though the token should be handled with extreme care due to its elevated access capabilities.
      operationId: createAnImpersonationOauthToken
      tags:
      - OAuth
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/users#create-an-impersonation-oauth-token
      parameters:
      - $ref: '#/components/parameters/username'
      responses:
        '200':
          description: Response when getting an existing impersonation OAuth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/authorization'
              examples:
                default:
                  $ref: '#/components/examples/authorization'
        '201':
          description: Response when creating a new impersonation OAuth token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/authorization'
              examples:
                default:
                  $ref: '#/components/examples/authorization'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                scopes:
                  type: array
                  description: A list of [scopes](https://docs.github.com/enterprise-server@3.9/apps/building-oauth-apps/understanding-scopes-for-oauth-apps/).
                  items:
                    type: string
              required:
              - scopes
            examples:
              default:
                value:
                  scopes:
                  - public_repo
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: enterprise-admin
        subcategory: users
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      summary: GitHub Delete an Impersonation Oauth Token
      description: Deletes an impersonation OAuth token for a specified user, allowing administrators to revoke access tokens that were created to impersonate that user. This endpoint requires admin authentication and removes the authorization token associated with the given username, effectively terminating any active sessions or API access using that impersonated token. This is typically used for security purposes or when administrative access to a user's account is no longer needed.
      operationId: deleteAnImpersonationOauthToken
      tags:
      - OAuth
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/enterprise-admin/users#delete-an-impersonation-oauth-token
      parameters:
      - $ref: '#/components/parameters/username'
      responses:
        '204':
          description: Response
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: enterprise-admin
        subcategory: users
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    nullable-simple-user:
      title: Simple User
      description: A GitHub user.
      type:
      - object
      - 'null'
      properties:
        name:
          type:
          - string
          - 'null'
          example: octocat
        email:
          type:
          - string
          - 'null'
          example: octocat@github.com
        login:
          type: string
          example: octocat
        id:
          type: integer
          example: 1
        node_id:
          type: string
          example: MDQ6VXNlcjE=
        avatar_url:
          type: string
          format: uri
          example: https://github.com/images/error/octocat_happy.gif
        gravatar_id:
          type:
          - string
          - 'null'
          example: 41d064eb2195891e12d0413f63227ea7
        url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat
        html_url:
          type: string
          format: uri
          example: https://github.com/octocat
        followers_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/followers
        following_url:
          type: string
          example: https://api.github.com/users/octocat/following{/other_user}
        gists_url:
          type: string
          example: https://api.github.com/users/octocat/gists{/gist_id}
        starred_url:
          type: string
          example: https://api.github.com/users/octocat/starred{/owner}{/repo}
        subscriptions_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/subscriptions
        organizations_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/orgs
        repos_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/repos
        events_url:
          type: string
          example: https://api.github.com/users/octocat/events{/privacy}
        received_events_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/received_events
        type:
          type: string
          example: User
        site_admin:
          type: boolean
          example: true
        starred_at:
          type: string
          example: '"2020-07-09T00:17:55Z"'
      required:
      - avatar_url
      - events_url
      - followers_url
      - following_url
      - gists_url
      - gravatar_id
      - html_url
      - id
      - node_id
      - login
      - organizations_url
      - received_events_url
      - repos_url
      - site_admin
      - starred_url
      - subscriptions_url
      - type
      - url
    app-permissions:
      title: App Permissions
      type: object
      description: The permissions granted to the user access token.
      properties:
        actions:
          type: string
          description: The level of permission to grant the access token for GitHub Actions workflows, workflow runs, and artifacts.
          enum:
          - read
          - write
          example: read
        administration:
          type: string
          description: The level of permission to grant the access token for repository creation, deletion, settings, teams, and collaborators creation.
          enum:
          - read
          - write
          example: read
        checks:
          type: string
          description: The level of permission to grant the access token for checks on code.
          enum:
          - read
          - write
          example: read
        codespaces:
          type: string
          description: The level of permission to grant the access token to create, edit, delete, and list Codespaces.
          enum:
          - read
          - write
          example: read
        contents:
          type: string
          description: The level of permission to grant the access token for repository contents, commits, branches, downloads, releases, and merges.
          enum:
          - read
          - write
          example: read
        dependabot_secrets:
          type: string
          description: The leve of permission to grant the access token to manage Dependabot secrets.
          enum:
          - read
          - write
          example: read
        deployments:
          type: string
          description: The level of permission to grant the access token for deployments and deployment statuses.
          enum:
          - read
          - write
          example: read
        environments:
          type: string
          description: The level of permission to grant the access token for managing repository environments.
          enum:
          - read
          - write
          example: read
        issues:
          type: string
          description: The level of permission to grant the access token for issues and related comments, assignees, labels, and milestones.
          enum:
          - read
          - write
          example: read
        metadata:
          type: string
          description: The level of permission to grant the access token to search repositories, list collaborators, and access repository metadata.
          enum:
          - read
          - write
          example: read
        packages:
          type: string
          description: The level of permission to grant the access token for packages published to GitHub Packages.
          enum:
          - read
          - write
          example: read
        pages:
          type: string
          description: The level of permission to grant the access token to retrieve Pages statuses, configuration, and builds, as well as create new builds.
          enum:
          - read
          - write
          example: read
        pull_requests:
          type: string
          description: The level of permission to grant the access token for pull requests and related comments, assignees, labels, milestones, and merges.
          enum:
          - read
          - write
          example: read
        repository_hooks:
          type: string
          description: The level of permission to grant the access token to manage the post-receive hooks for a repository.
          enum:
          - read
          - write
          example: read
        repository_projects:
          type: string
          description: The level of permission to grant the access token to manage repository projects, columns, and cards.
          enum:
          - read
          - write
          - admin
          example: read
        secret_scanning_alerts:
          type: string
          description: The level of permission to grant the access token to view and manage secret scanning alerts.
          enum:
          - read
          - write
          example: read
        secrets:
          type: string
          description: The level of permission to grant the access token to manage repository secrets.
          enum:
          - read
          - write
          example: read
        security_events:
          type: string
          description: The level of permission to grant the access token to view and manage security events like code scanning alerts.
          enum:
          - read
          - write
          example: read
        single_file:
          type: string
          description: The level of permission to grant the access token to manage just a single file.
          enum:
          - read
          - write
          example: read
        statuses:
          type: string
          description: The level of permission to grant the access token for commit statuses.
          enum:
          - read
          - write
          example: read
        vulnerability_alerts:
          type: string
          description: The level of permission to grant the access token to manage Dependabot alerts.
          enum:
          - read
          - write
        workflows:
          type: string
          description: The level of permission to grant the access token to update GitHub Actions workflow files.
          enum:
          - write
        members:
          type: string
          description: The level of permission to grant the access token for organization teams and members.
          enum:
          - read
          - write
        organization_administration:
          type: string
          description: The level of permission to grant the access token to manage access to an organization.
          enum:
          - read
          - write
        organization_custom_roles:
          type: string
          description: The level of permission to grant the access token for custom repository roles management.
          enum:
          - read
          - write
        organization_copilot_seat_management:
          type: string
          description: The level of permission to grant the access token for managing access to GitHub Copilot for members of an organization with a Copilot Business subscription. This property is in beta and is subject to change.
          enum:
          - write
        organization_announcement_banners:
          type: string
          description: The level of permission to grant the access token to view and manage announcement banners for an organization.
          enum:
          - read
          - write
        organization_events:
          type: string
          description: The level of permission to grant the access token to view events triggered by an activity in an organization.
          enum:
          - read
        organization_hooks:
          type: string
          description: The level of permission to grant the access token to manage the post-receive hooks for an organization.
          enum:
          - read
          - write
        organization_personal_access_tokens:
          type: string
          description: The level of permission to grant the access token for viewing and managing fine-grained personal access token requests to an organization.
          enum:
          - read
          - write
        organization_personal_access_token_requests:
          type: string
          description: The level of permission to grant the access token for viewing and managing fine-grained personal access tokens that have been approved by an organization.
          enum:
          - read
          - write
        organization_plan:
          type: string
          description: The level of permission to grant the access token for viewing an organization's plan.
          enum:
          - read
        organization_projects:
          type: string
          description: The level of permission to grant the access token to manage organization projects and projects beta (where available).
          enum:
          - read
          - write
          - admin
        organization_packages:
          type: string
          description: The level of permission to grant the access token for organization packages published to GitHub Packages.
          enum:
          - read
          - write
        organization_secrets:
          type: string
          description: The level of permission to grant the access token to manage organization secrets.
          enum:
          - read
          - write
        organization_self_hosted_runners:
          type: string
          description: The level of permission to grant the access token to view and manage GitHub Actions self-hosted runners available to an organization.
          enum:
          - read
          - write
        organization_user_blocking:
          type: string
          description: The level of permission to grant the access token to view and manage users blocked by the organization.
          enum:
          - read
          - write
        team_discussions:
          type: string
          description: The level of permission to grant the access token to manage team discussions and related comments.
          enum:
          - read
          - write
        email_addresses:
          type: string
          description: The level of permission to grant the access token to manage the email addresses belonging to a user.
          enum:
          - read
          - write
        followers:
          type: string
          description: The level of permission to grant the access token to manage the followers belonging to a user.
          enum:
          - read
          - write
        git_ssh_keys:
          type: string
          description: The level of permission to grant the access token to manage git SSH keys.
          enum:
          - read
          - write
        gpg_keys:
          type: string
          description: The level of permission to grant the access token to view and manage GPG keys belonging to a user.
          enum:
          - read
          - write
        interaction_limits:
          type: string
          description: The level of permission to grant the access token to view and manage interaction limits on a repository.
          enum:
          - read
          - write
        profile:
          type: string
          description: The level of permission to grant the access token to manage the profile settings belonging to a user.
          enum:
          - write
        starring:
          type: string
          description: The level of permission to grant the access token to list and manage repositories a user is starring.
          enum:
          - read
          - write
      example:
        contents: read
        issues: read
        deployments: write
        single_file: read
    authorization:
      title: Authorization
      description: The authorization for an OAuth app, GitHub App, or a Personal Access Token.
      type: object
      properties:
        id:
          type: integer
          example: 42
        url:
          type: string
          format: uri
          example: https://api.github.com/repos/octocat/Hello-World
        scopes:
          description: A list of scopes that this authorization is in.
          type:
          - array
          - 'null'
          items:
            type: string
        token:
          type: string
          example: example_value
        token_last_eight:
          type:
          - string
          - 'null'
          example: example_value
        hashed_token:
          type:
          - string
          - 'null'
          example: example_value
        app:
          type: object
          properties:
            client_id:
              type: string
            name:
              type: string
            url:
              type: string
              format: uri
          required:
          - client_id
          - name
          - url
        note:
          type:
          - string
          - 'null'
          example: example_value
        note_url:
          type:
          - string
          - 'null'
          format: uri
          example: https://api.github.com/repos/octocat/Hello-World
        updated_at:
          type: string
          format: date-time
          example: '2026-04-17T12:00:00Z'
        created_at:
          type: string
          format: date-time
          example: '2026-04-17T12:00:00Z'
        fingerprint:
          type:
          - string
          - 'null'
          example: example_value
        user:
          $ref: '#/components/schemas/nullable-simple-user'
        installation:
          $ref: '#/components/schemas/nullable-scoped-installation'
        expires_at:
          type:
          - string
          - 'null'
          format: date-time
          example: '2026-04-17T12:00:00Z'
      required:
      - app
      - id
      - note
      - note_url
      - scopes
      - token
      - hashed_token
      - token_last_eight
      - fingerprint
      - url
      - created_at
      - updated_at
      - expires_at
    simple-user:
      title: Simple User
      description: A GitHub user.
      type: object
      properties:
        name:
          type:
          - string
          - 'null'
          example: octocat
        email:
          type:
          - string
          - 'null'
          example: octocat@github.com
        login:
          type: string
          example: octocat
        id:
          type: integer
          example: 1
        node_id:
          type: string
          example: MDQ6VXNlcjE=
        avatar_url:
          type: string
          format: uri
          example: https://github.com/images/error/octocat_happy.gif
        gravatar_id:
          type:
          - string
          - 'null'
          example: 41d064eb2195891e12d0413f63227ea7
        url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat
        html_url:
          type: string
          format: uri
          example: https://github.com/octocat
        followers_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/followers
        following_url:
          type: string
          example: https://api.github.com/users/octocat/following{/other_user}
        gists_url:
          type: string
          example: https://api.github.com/users/octocat/gists{/gist_id}
        starred_url:
          type: string
          example: https://api.github.com/users/octocat/starred{/owner}{/repo}
        subscriptions_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/subscriptions
        organizations_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/orgs
        repos_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/repos
        events_url:
          type: string
          example: https://api.github.com/users/octocat/events{/privacy}
        received_events_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/received_events
        type:
          type: string
          example: User
        site_admin:
          type: boolean
          example: true
        starred_at:
          type: string
          example: '"2020-07-09T00:17:55Z"'
      required:
      - avatar_url
      - events_url
      - followers_url
      - following_url
      - gists_url
      - gravatar_id
      - html_url
      - id
      - node_id
      - login
      - organizations_url
      - received_events_url
      - repos_url
      - site_admin
      - starred_url
      - subscriptions_url
      - type
      - url
    nullable-scoped-installation:
      title: Scoped Installation
      type:
      - object
      - 'null'
      properties:
        permissions:
          $ref: '#/components/schemas/app-permissions'
        repository_selection:
          description: Describe whether all repositories have been selected or there's a selection involved
          type: string
          enum:
          - all
          - selected
          example: all
        single_file_name:
          type:
          - string
          - 'null'
          example: config.yaml
        has_multiple_single_files:
          type: boolean
          example: true
        single_file_paths:
          type: array
          items:
            type: string
          example:
          - config.yml
          - .github/issue_TEMPLATE.md
        repositories_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/repos
        account:
          $ref: '#/components/schemas/simple-user'
      required:
      - permissions
      - repository_selection
      - single_file_name
      - repositories_url
      - account
  examples:
    authorization:
      value:
        id: 1
        url: https://api.github.com/authorizations/1
        scopes:
        - public_repo
        token: REDACTED_GITHUB_TOKEN
        token_last_eight: Ae178B4a
        hashed_token: 25f94a2a5c7fbaf499c665bc73d67c1c87e496da8985131633ee0a95819db2e8
        app:
          url: http://my-github-app.com
          name: my github app
          client_id: abcde12345fghij67890
        note: optional note
        note_url: http://optional/note/url
        updated_at: '2011-09-06T20:39:23Z'
        created_at: '2011-09-06T17:26:27Z'
        expires_at: '2011-10-06T17:26:27Z'
        fingerprint: jklmnop12345678
  parameters:
    username:
      name: username
      description: The handle for the GitHub user account.
      in: path
      required: true
      schema:
        type: string
  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/