openapi: 3.0.3
info:
version: 1.1.4
title: GitHub Application About Authorization 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: Authorization
paths:
/applications/{client_id}/grant:
delete:
summary: GitHub Delete an App Authorization
description: 'OAuth and GitHub application owners can revoke a grant for their application and a specific user. 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 OAuth application''s `client_id` and `client_secret` as the username and password. You must also provide a valid OAuth `access_token` as an input parameter and the grant for the token''s owner will be deleted.
Deleting an application''s grant will also delete all OAuth tokens associated with the application for the user. Once deleted, the application will have no access to the user''s account and will no longer be listed on [the application authorizations settings screen within GitHub](https://github.com/settings/applications#authorized).'
operationId: deleteAnAppAuthorization
tags:
- Authorization
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/apps/oauth-applications#delete-an-app-authorization
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
/authorizations:
get:
summary: GitHub List Your Authorizations
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/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/).'
tags:
- Authorization
operationId: listYourAuthorizations
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations#list-your-authorizations
parameters:
- $ref: '#/components/parameters/per-page'
- $ref: '#/components/parameters/page'
- name: client_id
in: query
required: false
description: The client ID of your GitHub app.
schema:
type: string
example: '12345678'
responses:
'200':
description: Response
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/authorization'
examples:
default:
$ref: '#/components/examples/authorization-items'
headers:
Link:
$ref: '#/components/headers/link'
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
'404':
$ref: '#/components/responses/not_found'
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
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:
- Authorization
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:
- Authorization
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:
- Authorization
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: '#/components/schemas/authorization'
examples:
default:
$ref: '#/components/examples/authorization-3'
headers:
Location:
example: https://api.github.com/authorizations/1
schema:
type: string
'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/{authorization_id}:
get:
summary: GitHub Getsingle 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/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/).'
tags:
- Authorization
operationId: getsingleAuthorization
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations#get-a-single-authorization
parameters:
- $ref: '#/components/parameters/authorization-id'
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/authorization'
examples:
default:
$ref: '#/components/examples/authorization-2'
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
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
patch:
summary: GitHub Update an Existing 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/).
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)."
You can only send one of these scope keys at a time.'
tags:
- Authorization
operationId: updateAnExistingAuthorization
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations#update-an-existing-authorization
parameters:
- $ref: '#/components/parameters/authorization-id'
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
add_scopes:
description: A list of scopes to add to this authorization.
type: array
items:
type: string
remove_scopes:
description: A list of scopes to remove from this authorization.
type: array
items:
type: string
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
examples:
default:
summary: Example of updating scopes and note
value:
add_scopes:
- public_repo
remove_scopes:
- user
note: optional note
responses:
'200':
description: Response
content:
application/json:
schema:
$ref: '#/components/schemas/authorization'
examples:
default:
$ref: '#/components/examples/authorization-2'
'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
delete:
summary: GitHub Delete an 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/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/).'
tags:
- Authorization
operationId: deleteAnAuthorization
externalDocs:
description: API method documentation
url: https://docs.github.com/enterprise-server@3.9/rest/oauth-authorizations/oauth-authorizations#delete-an-authorization
parameters:
- $ref: '#/components/parameters/authorization-id'
responses:
'204':
description: Response
'304':
$ref: '#/components/responses/not_modified'
'401':
$ref: '#/components/responses/requires_authentication'
'403':
$ref: '#/components/responses/forbidden'
x-github:
githubCloudOnly: false
# --- truncated at 32 KB (661 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-authorization-api-openapi.yml