Skip to main content

OAuth Apps

About the OAuth App API

You can use this API to manage the OAuth tokens an 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
acceptstring

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
client_idstringRequired

The client ID of the GitHub app.

Body parameters
Name, Type, Description
access_tokenstringRequired

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

HTTP response status codes

Status codeDescription
204

No Content

422

Validation failed

Code samples

delete/applications/{client_id}/grant
curl \ -X DELETE \ -H "Accept: application/vnd.github+json" \ -H "Authorization: token <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.

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 token as :access_token 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 Applications settings page under "Authorized OAuth Apps" on GitHub Enterprise Server.

Parameters

Headers
Name, Type, Description
acceptstring

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
client_idstringRequired

The client ID of the GitHub app.

access_tokenstringRequired

HTTP response status codes

Status codeDescription
204

No Content

Code samples

delete/applications/{client_id}/grants/{access_token}
curl \ -X DELETE \ -H "Accept: application/vnd.github+json" \ -H "Authorization: token <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
acceptstring

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
client_idstringRequired

The client ID of the GitHub app.

Body parameters
Name, Type, Description
access_tokenstringRequired

The access_token of the OAuth application.

HTTP response status codes

Status codeDescription
200

OK

404

Resource not found

422

Validation failed

Code samples

post/applications/{client_id}/token
curl \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: token <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
acceptstring

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
client_idstringRequired

The client ID of the GitHub app.

Body parameters
Name, Type, Description
access_tokenstringRequired

The access_token of the OAuth application.

HTTP response status codes

Status codeDescription
200

OK

422

Validation failed

Code samples

patch/applications/{client_id}/token
curl \ -X PATCH \ -H "Accept: application/vnd.github+json" \ -H "Authorization: token <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
acceptstring

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
client_idstringRequired

The client ID of the GitHub app.

Body parameters
Name, Type, Description
access_tokenstringRequired

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

HTTP response status codes

Status codeDescription
204

No Content

422

Validation failed

Code samples

delete/applications/{client_id}/token
curl \ -X DELETE \ -H "Accept: application/vnd.github+json" \ -H "Authorization: token <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
acceptstring

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
client_idstringRequired

The client ID of the GitHub app.

Body parameters
Name, Type, Description
access_tokenstringRequired

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

targetstring

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

target_idinteger

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

repositoriesarray 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_idsarray 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.

permissionsobject

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

Name, Type, Description
actionsstring

The level of permission to grant the access token for GitHub Actions workflows, workflow runs, and artifacts.

Can be one of: read, write

administrationstring

The level of permission to grant the access token for repository creation, deletion, settings, teams, and collaborators creation.

Can be one of: read, write

checksstring

The level of permission to grant the access token for checks on code.

Can be one of: read, write

contentsstring

The level of permission to grant the access token for repository contents, commits, branches, downloads, releases, and merges.

Can be one of: read, write

deploymentsstring

The level of permission to grant the access token for deployments and deployment statuses.

Can be one of: read, write

environmentsstring

The level of permission to grant the access token for managing repository environments.

Can be one of: read, write

issuesstring

The level of permission to grant the access token for issues and related comments, assignees, labels, and milestones.

Can be one of: read, write

metadatastring

The level of permission to grant the access token to search repositories, list collaborators, and access repository metadata.

Can be one of: read, write

packagesstring

The level of permission to grant the access token for packages published to GitHub Packages.

Can be one of: read, write

pagesstring

The level of permission to grant the access token to retrieve Pages statuses, configuration, and builds, as well as create new builds.

Can be one of: read, write

pull_requestsstring

The level of permission to grant the access token for pull requests and related comments, assignees, labels, milestones, and merges.

Can be one of: read, write

repository_hooksstring

The level of permission to grant the access token to manage the post-receive hooks for a repository.

Can be one of: read, write

repository_projectsstring

The level of permission to grant the access token to manage repository projects, columns, and cards.

Can be one of: read, write, admin

secret_scanning_alertsstring

The level of permission to grant the access token to view and manage secret scanning alerts.

Can be one of: read, write

secretsstring

The level of permission to grant the access token to manage repository secrets.

Can be one of: read, write

security_eventsstring

The level of permission to grant the access token to view and manage security events like code scanning alerts.

Can be one of: read, write

single_filestring

The level of permission to grant the access token to manage just a single file.

Can be one of: read, write

statusesstring

The level of permission to grant the access token for commit statuses.

Can be one of: read, write

vulnerability_alertsstring

The level of permission to grant the access token to manage Dependabot alerts.

Can be one of: read, write

workflowsstring

The level of permission to grant the access token to update GitHub Actions workflow files.

Can be one of: write

membersstring

The level of permission to grant the access token for organization teams and members.

Can be one of: read, write

organization_administrationstring

The level of permission to grant the access token to manage access to an organization.

Can be one of: read, write

organization_hooksstring

The level of permission to grant the access token to manage the post-receive hooks for an organization.

Can be one of: read, write

organization_planstring

The level of permission to grant the access token for viewing an organization's plan.

Can be one of: read

organization_projectsstring

The level of permission to grant the access token to manage organization projects and projects beta (where available).

Can be one of: read, write, admin

organization_packagesstring

The level of permission to grant the access token for organization packages published to GitHub Packages.

Can be one of: read, write

organization_secretsstring

The level of permission to grant the access token to manage organization secrets.

Can be one of: read, write

organization_self_hosted_runnersstring

The level of permission to grant the access token to view and manage GitHub Actions self-hosted runners available to an organization.

Can be one of: read, write

organization_user_blockingstring

The level of permission to grant the access token to view and manage users blocked by the organization.

Can be one of: read, write

team_discussionsstring

The level of permission to grant the access token to manage team discussions and related comments.

Can be one of: read, write

content_referencesstring

The level of permission to grant the access token for notification of content references and creation content attachments.

Can be one of: read, write

HTTP response status codes

Status codeDescription
200

OK

401

Requires authentication

403

Forbidden

404

Resource not found

422

Validation failed

Code samples

post/applications/{client_id}/token/scoped
curl \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: token <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

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.

Parameters

Headers
Name, Type, Description
acceptstring

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
client_idstringRequired

The client ID of the GitHub app.

access_tokenstringRequired

HTTP response status codes

Status codeDescription
200

OK

404

Resource not found

Code samples

get/applications/{client_id}/tokens/{access_token}
curl \ -H "Accept: application/vnd.github+json" \ -H "Authorization: token <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

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.

Parameters

Headers
Name, Type, Description
acceptstring

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
client_idstringRequired

The client ID of the GitHub app.

access_tokenstringRequired

HTTP response status codes

Status codeDescription
200

OK

Code samples

post/applications/{client_id}/tokens/{access_token}
curl \ -X POST \ -H "Accept: application/vnd.github+json" \ -H "Authorization: token <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

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.

Parameters

Headers
Name, Type, Description
acceptstring

Setting to application/vnd.github+json is recommended.

Path parameters
Name, Type, Description
client_idstringRequired

The client ID of the GitHub app.

access_tokenstringRequired

HTTP response status codes

Status codeDescription
204

No Content

Code samples

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

Response

Status: 204