GitHub Tokens API

openapi: 3.0.3
info:
  version: 1.1.4
  title: GitHub Application About Tokens API
  description: 'Use the REST API to retrieve information about GitHub Apps and GitHub App

    installations.'
  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: Tokens
paths:
  /app/installations/{installation_id}/access_tokens:
    post:
      summary: GitHub Create an Installation Access Token for an App
      description: "Creates an installation access token that enables a GitHub App to make authenticated API requests for the app's installation on an organization or individual account. Installation tokens expire one hour from the time you create them. Using an expired token produces a status code of `401 - Unauthorized`, and requires creating a new installation token. By default the installation token has access to all repositories that the installation can access. \n\nOptionally, you can use the `repositories` or `repository_ids` body parameters to specify individual repositories that the installation access token can access. If you don't use `repositories` or `repository_ids` to grant access to specific repositories, the installation access token will have access to all repositories that the installation was granted access to. The installation access token cannot be granted access to repositories that the installation was not granted access to. Up to 500 repositories can be listed in this manner.\n\nOptionally, use the `permissions` body parameter to specify the permissions that the installation access token should have. If `permissions` is not specified, the installation access token will have all of the permissions that were granted to the app. The installation access token cannot be granted permissions that the app was not granted.\n\nWhen using the repository or permission parameters to reduce the access of the token, the complexity of the token is increased due to both the number of permissions in the request and the number of repositories the token will have access to. If the complexity is too large, the token will fail to be issued. If this occurs, the error message will indicate the maximum number of repositories that should be requested. For the average application requesting 8 permissions, this limit is around 5000 repositories. With fewer permissions requested, more repositories are supported. \n\nYou must use a [JWT](https://docs.github.com/enterprise-server@3.9/apps/building-github-apps/authenticating-with-github-apps/#authenticating-as-a-github-app) to access this endpoint."
      tags:
      - Tokens
      operationId: createAnInstallationAccessTokenForAnApp
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/apps/apps#create-an-installation-access-token-for-an-app
      parameters:
      - $ref: '#/components/parameters/installation-id'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                repositories:
                  description: List of repository names that the token should have access to
                  type: array
                  items:
                    type: string
                    example: rails
                repository_ids:
                  description: List of repository IDs that the token should have access to
                  example:
                  - 1
                  type: array
                  items:
                    type: integer
                permissions:
                  $ref: '#/components/schemas/app-permissions'
            examples:
              default:
                value:
                  repositories:
                  - Hello-World
                  permissions:
                    issues: write
                    contents: read
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/installation-token'
              examples:
                default:
                  $ref: '#/components/examples/installation-token'
        '401':
          $ref: '#/components/responses/requires_authentication'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '422':
          $ref: '#/components/responses/validation_failed'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: apps
        subcategory: apps
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /applications/{client_id}/token:
    post:
      summary: GitHub Checktoken
      description: OAuth applications and GitHub applications with OAuth authorizations can use this API method for checking OAuth token validity without exceeding the normal rate limits for failed login attempts. Authentication works differently with this particular endpoint. You must use [Basic Authentication](https://docs.github.com/enterprise-server@3.9/rest/overview/other-authentication-methods#basic-authentication) to use this endpoint, where the username is the application `client_id` and the password is its `client_secret`. Invalid tokens will return `404 NOT FOUND`.
      tags:
      - Tokens
      operationId: checktoken
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/apps/oauth-applications#check-a-token
      parameters:
      - $ref: '#/components/parameters/client-id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                access_token:
                  description: The access_token of the OAuth or GitHub application.
                  type: string
              required:
              - access_token
              type: object
            examples:
              default:
                value:
                  access_token: e72e16c7e42f292c6912e7710c838347ae178b4a
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/authorization'
              examples:
                default:
                  $ref: '#/components/examples/authorization-with-user'
        '404':
          $ref: '#/components/responses/not_found'
        '422':
          $ref: '#/components/responses/validation_failed'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: apps
        subcategory: oauth-applications
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      summary: GitHub Reset Token
      description: OAuth applications and GitHub applications with OAuth authorizations can use this API method to reset a valid OAuth token without end-user involvement. Applications must save the "token" property in the response because changes take effect immediately. You must use [Basic Authentication](https://docs.github.com/enterprise-server@3.9/rest/overview/other-authentication-methods#basic-authentication) when accessing this endpoint, using the application's `client_id` and `client_secret` as the username and password. Invalid tokens will return `404 NOT FOUND`.
      tags:
      - Tokens
      operationId: resetToken
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/apps/oauth-applications#reset-a-token
      parameters:
      - $ref: '#/components/parameters/client-id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                access_token:
                  description: The access_token of the OAuth or GitHub application.
                  type: string
              required:
              - access_token
              type: object
            examples:
              default:
                value:
                  access_token: e72e16c7e42f292c6912e7710c838347ae178b4a
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/authorization'
              examples:
                default:
                  $ref: '#/components/examples/authorization-with-user'
        '422':
          $ref: '#/components/responses/validation_failed'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: apps
        subcategory: oauth-applications
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      summary: GitHub Delete an App Token
      description: OAuth  or GitHub application owners can revoke a single token for an OAuth application or a GitHub application with an OAuth authorization. You must use [Basic Authentication](https://docs.github.com/enterprise-server@3.9/rest/overview/other-authentication-methods#basic-authentication) when accessing this endpoint, using the application's `client_id` and `client_secret` as the username and password.
      tags:
      - Tokens
      operationId: deleteAnAppToken
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/apps/oauth-applications#delete-an-app-token
      parameters:
      - $ref: '#/components/parameters/client-id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                access_token:
                  type: string
                  description: The OAuth access token used to authenticate to the GitHub API.
              required:
              - access_token
            examples:
              default:
                value:
                  access_token: e72e16c7e42f292c6912e7710c838347ae178b4a
      responses:
        '204':
          description: Response
        '422':
          $ref: '#/components/responses/validation_failed'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: apps
        subcategory: oauth-applications
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /applications/{client_id}/token/scoped:
    post:
      summary: GitHub Createscoped Access Token
      description: 'Use a non-scoped user access token to create a repository-scoped and/or permission-scoped user access token. You can specify

        which repositories the token can access and which permissions are granted to the

        token.


        Invalid tokens will return `404 NOT FOUND`.


        You must use [Basic Authentication](https://docs.github.com/enterprise-server@3.9/rest/overview/other-authentication-methods#basic-authentication)

        when accessing this endpoint, using the `client_id` and `client_secret` of the GitHub App

        as the username and password.'
      tags:
      - Tokens
      operationId: createscopedAccessToken
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/apps/apps#create-a-scoped-access-token
      parameters:
      - $ref: '#/components/parameters/client-id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                access_token:
                  type: string
                  description: The access token used to authenticate to the GitHub API.
                  example: e72e16c7e42f292c6912e7710c838347ae178b4a
                target:
                  description: The name of the user or organization to scope the user access token to. **Required** unless `target_id` is specified.
                  type: string
                  example: octocat
                target_id:
                  description: The ID of the user or organization to scope the user access token to. **Required** unless `target` is specified.
                  example: 1
                  type: integer
                repositories:
                  description: The list of repository names to scope the user access token to. `repositories` may not be specified if `repository_ids` is specified.
                  type: array
                  items:
                    type: string
                    example: rails
                repository_ids:
                  description: The list of repository IDs to scope the user access token to. `repository_ids` may not be specified if `repositories` is specified.
                  example:
                  - 1
                  type: array
                  items:
                    type: integer
                permissions:
                  $ref: '#/components/schemas/app-permissions'
              required:
              - access_token
            examples:
              default:
                value:
                  access_token: e72e16c7e42f292c6912e7710c838347ae178b4a
                  target: octocat
                  permissions:
                    metadata: read
                    issues: write
                    contents: read
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/authorization'
              examples:
                default:
                  $ref: '#/components/examples/scope-token'
        '401':
          $ref: '#/components/responses/requires_authentication'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
        '422':
          $ref: '#/components/responses/validation_failed'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: apps
        subcategory: apps
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /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:
      - Tokens
      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:
      - Tokens
      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
  /installation/token:
    delete:
      summary: GitHub Revoke an Installation Access Token
      description: 'Revokes the installation token you''re using to authenticate as an installation and access this endpoint.


        Once an installation token is revoked, the token is invalidated and cannot be used. Other endpoints that require the revoked installation token must have a new installation token to work. You can create a new token using the "[Create an installation access token for an app](https://docs.github.com/enterprise-server@3.9/rest/apps/apps#create-an-installation-access-token-for-an-app)" endpoint.'
      tags:
      - Tokens
      operationId: revokeAnInstallationAccessToken
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/apps/installations#revoke-an-installation-access-token
      parameters: []
      responses:
        '204':
          description: Response
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: apps
        subcategory: installations
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /user/installations:
    get:
      summary: GitHub List App Installations Accessible to the User Access Token
      description: 'Lists installations of your GitHub App that the authenticated user has explicit permission (`:read`, `:write`, or `:admin`) to access.


        The authenticated user has explicit permission to access repositories they own, repositories where they are a collaborator, and repositories that they can access through an organization membership.


        You can find the permissions for the installation under the `permissions` key.'
      tags:
      - Tokens
      operationId: listAppInstallationsAccessibleToTheUserAccessToken
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/apps/installations#list-app-installations-accessible-to-the-user-access-token
      parameters:
      - $ref: '#/components/parameters/per-page'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: You can find the permissions for the installation under the `permissions` key.
          content:
            application/json:
              schema:
                type: object
                required:
                - total_count
                - installations
                properties:
                  total_count:
                    type: integer
                  installations:
                    type: array
                    items:
                      $ref: '#/components/schemas/installation'
              examples:
                default:
                  $ref: '#/components/examples/base-installation-for-auth-user-paginated'
          headers:
            Link:
              $ref: '#/components/headers/link'
        '304':
          $ref: '#/components/responses/not_modified'
        '401':
          $ref: '#/components/responses/requires_authentication'
        '403':
          $ref: '#/components/responses/forbidden'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: apps
        subcategory: installations
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /user/installations/{installation_id}/repositories:
    get:
      summary: GitHub List Repositories Accessible to the User Access Token
      description: 'List repositories that the authenticated user has explicit permission (`:read`, `:write`, or `:admin`) to access for an installation.


        The authenticated user has explicit permission to access repositories they own, repositories where they are a collaborator, and repositories that they can access through an organization membership.


        The access the user has to each repository is included in the hash under the `permissions` key.'
      tags:
      - Tokens
      operationId: listRepositoriesAccessibleToTheUserAccessToken
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/apps/installations#list-repositories-accessible-to-the-user-access-token
      parameters:
      - $ref: '#/components/parameters/installation-id'
      - $ref: '#/components/parameters/per-page'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: The access the user has to each repository is included in the hash under the `permissions` key.
          content:
            application/json:
              schema:
                type: object
                required:
                - total_count
                - repositories
                properties:
                  total_count:
                    type: integer
                  repository_selection:
                    type: string
                  repositories:
                    type: array
                    items:
                      $ref: '#/components/schemas/repository'
              examples:
                default:
                  $ref: '#/components/examples/repository-paginated'
          headers:
            Link:
              $ref: '#/components/headers/link'
        '304':
          $ref: '#/components/responses/not_modified'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: false
        category: apps
        subcategory: installations
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orgs/{org}/actions/runners/registration-token:
    post:
      summary: GitHub Create Registration Token for an Organization
      description: 'Returns a token that you can pass to the `config` script. The token expires after one hour.


        For example, you can replace `TOKEN` in the following example with the registration token provided by this endpoint to configure your self-hosted runner:


        ```

        ./config.sh --url https://github.com/octo-org --token TOKEN

        ```


        Authenticated users must have admin access to the organization to use this endpoint.


        OAuth tokens and personal access tokens (classic) need the`admin:org` scope to use this endpoint. If the repository is private, OAuth tokens and personal access tokens (classic) need the `repo` scope to use this endpoint.'
      tags:
      - Tokens
      operationId: createRegistrationTokenForAnOrganization
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/actions/self-hosted-runners#create-a-registration-token-for-an-organization
      parameters:
      - $ref: '#/components/parameters/org'
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/authentication-token'
              examples:
                default:
                  $ref: '#/components/examples/authentication-token'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: actions
        subcategory: self-hosted-runners
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orgs/{org}/actions/runners/remove-token:
    post:
      summary: GitHub Create Remove Token for an Organization
      description: 'Returns a token that you can pass to the `config` script to remove a self-hosted runner from an organization. The token expires after one hour.


        For example, you can replace `TOKEN` in the following example with the registration token provided by this endpoint to remove your self-hosted runner from an organization:


        ```

        ./config.sh remove --token TOKEN

        ```


        Authenticated users must have admin access to the organization to use this endpoint.


        OAuth tokens and personal access tokens (classic) need the`admin:org` scope to use this endpoint. If the repository is private, OAuth tokens and personal access tokens (classic) need the `repo` scope to use this endpoint.'
      tags:
      - Tokens
      operationId: createRemoveTokenForAnOrganization
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/actions/self-hosted-runners#create-a-remove-token-for-an-organization
      parameters:
      - $ref: '#/components/parameters/org'
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/authentication-token'
              examples:
                default:
                  $ref: '#/components/examples/authentication-token-2'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: actions
        subcategory: self-hosted-runners
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/actions/runners/registration-token:
    post:
      summary: GitHub Create Registration Token for Repository
      description: 'Returns a token that you can pass to the `config` script. The token expires after one hour.


        For example, you can replace `TOKEN` in the following example with the registration token provided by this endpoint to configure your self-hosted runner:


        ```

        ./config.sh --url https://github.com/octo-org --token TOKEN

        ```


        Authenticated users must have admin access to the repository to use this endpoint.


        OAuth tokens and personal access tokens (classic) need the `repo` scope to use this endpoint.'
      tags:
      - Tokens
      operationId: createRegistrationTokenForRepository
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/actions/self-hosted-runners#create-a-registration-token-for-a-repository
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - in: header
        name: Authorization
        schema:
          type: string
        example: example_value
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
        example: example_value
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
        example: example_value
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/authentication-token_2'
              examples:
                default:
                  $ref: '#/components/examples/authentication-token'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: actions
        subcategory: self-hosted-runners
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/actions/runners/remove-token:
    post:
      summary: GitHub Create Remove Token for Repository
      description: 'Returns a token that you can pass to the `config` script to remove a self-hosted runner from an repository. The token expires after one hour.


        For example, you can replace `TOKEN` in the following example with the registration token provided by this endpoint to remove your self-hosted runner from an organization:


        ```

        ./config.sh remove --token TOKEN

        ```


        Authenticated users must have admin access to the repository to use this endpoint.


        OAuth tokens and personal access tokens (classic) need the `repo` scope to use this endpoint.'
      tags:
      - Tokens
      operationId: createRemoveTokenForRepository
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/actions/self-hosted-runners#create-a-remove-token-for-a-repository
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - in: header
        name: Authorization
        schema:
          type: string
        example: example_value
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
        example: example_value
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
        example: example_value
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/authentication-token_2'
              examples:
                default:
                  $ref: '#/components/examples/authentication-token-2'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: actions
        subcategory: self-hosted-runners
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:


# --- truncated at 32 KB (720 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-tokens-api-openapi.yml