openapi: 3.0.3
info:
version: 1.1.4
title: GitHub Application About Access 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: Access
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:
- Access
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/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:
- Access
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
/repos/{owner}/{repo}/branches/{branch}/protection/restrictions/apps:
get:
summary: GitHub Get Apps with Access to the Protected Branch
description: 'Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. 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.
Lists the GitHub Apps that have push access to this branch. Only GitHub Apps that are installed on the repository and that have been granted write access to the repository contents can be added as authorized actors on a protected branch.'
tags:
- Access
operationId: getAppsWithAccessToTheProtectedBranch
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/branches/branch-protection#get-apps-with-access-to-the-protected-branch
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/integration'
examples:
default:
$ref: '#/components/examples/integration-items'
'404':
$ref: '#/components/responses/not_found'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: GitHub Add App Access Restrictions
description: 'Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. 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.
Grants the specified apps push access for this branch. Only GitHub Apps that are installed on the repository and that have been granted write access to the repository contents can be added as authorized actors on a protected branch.'
tags:
- Access
operationId: addAppAccessRestrictions
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/branches/branch-protection#add-app-access-restrictions
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
requestBody:
required: false
content:
application/json:
schema:
oneOf:
- type: object
properties:
apps:
type: array
description: 'The GitHub Apps that have push access to this branch. Use the slugified version of the app name. **Note**: The list of users, apps, and teams in total is limited to 100 items.'
items:
type: string
required:
- apps
example:
apps:
- my-app
- type: array
items:
type: string
examples:
default:
value:
apps:
- octoapp
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/integration'
examples:
default:
$ref: '#/components/examples/integration-items'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
requestBodyParameterName: apps
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
summary: GitHub Set App Access Restrictions
description: 'Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. 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.
Replaces the list of apps that have push access to this branch. This removes all apps that previously had push access and grants push access to the new list of apps. Only GitHub Apps that are installed on the repository and that have been granted write access to the repository contents can be added as authorized actors on a protected branch.'
tags:
- Access
operationId: setAppAccessRestrictions
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/branches/branch-protection#set-app-access-restrictions
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
requestBody:
required: false
content:
application/json:
schema:
oneOf:
- type: object
properties:
apps:
type: array
description: 'The GitHub Apps that have push access to this branch. Use the slugified version of the app name. **Note**: The list of users, apps, and teams in total is limited to 100 items.'
items:
type: string
required:
- apps
example:
apps:
- my-app
- type: array
items:
type: string
examples:
default:
value:
apps:
- octoapp
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/integration'
examples:
default:
$ref: '#/components/examples/integration-items'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
requestBodyParameterName: apps
category: branches
subcategory: branch-protection
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Remove App Access Restrictions
description: 'Protected branches are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud, and GitHub Enterprise Server. 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.
Removes the ability of an app to push to this branch. Only GitHub Apps that are installed on the repository and that have been granted write access to the repository contents can be added as authorized actors on a protected branch.'
tags:
- Access
operationId: removeAppAccessRestrictions
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/branches/branch-protection#remove-app-access-restrictions
parameters:
- $ref: '#/components/parameters/owner'
- $ref: '#/components/parameters/repo'
- $ref: '#/components/parameters/branch'
requestBody:
content:
application/json:
schema:
oneOf:
- type: object
properties:
apps:
type: array
description: 'The GitHub Apps that have push access to this branch. Use the slugified version of the app name. **Note**: The list of users, apps, and teams in total is limited to 100 items.'
items:
type: string
required:
- apps
example:
apps:
- my-app
- type: array
items:
type: string
examples:
default:
value:
apps:
- my-app
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/integration'
examples:
default:
$ref: '#/components/examples/integration-items'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: true
requestBodyParameterName: apps
category: branches
subcategory: branch-protection
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:
- Access
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:
- Access
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:
- Access
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/runner-groups/{runner_group_id}/repositories:
get:
summary: GitHub List Repository Access to Self-hosted Runner Group in an Organization
description: 'Lists the repositories with access to a self-hosted runner group configured in an organization.
OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.'
operationId: listRepositoryAccessToSelfhostedRunnerGroupInAnOrganization
tags:
- Access
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/actions/self-hosted-runner-groups#list-repository-access-to-a-self-hosted-runner-group-in-an-organization
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/runner-group-id'
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/per-page'
responses:
'200':
description: Response
content:
application/json:
schema:
type: object
required:
- total_count
- repositories
properties:
total_count:
type: number
repositories:
type: array
items:
$ref: '#/components/schemas/minimal-repository'
examples:
default:
$ref: '#/components/examples/minimal-repository-paginated'
x-github:
enabledForGitHubApps: true
githubCloudOnly: true
category: actions
subcategory: self-hosted-runner-groups
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
summary: GitHub Set Repository Access for Self-hosted Runner Group in an Organization
description: 'Replaces the list of repositories that have access to a self-hosted runner group configured in an organization.
OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.'
operationId: setRepositoryAccessForSelfhostedRunnerGroupInAnOrganization
tags:
- Access
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/actions/self-hosted-runner-groups#set-repository-access-for-a-self-hosted-runner-group-in-an-organization
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/runner-group-id'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
selected_repository_ids:
description: List of repository IDs that can access the runner group.
type: array
items:
type: integer
description: Unique identifier of the repository.
required:
- selected_repository_ids
examples:
default:
value:
selected_repository_ids:
- 32
- 91
responses:
'204':
description: Response
x-github:
enabledForGitHubApps: true
githubCloudOnly: true
category: actions
subcategory: self-hosted-runner-groups
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/orgs/{org}/actions/runner-groups/{runner_group_id}/repositories/{repository_id}:
put:
summary: GitHub Add Repository Access to Self-hosted Runner Group in an Organization
description: 'Adds a repository to the list of repositories that can access a self-hosted runner group. The runner group must have `visibility` set to `selected`. For more information, see "[Create a self-hosted runner group for an organization](#create-a-self-hosted-runner-group-for-an-organization)."
OAuth tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.'
operationId: addRepositoryAccessToSelfhostedRunnerGroupInAnOrganization
tags:
- Access
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/actions/self-hosted-runner-groups#add-repository-access-to-a-self-hosted-runner-group-in-an-organization
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/runner-group-id'
- $ref: '#/components/parameters/repository-id'
responses:
'204':
description: Response
x-github:
enabledForGitHubApps: true
githubCloudOnly: true
category: actions
subcategory: self-hosted-runner-groups
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: GitHub Remove Repository Access to Self-hosted Runner Group in an Organization
description: 'Removes a repository from the list of selected repositories that can access a self-hosted runner group. The runner group must have `visibility` set to `selected`. For more information, see "[Create a self-hosted runner group for an organization](#create-a-self-hosted-runner-group-for-an-organization)."
OAuth app tokens and personal access tokens (classic) need the `admin:org` scope to use this endpoint.'
operationId: removeRepositoryAccessToSelfhostedRunnerGroupInAnOrganization
tags:
- Access
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/actions/self-hosted-runner-groups#remove-repository-access-to-a-self-hosted-runner-group-in-an-organization
parameters:
- $ref: '#/components/parameters/org'
- $ref: '#/components/parameters/runner-group-id'
- $ref: '#/components/parameters/repository-id'
responses:
'204':
description: Response
x-github:
enabledForGitHubApps: true
githubCloudOnly: true
category: actions
subcategory: self-hosted-runner-groups
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/repos/{owner}/{repo}/actions/permissions/access:
get:
summary: GitHub Get the Level of Access for Workflows Outside of the Repository
description: 'Gets the level of access that workflows outside of the repository have to actions and reusable workflows in the repository.
This endpoint only applies to internal and private repositories.
For more information, see "[Allowing access to components in a private repository](https://docs.github.com/enterprise-server@3.9/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-a-private-repository)" and
"[Allowing access to components in an internal repository](https://docs.github.com/enterprise-server@3.9/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-access-to-components-in-an
# --- truncated at 32 KB (780 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-access-api-openapi.yml