title:Preview support for OAuth authorizations grants API

author_name:ptoomey3

GitHub recently made changes to[the application authorizations settings screen within GitHub][authorized-application-listing] to display one entry for each OAuth application a user has authorized. Previously this screen showed one entry for each OAuth token that was generated by an OAuth application. For example, if you installed two instances of GitHub Desktop, you would see one entry for each installation. To simplify OAuth application management, we now show a single entry for each OAuth application. For OAuth applications that use the[web flow][web-flow] this was not a problem, since the web flow never generates more than one token for a given OAuth application and user. However, going forward, GitHub would like to allow all OAuth applications, including those that use the web flow, to generate more than one token.

In preparation for that change, we are adding API support to simplify management of OAuth applications that matches what is available on GitHub.com. You can enable these changes during the preview period by providing a custom[media type][media-type] in the`Accept` header:

For example:

You can learn more about the new APIs in the[OAuth authorizations][oauth-authorizations-api] documentation.

During the preview period, we may change aspects of these APIs based on developer feedback. We will announce the changes here on the developer blog, but we will not provide advance notice.

If you have any questions or feedback, please[let us know][contact].

[media-type]:/v3/media

[oauth-authorizations-api]:/v3/oauth_authorizations

[authorized-application-listing]:https://github.com/settings/applications#authorized

[contact]:https://github.com/contact?form%5Bsubject%5D=OAuth+Authorizations+Grants+API+Preview

[web-flow]:/v3/oauth/#web-application-flow

title:Authorizations

{:toc}

{{#tip}}

Make sure you understand how to[work with two-factor authentication](/v3/auth/#working-with-two-factor-authentication) if you or your users have two-factor authentication enabled.

APIs for managing OAuth grants are currently available for developers to preview.

During the preview period, the APIs may change without advance notice.

Please see the[blog post](/changes/2016-04-21-oauth-authorizations-grants-api-preview) for full details.

To access the API you must provide a custom[media type](/v3/media) in the`Accept` header:

{{/tip}}

{% endif %}

<br>

<divclass="alert">

<h3id="deprecation-notice">Deprecation Notice</h3>

</p>

</div>

{:toc}

You can use this API to manage the access OAuth applications have to your account. You can only access this API via[Basic Authentication](/v3/auth#basic-authentication) using your username and password, not tokens.

Make sure you understand how to[work with two-factor authentication](/v3/auth/#working-with-two-factor-authentication) if you or your users have two-factor authentication enabled.

{% if page.version == 'dotcom' or page.version > 2.6 %}

You can use this API to list the set of OAuth applications that have been granted access to your account. Unlike the[list your authorizations](/v3/oauth_authorizations/#list-your-authorizations) API, this API does not manage individual tokens. This API will return one entry for each OAuth application that has been granted access to your account, regardless of the number of tokens an application has generated for your user. The list of OAuth applications returned matches what is shown on[the application authorizations settings screen within GitHub][authorized-application-listing]. The`scopes` returned are the union of scopes authorized for the application. For example, if an application has one token with`repo` scope and another token with`user` scope, the grant will return`["repo", "user"]`.

<%= headers 200,:pagination => default_pagination_rels %>

<%= json(:oauth_authorization) { |h|[h] } %>

<%= headers 200 %>

<%= json(:oauth_authorization) %>

Deleting an OAuth application's grant will also delete all OAuth tokens associated with the application for your user. Once deleted, the application has no access to your account and is no longer listed on[the application authorizations settings screen within GitHub][authorized-application-listing].

<%= headers 204 %>

{% endif %}

[app-listing]:https://github.com/settings/developers

[tokens-listing]:https://github.com/settings/tokens

[authorized-application-listing]:https://github.com/settings/applications#authorized

[basics auth guide]:/guides/basics-of-authentication/

OAUTH_ACCESS_WITH_USER ||=OAUTH_ACCESS.merge(:user=>USER)

OAUTH_AUTHORIZATION ||={