REST API endpoints for OAuth authorizations

You can use these endpoints to manage the OAuth tokens that OAuth apps or Apps use to access people's accounts on .

Tokens for OAuth apps have the prefix gho_, while OAuth tokens for Apps, used for authenticating on behalf of the user, have the prefix ghu_. You can use the following endpoints for both types of OAuth tokens.

OAuth and application owners can revoke a grant for their application and a specific user. You must provide a valid OAuth access_token as an input parameter and the grant for the token's owner will be deleted. Deleting an 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 .

Basic authentication for "Delete an app authorization"

You must use Basic Authentication to use this endpoint. Use the application's client_id as the username and the client_secret as the password.

Parameters for "Delete an app authorization"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.+json` is recommended.

Path parameters
Name, Type, Description
`client_id` string Required The client ID of the app.

Body parameters
Name, Type, Description
`access_token` string Required The OAuth access token used to authenticate to the API.

HTTP response status codes for "Delete an app authorization"

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

Code samples for "Delete an app authorization"

If you access at GHE.com, replace api..com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

delete/applications/{client_id}/grant

curl -L \ -X DELETE \ -H "Accept: application/vnd.+json" \ -u "<YOUR_CLIENT_ID>:<YOUR_CLIENT_SECRET>" \ -H "X--Api-Version: 2022-11-28" \ https://api..com/applications/Iv1.8a61f9b3a7aba766/grant \ -d '{"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a"}'

Response

Status: 204

OAuth applications and applications with OAuth authorizations can use this API method for checking OAuth token validity without exceeding the normal rate limits for failed login attempts. Authentication works differently with this particular endpoint. Invalid tokens will return 404 NOT FOUND.

Basic authentication for "Check a token"

You must use Basic Authentication to use this endpoint. Use the application's client_id as the username and the client_secret as the password.

Parameters for "Check a token"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.+json` is recommended.

Path parameters
Name, Type, Description
`client_id` string Required The client ID of the app.

Body parameters
Name, Type, Description
`access_token` string Required The access_token of the OAuth or application.

HTTP response status codes for "Check a token"

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

Code samples for "Check a token"

If you access at GHE.com, replace api..com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

post/applications/{client_id}/token

curl -L \ -X POST \ -H "Accept: application/vnd.+json" \ -u "<YOUR_CLIENT_ID>:<YOUR_CLIENT_SECRET>" \ -H "X--Api-Version: 2022-11-28" \ https://api..com/applications/Iv1.8a61f9b3a7aba766/token \ -d '{"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a"}'

Response

Status: 200

{ "id": 1, "url": "https://api..com/authorizations/1", "scopes": [ "public_repo", "user" ], "token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a", "token_last_eight": "Ae178B4a", "hashed_token": "25f94a2a5c7fbaf499c665bc73d67c1c87e496da8985131633ee0a95819db2e8", "app": { "url": "http://my--app.com", "name": "my 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://.com/images/error/octocat_happy.gif", "gravatar_id": "", "url": "https://api..com/users/octocat", "html_url": "https://.com/octocat", "followers_url": "https://api..com/users/octocat/followers", "following_url": "https://api..com/users/octocat/following{/other_user}", "gists_url": "https://api..com/users/octocat/gists{/gist_id}", "starred_url": "https://api..com/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://api..com/users/octocat/subscriptions", "organizations_url": "https://api..com/users/octocat/orgs", "repos_url": "https://api..com/users/octocat/repos", "events_url": "https://api..com/users/octocat/events{/privacy}", "received_events_url": "https://api..com/users/octocat/received_events", "type": "User", "site_admin": false } }

OAuth applications and applications with OAuth authorizations 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. Invalid tokens will return 404 NOT FOUND.

Basic authentication for "Reset a token"

You must use Basic Authentication to use this endpoint. Use the application's client_id as the username and the client_secret as the password.

Parameters for "Reset a token"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.+json` is recommended.

Path parameters
Name, Type, Description
`client_id` string Required The client ID of the app.

Body parameters
Name, Type, Description
`access_token` string Required The access_token of the OAuth or application.

HTTP response status codes for "Reset a token"

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

Code samples for "Reset a token"

If you access at GHE.com, replace api..com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

/applications/{client_id}/token

curl -L \ -X \ -H "Accept: application/vnd.+json" \ -u "<YOUR_CLIENT_ID>:<YOUR_CLIENT_SECRET>" \ -H "X--Api-Version: 2022-11-28" \ https://api..com/applications/Iv1.8a61f9b3a7aba766/token \ -d '{"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a"}'

Response

Status: 200

{ "id": 1, "url": "https://api..com/authorizations/1", "scopes": [ "public_repo", "user" ], "token": "ghu_16C7e42F292c6912E7710c838347Ae178B4a", "token_last_eight": "Ae178B4a", "hashed_token": "25f94a2a5c7fbaf499c665bc73d67c1c87e496da8985131633ee0a95819db2e8", "app": { "url": "http://my--app.com", "name": "my 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://.com/images/error/octocat_happy.gif", "gravatar_id": "", "url": "https://api..com/users/octocat", "html_url": "https://.com/octocat", "followers_url": "https://api..com/users/octocat/followers", "following_url": "https://api..com/users/octocat/following{/other_user}", "gists_url": "https://api..com/users/octocat/gists{/gist_id}", "starred_url": "https://api..com/users/octocat/starred{/owner}{/repo}", "subscriptions_url": "https://api..com/users/octocat/subscriptions", "organizations_url": "https://api..com/users/octocat/orgs", "repos_url": "https://api..com/users/octocat/repos", "events_url": "https://api..com/users/octocat/events{/privacy}", "received_events_url": "https://api..com/users/octocat/received_events", "type": "User", "site_admin": false } }

OAuth or application owners can revoke a single token for an OAuth application or a application with an OAuth authorization.

Basic authentication for "Delete an app token"

You must use Basic Authentication to use this endpoint. Use the application's client_id as the username and the client_secret as the password.

Parameters for "Delete an app token"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.+json` is recommended.

Path parameters
Name, Type, Description
`client_id` string Required The client ID of the app.

Body parameters
Name, Type, Description
`access_token` string Required The OAuth access token used to authenticate to the API.

HTTP response status codes for "Delete an app token"

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

Code samples for "Delete an app token"

If you access at GHE.com, replace api..com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

delete/applications/{client_id}/token

curl -L \ -X DELETE \ -H "Accept: application/vnd.+json" \ -u "<YOUR_CLIENT_ID>:<YOUR_CLIENT_SECRET>" \ -H "X--Api-Version: 2022-11-28" \ https://api..com/applications/Iv1.8a61f9b3a7aba766/token \ -d '{"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a"}'

Response

Status: 204