The GitHub Authorization (OAuth Authorizations) API historically let you programmatically create, list, inspect, and revoke access tokens for a user or OAuth applicationsetting scopes, verifying token validity, rotating or deleting tokens, and generally managing what an app could do on a users behalf. It was commonly used with basic authentication (and 2FA) to mint personal access tokens and to manage OAuth app grants.
openapi: 3.0.3
info:
version: 1.1.4
title: GitHub Auth API
description: >
You can authenticate to the REST API to access more endpoints and have a
higher rate limit. Many REST API endpoints require authentication or return
additional information if you are authenticated. Additionally, you can make
more requests per hour when you are authenticated.
license:
name: MIT
url: https://spdx.org/licenses/MIT
termsOfService: https://docs.github.com/articles/github-terms-of-service
contact:
name: Support
url: https://support.github.com/contact?tags=dotcom-rest-api
x-github-plan: ghes
x-github-release: 3.9
tags:
- name: Add
- name: Applications
- name: Authorization
- name: Authorized
- name: Create
- name: Delete
- name: Existing
- name: Fingerprint
- name: Get
- name: Impersonation
- name: Keys
- name: Lists
- name: Oauth
- name: Remove
- name: Settings
- name: Setup
- name: Single
- name: Specific
- name: Ssh
- name: Tokens
- name: Update
servers:
- url: '{protocol}://{hostname}/api/v3'
variables:
hostname:
description: Self-hosted Enterprise Server hostname
default: api.github.com
protocol:
description: Self-hosted Enterprise Server protocol
default: https
externalDocs:
description: GitHub Enterprise Developer Docs
url: https://docs.github.com/[email protected]/rest/
paths:
/admin/users/{username}/authorizations:
post:
summary: GitHub Create an Impersonation Oauth Token
description: >-
This API endpoint allows administrators to create an OAuth impersonation
token for a specific GitHub user by making a POST request to
/admin/users/{username}/authorizations. The operation enables authorized
administrators to generate access tokens on behalf of other users, which
can be useful for troubleshooting, performing administrative tasks, or
assisting users with account-related issues. The endpoint requires admin
privileges and accepts the target username as a path parameter, along
with optional scopes in the request body to define the permissions
granted to the impersonation token. Upon successful execution, it
returns an OAuth token that can be used to authenticate API requests as
if made by the specified user, though the token should be handled with
extreme care due to its elevated access capabilities.
operationId: createAnImpersonationOauthToken
tags:
- Create
- Impersonation
- Oauth
- Tokens
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/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/[email protected]/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:
- Delete
- Impersonation
- Oauth
- Tokens
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/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
/authorizations:
get:
summary: GitHub List Your Authorizations
description: >-
**Deprecation Notice:** GitHub Enterprise Server will discontinue the
[OAuth Authorizations
API](https://docs.github.com/[email protected]/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/[email protected]/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow).
The [OAuth Authorizations
API](https://docs.github.com/[email protected]/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
- Lists
operationId: listYourAuthorizations
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/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/[email protected]/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/[email protected]/developers/apps/authorizing-oauth-apps#web-application-flow).
The [OAuth Authorizations
API](https://docs.github.com/[email protected]/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/[email protected]/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/[email protected]/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/[email protected]/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/[email protected]/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/[email protected]/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
- Create
operationId: createnewAuthorization
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/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/[email protected]/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/[email protected]/developers/apps/authorizing-oauth-apps#web-application-flow).
The [OAuth Authorizations
API](https://docs.github.com/[email protected]/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/[email protected]/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/[email protected]/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/[email protected]/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/[email protected]/developers/apps/authorizing-oauth-apps#web-application-flow).
The [OAuth Authorizations
API](https://docs.github.com/[email protected]/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:
- Applications
- Authorization
- Create
- Get
- Specific
operationId: getOrCreateAnAuthorizationForspecificApp
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/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/[email protected]/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/[email protected]/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow).
The [OAuth Authorizations
API](https://docs.github.com/[email protected]/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/[email protected]/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/[email protected]/developers/apps/authorizing-oauth-apps#web-application-flow).
The [OAuth Authorizations
API](https://docs.github.com/[email protected]/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/[email protected]/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/[email protected]/rest/overview/other-authentication-methods#working-with-two-factor-authentication)."
tags:
- Applications
- Authorization
- Create
- Fingerprint
- Get
- Specific
operationId: getOrCreateAnAuthorizationForspecificAppAndFingerprint
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/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/[email protected]/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/[email protected]/apps/building-oauth-apps/authorizing-oauth-apps/#web-application-flow).
The [OAuth Authorizations
API](https://docs.github.com/[email protected]/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
- Get
- Single
operationId: getsingleAuthorization
externalDocs:
description: API method documentation
url: >-
https://docs.github.com/[email protected]/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/[email protected]/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/[email protected]/developers/apps/authorizing-oauth-apps#web-application-flow).
The [OAuth Authorizations
API](https://docs.github.com/[email protected]/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@
# --- truncated at 32 KB (6547 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/github/refs/heads/main/openapi/github-auth-api-openapi.yml