Search
K
GitHub v3 REST API

Create a scoped access token

Use a non-scoped user-to-server OAuth access token to create a repository scoped and/or permission scoped user-to-server OAuth access token. You can specify which repositories the token can access and which permissions are granted to the token. You must use Basic Authentication when accessing this endpoint, using the OAuth application’s client_id and client_secret as the username and password. Invalid tokens will return 404 NOT FOUND.

post
http://HOSTNAME/api/v3/applications/{client_id}/token/scoped

Path Parameters

client_idstringrequired

The client ID of your GitHub app.

Body

application/json
access_tokenstringrequired

The OAuth access token used to authenticate to the GitHub API.

Example:e72e16c7e42f292c6912e7710c838347ae178b4a

targetstring

The name of the user or organization to scope the user-to-server access token to. Required unless target_id is specified.

Example:octocat

target_idinteger

The ID of the user or organization to scope the user-to-server access token to. Required unless target is specified.

Example:1

repositoriesarray[string]

The list of repository names to scope the user-to-server access token to. repositories may not be specified if repository_ids is specified.

Example:rails

repository_idsarray[integer]

The list of repository IDs to scope the user-to-server access token to. repository_ids may not be specified if repositories is specified.

Example:[1]

permissionsobject

The permissions granted to the user-to-server access token.

Example:{"contents":"read","issues":"read","deployments":"write","single_file":"read"}

Show Child Parameters

Response

application/json

Response

Authorization

The authorization for an OAuth app, GitHub App, or a Personal Access Token.

idintegerrequired
urlstring(uri)required
scopesarray | null[string]required

A list of scopes that this authorization is in.

tokenstringrequired
token_last_eightstring | nullrequired
hashed_tokenstring | nullrequired
appobjectrequired
Show Child Parameters
notestring | nullrequired
note_urlstring | null(uri)required
updated_atstring(date-time)required
created_atstring(date-time)required
fingerprintstring | nullrequired
userobject | null

Simple User

Show Child Parameters
installationobject | null
Show Child Parameters
post/applications/{client_id}/token/scoped

Body

{ "access_token": "e72e16c7e42f292c6912e7710c838347ae178b4a" }
 
application/json

Check an authorization

DEPRECATED

Deprecation Notice: GitHub Enterprise Server will discontinue OAuth endpoints that contain access_token in the path parameter. We have introduced new endpoints that allow you to securely manage tokens for OAuth Apps by moving access_token to the request body. For more information, see the blog post.

OAuth applications can use a special API method for checking OAuth token validity without exceeding the normal rate limits for failed login attempts. Authentication works differently with this particular endpoint. You must use Basic Authentication when accessing this endpoint, using the OAuth application’s client_id and client_secret as the username and password. Invalid tokens will return 404 NOT FOUND.

get
http://HOSTNAME/api/v3/applications/{client_id}/tokens/{access_token}

Path Parameters

client_idstringrequired

The client ID of your GitHub app.

access_tokenstringrequired

Response

application/json

Response

Authorization

The authorization for an OAuth app, GitHub App, or a Personal Access Token.

idintegerrequired
urlstring(uri)required
scopesarray | null[string]required

A list of scopes that this authorization is in.

tokenstringrequired
token_last_eightstring | nullrequired
hashed_tokenstring | nullrequired
appobjectrequired
Show Child Parameters
notestring | nullrequired
note_urlstring | null(uri)required
updated_atstring(date-time)required
created_atstring(date-time)required
fingerprintstring | nullrequired
userobject | null

Simple User

Show Child Parameters
installationobject | null
Show Child Parameters
get/applications/{client_id}/tokens/{access_token}
 
application/json

Reset an authorization

DEPRECATED

Deprecation Notice: GitHub Enterprise Server will discontinue OAuth endpoints that contain access_token in the path parameter. We have introduced new endpoints that allow you to securely manage tokens for OAuth Apps by moving access_token to the request body. For more information, see the blog post.

OAuth applications can use this API method to reset a valid OAuth token without end-user involvement. Applications must save the “token” property in the response because changes take effect immediately. You must use Basic Authentication when accessing this endpoint, using the OAuth application’s client_id and client_secret as the username and password. Invalid tokens will return 404 NOT FOUND.

post
http://HOSTNAME/api/v3/applications/{client_id}/tokens/{access_token}

Path Parameters

client_idstringrequired

The client ID of your GitHub app.

access_tokenstringrequired

Response

200 application/json

Response

Authorization

The authorization for an OAuth app, GitHub App, or a Personal Access Token.

idintegerrequired
urlstring(uri)required
scopesarray | null[string]required

A list of scopes that this authorization is in.

tokenstringrequired
token_last_eightstring | nullrequired
hashed_tokenstring | nullrequired
appobjectrequired
Show Child Parameters
notestring | nullrequired
note_urlstring | null(uri)required
updated_atstring(date-time)required
created_atstring(date-time)required
fingerprintstring | nullrequired
userobject | null

Simple User

Show Child Parameters
installationobject | null
Show Child Parameters
post/applications/{client_id}/tokens/{access_token}
 
200 application/json

Revoke an authorization for an application

DEPRECATED

Deprecation Notice: GitHub Enterprise Server will discontinue OAuth endpoints that contain access_token in the path parameter. We have introduced new endpoints that allow you to securely manage tokens for OAuth Apps by moving access_token to the request body. For more information, see the blog post.

OAuth application owners can revoke a single token for an OAuth application. You must use Basic Authentication when accessing this endpoint, using the OAuth application’s client_id and client_secret as the username and password.

delete
http://HOSTNAME/api/v3/applications/{client_id}/tokens/{access_token}

Path Parameters

client_idstringrequired

The client ID of your GitHub app.

access_tokenstringrequired

Response

204

Response

delete/applications/{client_id}/tokens/{access_token}
 
204

Get an app

Note: The :app_slug is just the URL-friendly name of your GitHub App. You can find this on the settings page for your GitHub App (e.g., https://github.com/settings/apps/:app_slug).

If the GitHub App you specify is public, you can access this endpoint without authenticating. If the GitHub App you specify is private, you must authenticate with a personal access token or an installation access token to access this endpoint.

get
http://HOSTNAME/api/v3/apps/{app_slug}

Path Parameters

app_slugstringrequired

Response

application/json

Response

GitHub app

GitHub apps are a new way to extend GitHub. They can be installed directly on organizations and user accounts and granted access to specific repositories. They come with granular permissions and built-in webhooks. GitHub apps are first class actors within GitHub.

idintegerrequired

Unique identifier of the GitHub app

Example:37

slugstring

The slug name of the GitHub app

Example:probot-owners

node_idstringrequired

Example:MDExOkludGVncmF0aW9uMQ==

ownerobject | nullrequired

Simple User

Show Child Parameters
namestringrequired

The name of the GitHub app

Example:Probot Owners

descriptionstring | nullrequired

Example:The description of the app.

external_urlstring(uri)required

Example:https://example.com

html_urlstring(uri)required

Example:https://github.com/apps/super-ci

created_atstring(date-time)required

Example:2017-07-08T16:18:44-04:00

updated_atstring(date-time)required

Example:2017-07-08T16:18:44-04:00

permissionsobjectrequired

The set of permissions for the GitHub app

Example:{"issues":"read","deployments":"write"}

Show Child Parameters
eventsarray[string]required

The list of events for the GitHub app

Example:["label","deployment"]

installations_countinteger

The number of installations associated with the GitHub app

Example:5

client_idstring

Example:"Iv1.25b5d1e65ffc4022"

client_secretstring

Example:"1d4b2097ac622ba702d19de498f005747a8b21d3"

webhook_secretstring | null

Example:"6fba8f2fc8a7e8f2cca5577eddd82ca7586b3b6b"

pemstring

Example:"-----BEGIN RSA PRIVATE KEY-----\nMIIEogIBAAKCAQEArYxrNYD/iT5CZVpRJu4rBKmmze3PVmT/gCo2ATUvDvZTPTey\nxcGJ3vvrJXazKk06pN05TN29o98jrYz4cengG3YGsXPNEpKsIrEl8NhbnxapEnM9\nJCMRe0P5JcPsfZlX6hmiT7136GRWiGOUba2X9+HKh8QJVLG5rM007TBER9/z9mWm\nrJuNh+m5l320oBQY/Qq3A7wzdEfZw8qm/mIN0FCeoXH1L6B8xXWaAYBwhTEh6SSn\nZHlO1Xu1JWDmAvBCi0RO5aRSKM8q9QEkvvHP4yweAtK3N8+aAbZ7ovaDhyGz8r6r\nzhU1b8Uo0Z2ysf503WqzQgIajr7Fry7/kUwpgQIDAQABAoIBADwJp80Ko1xHPZDy\nfcCKBDfIuPvkmSW6KumbsLMaQv1aGdHDwwTGv3t0ixSay8CGlxMRtRDyZPib6SvQ\n6OH/lpfpbMdW2ErkksgtoIKBVrDilfrcAvrNZu7NxRNbhCSvN8q0s4ICecjbbVQh\nnueSdlA6vGXbW58BHMq68uRbHkP+k+mM9U0mDJ1HMch67wlg5GbayVRt63H7R2+r\nVxcna7B80J/lCEjIYZznawgiTvp3MSanTglqAYi+m1EcSsP14bJIB9vgaxS79kTu\noiSo93leJbBvuGo8QEiUqTwMw4tDksmkLsoqNKQ1q9P7LZ9DGcujtPy4EZsamSJT\ny8OJt0ECgYEA2lxOxJsQk2kI325JgKFjo92mQeUObIvPfSNWUIZQDTjniOI6Gv63\nGLWVFrZcvQBWjMEQraJA9xjPbblV8PtfO87MiJGLWCHFxmPz2dzoedN+2Coxom8m\nV95CLz8QUShuao6u/RYcvUaZEoYs5bHcTmy5sBK80JyEmafJPtCQVxMCgYEAy3ar\nZr3yv4xRPEPMat4rseswmuMooSaK3SKub19WFI5IAtB/e7qR1Rj9JhOGcZz+OQrl\nT78O2OFYlgOIkJPvRMrPpK5V9lslc7tz1FSh3BZMRGq5jSyD7ETSOQ0c8T2O/s7v\nbeEPbVbDe4mwvM24XByH0GnWveVxaDl51ABD65sCgYB3ZAspUkOA5egVCh8kNpnd\nSd6SnuQBE3ySRlT2WEnCwP9Ph6oPgn+oAfiPX4xbRqkL8q/k0BdHQ4h+zNwhk7+h\nWtPYRAP1Xxnc/F+jGjb+DVaIaKGU18MWPg7f+FI6nampl3Q0KvfxwX0GdNhtio8T\nTj1E+SnFwh56SRQuxSh2gwKBgHKjlIO5NtNSflsUYFM+hyQiPiqnHzddfhSG+/3o\nm5nNaSmczJesUYreH5San7/YEy2UxAugvP7aSY2MxB+iGsiJ9WD2kZzTUlDZJ7RV\nUzWsoqBR+eZfVJ2FUWWvy8TpSG6trh4dFxImNtKejCR1TREpSiTV3Zb1dmahK9GV\nrK9NAoGAbBxRLoC01xfxCTgt5BDiBcFVh4fp5yYKwavJPLzHSpuDOrrI9jDn1oKN\nonq5sDU1i391zfQvdrbX4Ova48BN+B7p63FocP/MK5tyyBoT8zQEk2+vWDOw7H/Z\nu5dTCPxTIsoIwUw1I+7yIxqJzLPFgR2gVBwY1ra/8iAqCj+zeBw=\n-----END RSA PRIVATE KEY-----\n"

get/apps/{app_slug}
 
application/json