This version of GitHub Enterprise was discontinued on 2023-01-18. No patch releases will be made, even for critical security issues. For better performance, improved security, and new features, upgrade to the latest version of GitHub Enterprise. For help with the upgrade, contact GitHub Enterprise support.

OAuth Apps

Use the REST API to interact with OAuth Apps

About OAuth Apps

You can use these endpoints to manage the OAuth tokens that OAuth App uses to access people's accounts on your GitHub Enterprise Server instance.

Delete an app authorization

OAuth application owners can revoke a grant for their OAuth application and a specific user. You must use 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 OAuth 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.

Parameters

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`client_id`stringRequired The client ID of the GitHub app.
Body parameters
Name, Type, Description
`access_token`stringRequired The OAuth access token used to authenticate to the GitHub API.

HTTP response status codes

Status code	Description
`204`	No Content
`422`	Validation failed, or the endpoint has been spammed.

Code samples

delete/applications/{client_id}/grant

curl \
 -X DELETE \
 -H "Accept: application/vnd.github+json" \
 -H "Authorization: Bearer <YOUR-TOKEN>" \
 http(s)://HOSTNAME/api/v3/applications/Iv1.8a61f9b3a7aba766/grant \
 -d '{"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a"}'

Response

Status: 204

Revoke a grant for an application

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.

Deleting an OAuth 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 Applications settings page under "Authorized OAuth Apps" on GitHub Enterprise Server.

Parameters

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`client_id`stringRequired The client ID of the GitHub app.
`access_token`stringRequired

HTTP response status codes

Status code	Description
`204`	No Content

Code samples

delete/applications/{client_id}/grants/{access_token}

curl \
 -X DELETE \
 -H "Accept: application/vnd.github+json" \
 -H "Authorization: Bearer <YOUR-TOKEN>" \
 http(s)://HOSTNAME/api/v3/applications/Iv1.8a61f9b3a7aba766/grants/ACCESS_TOKEN

Response

Status: 204

Check a token

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 to use this endpoint, where the username is the OAuth application client_id and the password is its client_secret. Invalid tokens will return 404 NOT FOUND.

Parameters

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`client_id`stringRequired The client ID of the GitHub app.
Body parameters
Name, Type, Description
`access_token`stringRequired The access_token of the OAuth application.

HTTP response status codes

Status code	Description
`200`	OK
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

Code samples

post/applications/{client_id}/token

curl \
 -X POST \
 -H "Accept: application/vnd.github+json" \
 -H "Authorization: Bearer <YOUR-TOKEN>" \
 http(s)://HOSTNAME/api/v3/applications/Iv1.8a61f9b3a7aba766/token \
 -d '{"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a"}'

Response

Status: 200

{
 "id": 1,
 "url": "https://api.github.com/authorizations/1",
 "scopes": [
 "public_repo",
 "user"
 ],
 "token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a",
 "token_last_eight": "Ae178B4a",
 "hashed_token": "25f94a2a5c7fbaf499c665bc73d67c1c87e496da8985131633ee0a95819db2e8",
 "app": {
 "url": "http://my-github-app.com",
 "name": "my github app",
 "client_id": "Iv1.8a61f9b3a7aba766"
 },
 "note": "optional note",
 "note_url": "http://optional/note/url",
 "updated_at": "2011-09-06T20:39:23Z",
 "created_at": "2011-09-06T17:26:27Z",
 "fingerprint": "jklmnop12345678",
 "expires_at": "2011-09-08T17:26:27Z",
 "user": {
 "login": "octocat",
 "id": 1,
 "node_id": "MDQ6VXNlcjE=",
 "avatar_url": "https://github.com/images/error/octocat_happy.gif",
 "gravatar_id": "",
 "url": "https://api.github.com/users/octocat",
 "html_url": "https://github.com/octocat",
 "followers_url": "https://api.github.com/users/octocat/followers",
 "following_url": "https://api.github.com/users/octocat/following{/other_user}",
 "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
 "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
 "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
 "organizations_url": "https://api.github.com/users/octocat/orgs",
 "repos_url": "https://api.github.com/users/octocat/repos",
 "events_url": "https://api.github.com/users/octocat/events{/privacy}",
 "received_events_url": "https://api.github.com/users/octocat/received_events",
 "type": "User",
 "site_admin": false
 }
}

Reset a token

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.

Parameters

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`client_id`stringRequired The client ID of the GitHub app.
Body parameters
Name, Type, Description
`access_token`stringRequired The access_token of the OAuth application.

HTTP response status codes

Status code	Description
`200`	OK
`422`	Validation failed, or the endpoint has been spammed.

Code samples

patch/applications/{client_id}/token

curl \
 -X PATCH \
 -H "Accept: application/vnd.github+json" \
 -H "Authorization: Bearer <YOUR-TOKEN>" \
 http(s)://HOSTNAME/api/v3/applications/Iv1.8a61f9b3a7aba766/token \
 -d '{"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a"}'

Response

Status: 200

{
 "id": 1,
 "url": "https://api.github.com/authorizations/1",
 "scopes": [
 "public_repo",
 "user"
 ],
 "token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a",
 "token_last_eight": "Ae178B4a",
 "hashed_token": "25f94a2a5c7fbaf499c665bc73d67c1c87e496da8985131633ee0a95819db2e8",
 "app": {
 "url": "http://my-github-app.com",
 "name": "my github app",
 "client_id": "Iv1.8a61f9b3a7aba766"
 },
 "note": "optional note",
 "note_url": "http://optional/note/url",
 "updated_at": "2011-09-06T20:39:23Z",
 "created_at": "2011-09-06T17:26:27Z",
 "fingerprint": "jklmnop12345678",
 "expires_at": "2011-09-08T17:26:27Z",
 "user": {
 "login": "octocat",
 "id": 1,
 "node_id": "MDQ6VXNlcjE=",
 "avatar_url": "https://github.com/images/error/octocat_happy.gif",
 "gravatar_id": "",
 "url": "https://api.github.com/users/octocat",
 "html_url": "https://github.com/octocat",
 "followers_url": "https://api.github.com/users/octocat/followers",
 "following_url": "https://api.github.com/users/octocat/following{/other_user}",
 "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
 "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
 "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
 "organizations_url": "https://api.github.com/users/octocat/orgs",
 "repos_url": "https://api.github.com/users/octocat/repos",
 "events_url": "https://api.github.com/users/octocat/events{/privacy}",
 "received_events_url": "https://api.github.com/users/octocat/received_events",
 "type": "User",
 "site_admin": false
 }
}

Delete an app token

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.

Parameters

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`client_id`stringRequired The client ID of the GitHub app.
Body parameters
Name, Type, Description
`access_token`stringRequired The OAuth access token used to authenticate to the GitHub API.

HTTP response status codes

Status code	Description
`204`	No Content
`422`	Validation failed, or the endpoint has been spammed.

Code samples

delete/applications/{client_id}/token

curl \
 -X DELETE \
 -H "Accept: application/vnd.github+json" \
 -H "Authorization: Bearer <YOUR-TOKEN>" \
 http(s)://HOSTNAME/api/v3/applications/Iv1.8a61f9b3a7aba766/token \
 -d '{"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a"}'

Response

Status: 204

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.

Parameters

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`client_id`stringRequired The client ID of the GitHub app.
Body parameters
Name, Type, Description
`access_token`stringRequired The OAuth access token used to authenticate to the GitHub API.
`target`string The name of the user or organization to scope the user-to-server access token to. Required unless `target_id` is specified.
`target_id`integer The ID of the user or organization to scope the user-to-server access token to. Required unless `target` is specified.
`repositories`array of strings The list of repository names to scope the user-to-server access token to. `repositories` may not be specified if `repository_ids` is specified.
`repository_ids`array of integers The list of repository IDs to scope the user-to-server access token to. `repository_ids` may not be specified if `repositories` is specified.
`permissions`object The permissions granted to the user-to-server access token.

HTTP response status codes

Status code	Description
`200`	OK
`401`	Requires authentication
`403`	Forbidden
`404`	Resource not found
`422`	Validation failed, or the endpoint has been spammed.

Code samples

post/applications/{client_id}/token/scoped

curl \
 -X POST \
 -H "Accept: application/vnd.github+json" \
 -H "Authorization: Bearer <YOUR-TOKEN>" \
 http(s)://HOSTNAME/api/v3/applications/Iv1.8a61f9b3a7aba766/token/scoped \
 -d '{"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a","target":"octocat","permissions":{"metadata":"read","issues":"write","contents":"read"}}'

Response

Status: 200

{
 "id": 1,
 "url": "https://api.github.com/authorizations/1",
 "scopes": [],
 "token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a",
 "token_last_eight": "Ae178B4a",
 "hashed_token": "25f94a2a5c7fbaf499c665bc73d67c1c87e496da8985131633ee0a95819db2e8",
 "app": {
 "url": "http://my-github-app.com",
 "name": "my github app",
 "client_id": "Iv1.8a61f9b3a7aba766"
 },
 "note": "optional note",
 "note_url": "http://optional/note/url",
 "updated_at": "2011-09-06T20:39:23Z",
 "created_at": "2011-09-06T17:26:27Z",
 "fingerprint": "jklmnop12345678",
 "expires_at": "2011-09-08T17:26:27Z",
 "user": {
 "login": "octocat",
 "id": 1,
 "node_id": "MDQ6VXNlcjE=",
 "avatar_url": "https://github.com/images/error/octocat_happy.gif",
 "gravatar_id": "",
 "url": "https://api.github.com/users/octocat",
 "html_url": "https://github.com/octocat",
 "followers_url": "https://api.github.com/users/octocat/followers",
 "following_url": "https://api.github.com/users/octocat/following{/other_user}",
 "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
 "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
 "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
 "organizations_url": "https://api.github.com/users/octocat/orgs",
 "repos_url": "https://api.github.com/users/octocat/repos",
 "events_url": "https://api.github.com/users/octocat/events{/privacy}",
 "received_events_url": "https://api.github.com/users/octocat/received_events",
 "type": "User",
 "site_admin": false
 },
 "installation": {
 "permissions": {
 "metadata": "read",
 "issues": "write",
 "contents": "read"
 },
 "repository_selection": "selected",
 "single_file_name": ".github/workflow.yml",
 "repositories_url": "https://api.github.com/user/repos",
 "account": {
 "login": "octocat",
 "id": 1,
 "node_id": "MDQ6VXNlcjE=",
 "avatar_url": "https://github.com/images/error/octocat_happy.gif",
 "gravatar_id": "",
 "url": "https://api.github.com/users/octocat",
 "html_url": "https://github.com/octocat",
 "followers_url": "https://api.github.com/users/octocat/followers",
 "following_url": "https://api.github.com/users/octocat/following{/other_user}",
 "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
 "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
 "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
 "organizations_url": "https://api.github.com/users/octocat/orgs",
 "repos_url": "https://api.github.com/users/octocat/repos",
 "events_url": "https://api.github.com/users/octocat/events{/privacy}",
 "received_events_url": "https://api.github.com/users/octocat/received_events",
 "type": "User",
 "site_admin": false
 },
 "has_multiple_single_files": false,
 "single_file_paths": []
 }
}

Check an authorization

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.

Parameters

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`client_id`stringRequired The client ID of the GitHub app.
`access_token`stringRequired

HTTP response status codes

Status code	Description
`200`	OK
`404`	Resource not found

Code samples

get/applications/{client_id}/tokens/{access_token}

curl \
 -H "Accept: application/vnd.github+json" \
 -H "Authorization: Bearer <YOUR-TOKEN>" \
 http(s)://HOSTNAME/api/v3/applications/Iv1.8a61f9b3a7aba766/tokens/ACCESS_TOKEN

Response

Status: 200

{
 "id": 1,
 "url": "https://api.github.com/authorizations/1",
 "scopes": [
 "public_repo",
 "user"
 ],
 "token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a",
 "token_last_eight": "Ae178B4a",
 "hashed_token": "25f94a2a5c7fbaf499c665bc73d67c1c87e496da8985131633ee0a95819db2e8",
 "app": {
 "url": "http://my-github-app.com",
 "name": "my github app",
 "client_id": "Iv1.8a61f9b3a7aba766"
 },
 "note": "optional note",
 "note_url": "http://optional/note/url",
 "updated_at": "2011-09-06T20:39:23Z",
 "created_at": "2011-09-06T17:26:27Z",
 "fingerprint": "jklmnop12345678",
 "expires_at": "2011-09-08T17:26:27Z",
 "user": {
 "login": "octocat",
 "id": 1,
 "node_id": "MDQ6VXNlcjE=",
 "avatar_url": "https://github.com/images/error/octocat_happy.gif",
 "gravatar_id": "",
 "url": "https://api.github.com/users/octocat",
 "html_url": "https://github.com/octocat",
 "followers_url": "https://api.github.com/users/octocat/followers",
 "following_url": "https://api.github.com/users/octocat/following{/other_user}",
 "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
 "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
 "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
 "organizations_url": "https://api.github.com/users/octocat/orgs",
 "repos_url": "https://api.github.com/users/octocat/repos",
 "events_url": "https://api.github.com/users/octocat/events{/privacy}",
 "received_events_url": "https://api.github.com/users/octocat/received_events",
 "type": "User",
 "site_admin": false
 }
}

Reset an authorization

Parameters

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`client_id`stringRequired The client ID of the GitHub app.
`access_token`stringRequired

HTTP response status codes

Status code	Description
`200`	OK

Code samples

post/applications/{client_id}/tokens/{access_token}

curl \
 -X POST \
 -H "Accept: application/vnd.github+json" \
 -H "Authorization: Bearer <YOUR-TOKEN>" \
 http(s)://HOSTNAME/api/v3/applications/Iv1.8a61f9b3a7aba766/tokens/ACCESS_TOKEN

Response

Status: 200

{
 "id": 1,
 "url": "https://api.github.com/authorizations/1",
 "scopes": [
 "public_repo",
 "user"
 ],
 "token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a",
 "token_last_eight": "Ae178B4a",
 "hashed_token": "25f94a2a5c7fbaf499c665bc73d67c1c87e496da8985131633ee0a95819db2e8",
 "app": {
 "url": "http://my-github-app.com",
 "name": "my github app",
 "client_id": "Iv1.8a61f9b3a7aba766"
 },
 "note": "optional note",
 "note_url": "http://optional/note/url",
 "updated_at": "2011-09-06T20:39:23Z",
 "created_at": "2011-09-06T17:26:27Z",
 "fingerprint": "jklmnop12345678",
 "expires_at": "2011-09-08T17:26:27Z",
 "user": {
 "login": "octocat",
 "id": 1,
 "node_id": "MDQ6VXNlcjE=",
 "avatar_url": "https://github.com/images/error/octocat_happy.gif",
 "gravatar_id": "",
 "url": "https://api.github.com/users/octocat",
 "html_url": "https://github.com/octocat",
 "followers_url": "https://api.github.com/users/octocat/followers",
 "following_url": "https://api.github.com/users/octocat/following{/other_user}",
 "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
 "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
 "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
 "organizations_url": "https://api.github.com/users/octocat/orgs",
 "repos_url": "https://api.github.com/users/octocat/repos",
 "events_url": "https://api.github.com/users/octocat/events{/privacy}",
 "received_events_url": "https://api.github.com/users/octocat/received_events",
 "type": "User",
 "site_admin": false
 }
}

Revoke an authorization for an application

Parameters

Headers
Name, Type, Description
`accept`string Setting to `application/vnd.github+json` is recommended.
Path parameters
Name, Type, Description
`client_id`stringRequired The client ID of the GitHub app.
`access_token`stringRequired

HTTP response status codes

Status code	Description
`204`	No Content

Code samples

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

curl \
 -X DELETE \
 -H "Accept: application/vnd.github+json" \
 -H "Authorization: Bearer <YOUR-TOKEN>" \
 http(s)://HOSTNAME/api/v3/applications/Iv1.8a61f9b3a7aba766/tokens/ACCESS_TOKEN

Response

Status: 204

URL: https://docs.github.com/en/enterprise-server@3.3/rest/apps/oauth-applications

OAuth Apps

About OAuth Apps

Delete an app authorization

Response

Revoke a grant for an application

Response

Check a token

Response

Reset a token

Response

Delete an app token

Response

Create a scoped access token

Response

Check an authorization

Response

Reset an authorization

Response

Revoke an authorization for an application

Response