openapi: 3.0.3
info:
version: 1.1.4
title: GitHub Application About Create 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: Create
paths:
/app-manifests/{code}/conversions:
post:
summary: GitHub Creategithub App Frommanifest
description: Use this endpoint to complete the handshake necessary when implementing the [GitHub App Manifest flow](https://docs.github.com/enterprise-server@3.9/apps/building-github-apps/creating-github-apps-from-a-manifest/). When you create a GitHub App with the manifest flow, you receive a temporary `code` used to retrieve the GitHub App's `id`, `pem` (private key), and `webhook_secret`.
tags:
- Create
operationId: creategithubAppFrommanifest
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/apps/apps#create-a-github-app-from-a-manifest
parameters:
- name: code
in: path
required: true
schema:
type: string
example: example_value
responses:
'201':
description: Response
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/integration'
- type: object
properties:
client_id:
type: string
client_secret:
type: string
webhook_secret:
type: string
nullable: true
pem:
type: string
required:
- client_id
- client_secret
- webhook_secret
- pem
additionalProperties: true
examples:
default:
$ref: '#/components/examples/integration-from-manifest'
'404':
$ref: '#/components/responses/not_found'
'422':
$ref: '#/components/responses/validation_failed_simple'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
category: apps
subcategory: apps
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/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:
- Create
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:
- Create
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:
- Create
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
/authorizations:
post:
summary: GitHub Createnew Authorization
description: '**Deprecation Notice:** GitHub Enterprise Server will discontinue the [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations), which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our [web application flow](https://docs.github.com/enterprise-server@3.9/developers/apps/authorizing-oauth-apps#web-application-flow). The [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations) will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the [blog post](https://developer.github.com/changes/2020-02-14-deprecating-oauth-auth-endpoint/).
**Warning:** Apps must use the [web application flow](https://docs.github.com/enterprise-server@3.9/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow) to obtain OAuth tokens that work with GitHub Enterprise Server SAML organizations. OAuth tokens created using the Authorizations API will be unable to access GitHub Enterprise Server SAML organizations. For more information, see the [blog post](https://developer.github.com/changes/2019-11-05-deprecated-passwords-and-authorizations-api).
Creates OAuth tokens using [Basic Authentication](https://docs.github.com/enterprise-server@3.9/rest/overview/other-authentication-methods#basic-authentication). If you have two-factor authentication setup, Basic Authentication for this endpoint requires that you use a one-time password (OTP) and your username and password instead of tokens. For more information, see "[Working with two-factor authentication](https://docs.github.com/enterprise-server@3.9/rest/overview/other-authentication-methods#working-with-two-factor-authentication)."
To create tokens for a particular OAuth application using this endpoint, you must authenticate as the user you want to create an authorization for and provide the app''s client ID and secret, found on your OAuth application''s settings page. If your OAuth application intends to create multiple tokens for one user, use `fingerprint` to differentiate between them.
You can also create tokens on GitHub Enterprise Server from the [personal access tokens settings](https://github.com/settings/tokens) page. Read more about these tokens in [the GitHub Help documentation](https://docs.github.com/enterprise-server@3.9/articles/creating-an-access-token-for-command-line-use).
Organizations that enforce SAML SSO require personal access tokens to be allowed. For more information, see "[About identity and access management with SAML single sign-on](https://docs.github.com/enterprise-server@3.9/enterprise-cloud@latest/organizations/managing-saml-single-sign-on-for-your-organization/about-identity-and-access-management-with-saml-single-sign-on)" in the GitHub Enterprise Cloud documentation.'
tags:
- Create
operationId: createnewAuthorization
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations#create-a-new-authorization
parameters: []
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
scopes:
description: A list of scopes that this authorization is in.
type: array
items:
type: string
example:
- public_repo
- user
nullable: true
note:
description: A note to remind you what the OAuth token is for.
type: string
example: Update all gems
note_url:
description: A URL to remind you what app the OAuth token is for.
type: string
client_id:
description: The OAuth app client key for which to create the token.
maxLength: 20
type: string
client_secret:
description: The OAuth app client secret for which to create the token.
maxLength: 40
type: string
fingerprint:
description: A unique string to distinguish an authorization from others created for the same client ID and user.
type: string
examples:
default:
summary: Create an authorization
value:
scopes:
- public_repo
note: optional note
note_url: http://optional/note/url
client_id: abcde12345fghij67890
client_secret: 3ef4ad510c59ad37bac6bb4f80047fb3aee3cc7f
responses:
'201':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/authorization'
examples:
default:
$ref: '#/components/examples/authorization'
headers:
Location:
example: https://api.github.com/authorizations/1
schema:
type: string
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'410':
$ref: '#/components/responses/gone'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
removalDate: '2020-11-13'
deprecationDate: '2020-02-14'
category: oauth-authorizations
subcategory: oauth-authorizations
deprecated: true
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/authorizations/clients/{client_id}:
put:
summary: GitHub Get or Create an Authorization Forspecific App
description: '**Deprecation Notice:** GitHub Enterprise Server will discontinue the [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations/), which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our [web application flow](https://docs.github.com/enterprise-server@3.9/developers/apps/authorizing-oauth-apps#web-application-flow). The [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations) will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the [blog post](https://developer.github.com/changes/2020-02-14-deprecating-oauth-auth-endpoint/).
**Warning:** Apps must use the [web application flow](https://docs.github.com/enterprise-server@3.9/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow) to obtain OAuth tokens that work with GitHub Enterprise Server SAML organizations. OAuth tokens created using the Authorizations API will be unable to access GitHub Enterprise Server SAML organizations. For more information, see the [blog post](https://developer.github.com/changes/2019-11-05-deprecated-passwords-and-authorizations-api).
Creates a new authorization for the specified OAuth application, only if an authorization for that application doesn''t already exist for the user. The URL includes the 20 character client ID for the OAuth app that is requesting the token. It returns the user''s existing authorization for the application if one is present. Otherwise, it creates and returns a new one.
If you have two-factor authentication setup, Basic Authentication for this endpoint requires that you use a one-time password (OTP) and your username and password instead of tokens. For more information, see "[Working with two-factor authentication](https://docs.github.com/enterprise-server@3.9/rest/overview/other-authentication-methods#working-with-two-factor-authentication)."
**Deprecation Notice:** GitHub Enterprise Server will discontinue the [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations/), which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our [web application flow](https://docs.github.com/enterprise-server@3.9/developers/apps/authorizing-oauth-apps#web-application-flow). The [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations) will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the [blog post](https://developer.github.com/changes/2020-02-14-deprecating-oauth-auth-endpoint/).'
tags:
- Create
operationId: getOrCreateAnAuthorizationForspecificApp
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations#Get or Create-an-authorization-for-a-specific-app
parameters:
- $ref: '#/components/parameters/oauth-client-id'
requestBody:
required: true
content:
application/json:
schema:
properties:
client_secret:
description: The OAuth app client secret for which to create the token.
maxLength: 40
type: string
scopes:
description: A list of scopes that this authorization is in.
type: array
items:
type: string
example:
- public_repo
- user
nullable: true
note:
description: A note to remind you what the OAuth token is for.
type: string
example: Update all gems
note_url:
description: A URL to remind you what app the OAuth token is for.
type: string
fingerprint:
description: A unique string to distinguish an authorization from others created for the same client ID and user.
type: string
required:
- client_secret
type: object
examples:
default:
summary: Create an authorization for an app
value:
client_secret: 3ef4ad510c59ad37bac6bb4f80047fb3aee3cc7f
scopes:
- public_repo
note: optional note
note_url: http://optional/note/url
responses:
'200':
description: if returning an existing token
content:
application/json:
schema:
$ref: '#/components/schemas/authorization'
examples:
response-if-returning-an-existing-token:
$ref: '#/components/examples/authorization-response-if-returning-an-existing-token-2'
headers:
Location:
example: https://api.github.com/authorizations/1
schema:
type: string
'201':
description: '**Deprecation Notice:** GitHub will discontinue the [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations), which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our [web application flow](https://docs.github.com/enterprise-server@3.9/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow). The [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations) will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the [blog post](https://developer.github.com/changes/2020-02-14-deprecating-oauth-auth-endpoint/).'
content:
application/json:
schema:
$ref: '#/components/schemas/authorization'
examples:
default:
$ref: '#/components/examples/authorization'
headers:
Location:
example: https://api.github.com/authorizations/1
schema:
type: string
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'422':
$ref: '#/components/responses/validation_failed'
x-github:
githubCloudOnly: false
enabledForGitHubApps: false
removalDate: '2020-11-13'
deprecationDate: '2020-02-14'
category: oauth-authorizations
subcategory: oauth-authorizations
deprecated: true
security:
- bearerHttpAuthentication: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/authorizations/clients/{client_id}/{fingerprint}:
put:
summary: GitHub Get or Create an Authorization Forspecific App and Fingerprint
description: '**Deprecation Notice:** GitHub Enterprise Server will discontinue the [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations/), which is used by integrations to create personal access tokens and OAuth tokens, and you must now create these tokens using our [web application flow](https://docs.github.com/enterprise-server@3.9/developers/apps/authorizing-oauth-apps#web-application-flow). The [OAuth Authorizations API](https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations) will be removed on November, 13, 2020. For more information, including scheduled brownouts, see the [blog post](https://developer.github.com/changes/2020-02-14-deprecating-oauth-auth-endpoint/).
**Warning:** Apps must use the [web application flow](https://docs.github.com/enterprise-server@3.9/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow) to obtain OAuth tokens that work with GitHub Enterprise Server SAML organizations. OAuth tokens created using the Authorizations API will be unable to access GitHub Enterprise Server SAML organizations. For more information, see the [blog post](https://developer.github.com/changes/2019-11-05-deprecated-passwords-and-authorizations-api).
This method will create a new authorization for the specified OAuth application, only if an authorization for that application and fingerprint do not already exist for the user. The URL includes the 20 character client ID for the OAuth app that is requesting the token. `fingerprint` is a unique string to distinguish an authorization from others created for the same client ID and user. It returns the user''s existing authorization for the application if one is present. Otherwise, it creates and returns a new one.
If you have two-factor authentication setup, Basic Authentication for this endpoint requires that you use a one-time password (OTP) and your username and password instead of tokens. For more information, see "[Working with two-factor authentication](https://docs.github.com/enterprise-server@3.9/rest/overview/other-authentication-methods#working-with-two-factor-authentication)."'
tags:
- Create
operationId: getOrCreateAnAuthorizationForspecificAppAndFingerprint
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations#Get or Create-an-authorization-for-a-specific-app-and-fingerprint
parameters:
- $ref: '#/components/parameters/oauth-client-id'
- name: fingerprint
in: path
required: true
schema:
type: string
example: example_value
requestBody:
required: true
content:
application/json:
schema:
properties:
client_secret:
description: The OAuth app client secret for which to create the token.
maxLength: 40
type: string
scopes:
description: A list of scopes that this authorization is in.
type: array
items:
type: string
example:
- public_repo
- user
nullable: true
note:
description: A note to remind you what the OAuth token is for.
type: string
example: Update all gems
note_url:
description: A URL to remind you what app the OAuth token is for.
type: string
required:
- client_secret
type: object
examples:
default:
summary: Create an authorization for an app and fingerprint
value:
client_secret: 3ef4ad510c59ad37bac6bb4f80047fb3aee3cc7f
scopes:
- public_repo
note: optional note
note_url: http://optional/note/url
responses:
'200':
description: if returning an existing token
content:
application/json:
schema:
$ref: '#/components/schemas/authorization'
examples:
response-if-returning-an-existing-token:
$ref: '#/components/examples/authorization-response-if-returning-an-existing-token'
headers:
Location:
example: https://api.github.com/authorizations/1
schema:
type: string
'201':
description: Response if returning a new token
content:
application/json:
schema:
$ref: '#/component
# --- truncated at 32 KB (1463 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-create-api-openapi.yml