Skip to main content

OAuth 应用程序

关于 OAuth 应用程序 API

您可以使用此 API 来管理 OAuth 应用程序 用于访问 您的 GitHub Enterprise Server 实例 上用户帐户的 OAuth 令牌。

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.

参数

标头
名称, 类型, 描述
acceptstring

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

路径参数
名称, 类型, 描述
client_idstring必选

The client ID of the GitHub app.

正文参数
名称, 类型, 描述
access_tokenstring必选

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

HTTP 响应状态代码

状态代码描述
204

No Content

422

Validation failed

代码示例

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.

参数

标头
名称, 类型, 描述
acceptstring

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

路径参数
名称, 类型, 描述
client_idstring必选

The client ID of the GitHub app.

access_tokenstring必选

HTTP 响应状态代码

状态代码描述
204

No Content

代码示例

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.

参数

标头
名称, 类型, 描述
acceptstring

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

路径参数
名称, 类型, 描述
client_idstring必选

The client ID of the GitHub app.

正文参数
名称, 类型, 描述
access_tokenstring必选

The access_token of the OAuth application.

HTTP 响应状态代码

状态代码描述
200

OK

404

Resource not found

422

Validation failed

代码示例

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.

参数

标头
名称, 类型, 描述
acceptstring

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

路径参数
名称, 类型, 描述
client_idstring必选

The client ID of the GitHub app.

正文参数
名称, 类型, 描述
access_tokenstring必选

The access_token of the OAuth application.

HTTP 响应状态代码

状态代码描述
200

OK

422

Validation failed

代码示例

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.

参数

标头
名称, 类型, 描述
acceptstring

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

路径参数
名称, 类型, 描述
client_idstring必选

The client ID of the GitHub app.

正文参数
名称, 类型, 描述
access_tokenstring必选

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

HTTP 响应状态代码

状态代码描述
204

No Content

422

Validation failed

代码示例

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.

参数

标头
名称, 类型, 描述
acceptstring

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

路径参数
名称, 类型, 描述
client_idstring必选

The client ID of the GitHub app.

正文参数
名称, 类型, 描述
access_tokenstring必选

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.

名称, 类型, 描述
actionsstring

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

可以是以下其中之一: read, write

administrationstring

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

可以是以下其中之一: read, write

checksstring

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

可以是以下其中之一: read, write

contentsstring

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

可以是以下其中之一: read, write

deploymentsstring

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

可以是以下其中之一: read, write

environmentsstring

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

可以是以下其中之一: read, write

issuesstring

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

可以是以下其中之一: read, write

metadatastring

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

可以是以下其中之一: read, write

packagesstring

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

可以是以下其中之一: 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.

可以是以下其中之一: read, write

pull_requestsstring

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

可以是以下其中之一: read, write

repository_hooksstring

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

可以是以下其中之一: read, write

repository_projectsstring

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

可以是以下其中之一: read, write, admin

secret_scanning_alertsstring

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

可以是以下其中之一: read, write

secretsstring

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

可以是以下其中之一: read, write

security_eventsstring

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

可以是以下其中之一: read, write

single_filestring

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

可以是以下其中之一: read, write

statusesstring

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

可以是以下其中之一: read, write

vulnerability_alertsstring

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

可以是以下其中之一: read, write

workflowsstring

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

可以是以下其中之一: write

membersstring

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

可以是以下其中之一: read, write

organization_administrationstring

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

可以是以下其中之一: read, write

organization_hooksstring

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

可以是以下其中之一: read, write

organization_planstring

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

可以是以下其中之一: read

organization_projectsstring

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

可以是以下其中之一: read, write, admin

organization_packagesstring

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

可以是以下其中之一: read, write

organization_secretsstring

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

可以是以下其中之一: 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.

可以是以下其中之一: read, write

organization_user_blockingstring

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

可以是以下其中之一: read, write

team_discussionsstring

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

可以是以下其中之一: read, write

content_referencesstring

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

可以是以下其中之一: read, write

HTTP 响应状态代码

状态代码描述
200

OK

401

Requires authentication

403

Forbidden

404

Resource not found

422

Validation failed

代码示例

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.

参数

标头
名称, 类型, 描述
acceptstring

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

路径参数
名称, 类型, 描述
client_idstring必选

The client ID of the GitHub app.

access_tokenstring必选

HTTP 响应状态代码

状态代码描述
200

OK

404

Resource not found

代码示例

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.

参数

标头
名称, 类型, 描述
acceptstring

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

路径参数
名称, 类型, 描述
client_idstring必选

The client ID of the GitHub app.

access_tokenstring必选

HTTP 响应状态代码

状态代码描述
200

OK

代码示例

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.

参数

标头
名称, 类型, 描述
acceptstring

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

路径参数
名称, 类型, 描述
client_idstring必选

The client ID of the GitHub app.

access_tokenstring必选

HTTP 响应状态代码

状态代码描述
204

No Content

代码示例

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