You can specify terminal blocks with`pre.terminal` elements. (It'd be

nice ifMarkdown could do this more cleanly.)

You can specify terminal blocks with`pre.terminal` elements. (It'd be nice if

Markdown could do this more cleanly.)

<preclass="terminal">

kind:change

title:Removing token attribute from Authorizations API responses

created_at:2014-12-08

author_name:ptoomey3

Since OAuth access tokens function like passwords, they should be treated with

care. Today we are making it easier to more securely work with authorizations

via the Authorizations API. We are deprecating the use use of the`token`

attribute in the majority of the[Authorizations API](/v3/oauth_authorizations/)

responses. For the[affected APIs][authorizations-token-deprecation-notice], the

`token` attribute will soon return an empty string. To get ready for that

change, we are giving developers a chance to

[preview the updated API](#preview-period) starting today.

The current[OAuth Authorizations API](/v3/oauth_authorizations/) requires GitHub to store the full value for

each OAuth token on our servers. In order to increase the security for our

users, we are changing our architecture to store the SHA-256 digest of OAuth

tokens instead. GitHub securely hashes user passwords using bcrypt and we want

to provide comparable security for OAuth tokens as well.

Rest assured that this change is an entirely proactive measure from GitHub and is not associated with any security incident.

This change affects any code that relies on accessing the`token` attribute from

[these OAuth Authorizations API responses][authorizations-token-deprecation-notice].

For example, our own[GitHub for Mac][github-for-mac] and

[GitHub for Windows][github-for-windows] applications relied on reading the`token`

from the[Get-or-create an authorization for a specific app][get-or-create-for-app] API, in order to support multiple installations of our desktop application for a single user.

In order to reduce the impact of removing the`token` attribute, the OAuth

Authorizations API has added a new request attribute (`fingerprint`), added

three new response attributes (`token_last_eight`,`hashed_token`, and

`fingerprint`), and added[one new API][get-or-create-for-app-fingerprint].

While these new APIs and attributes do not replace the full functionality that

previously existed, they can be used in place of`token` for most common use cases.

*`token_last_eight` returns the last eight characters of the associated OAuth

token. As an example,`token_last_eight` could be used to display a list of

partial token values to help a user manage their OAuth tokens.

*`hashed_token` is the base64 of the SHA-256 digest of the token.

`hashed_token` could be used to programmatically validate that a given token

matches an authorization returned by the API.

*`fingerprint` is a new optional request parameter that allows an OAuth

application to create multiple authorizations for a single user.`fingerprint`

should be a string that distinguishes the new authorization from others

for the same client ID and user.

For example, to differentiate installations of a desktop application across

multiple devices you might set`fingerprint` to

`SHA256_HEXDIGEST("GitHub for Mac - MAC_ADDRESS_OF_MACHINE")`. Since

`fingerprint` is not meant to be a user-facing value, you should still set

the`note` attribute to help a user differentiate between authorizations on their

[OAuth applications listing on GitHub][app-listing].

*[Get-or-create an authorization for a specific app and fingerprint][get-or-create-for-app-fingerprint]

is a new API that is analagous to the

[Get-or-create an authorization for a specific app][get-or-create-for-app]

API, but adds support for the new`fingerprint` request parameter.

We are making the new Authorizations API available today for developers to

preview. During this period, we may change aspects of these endpoints. If we do,

we will announce the changes on the developer blog, but we will not provide any

advance notice.

While these new APIs are in their preview period, you’ll need to provide the

following custom media type in the Accept header:

We expect the preview period to last 4-6 weeks. (Stay tuned to the developer blog for updates.) At the end of the preview period, these changes will become an official and stable part of GitHub API.

At the end of the preview period, we will announce the start of a migration period. Developers will have 8 weeks to update existing code to use the new APIs.

Some users may be curious why we are not using bcrypt to hash our OAuth tokens

like we do for user passwords. Bcrypt is purposefully computationally expensive

in order to mitigate brute force attacks against low entropy passwords. However,

OAuth tokens are highly random and are not susceptible to brute force attacks.

Given that OAuth token validation occurs for each request to the API we chose

SHA-256 for performance reasons.

If you have any questions or feedback, please[drop us a line][contact].

[contact]:https://github.com/contact?form[subject]=Removing+authorizations+token

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

[create-a-new-authorization]:/v3/oauth_authorizations/#create-a-new-authorization

[get-or-create-for-app]:/v3/oauth_authorizations/#get-or-create-an-authorization-for-a-specific-app

[get-or-create-for-app-fingerprint]:/v3/oauth_authorizations/#get-or-create-an-authorization-for-a-specific-app-and-fingerprint

[github-for-mac]:https://mac.github.com/

[github-for-windows]:https://windows.github.com/

[authorizations-token-deprecation-notice]:/v3/oauth_authorizations/#deprecation-notice

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.

<divclass="alert">

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

<p>

</p>

<ul>

</ul>

<p>

</p>

<p>

</p>

<p>

</p>

</div>

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

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

<%= json(:oauth_access) { |h|[h.merge("token" => "")] } %>

<%= headers 200 %>

<%= json:oauth_access %>

<%= json(:oauth_access) { |h| h.merge("token" => "") } %>

If you need a small number of tokens, implementing the[web flow](/v3/oauth/#web-application-flow)

can be cumbersome. Instead, tokens can be created using the Authorizations API using

can be cumbersome. Instead, tokens can be created using theOAuthAuthorizations API using

[Basic Authentication](/v3/auth#basic-authentication). To create tokens for a particular OAuth application, you

must provide its client ID and secret, found on the OAuth application settings

page, linked from your[OAuth applications listing on GitHub][app-listing]. OAuth tokens

can also be created through the web UI via the[Application settings page](https://github.com/settings/applications).

page, linked from your[OAuth applications listing on GitHub][app-listing].If your OAuth applicaion intends to create multiple tokens for one user you should use`fingerprint` to differentiate between them.OAuth tokens

can also be created through the web UI via the[Application settings page][app-listing].

Read more about these tokens on the[GitHub Help page](https://help.github.com/articles/creating-an-access-token-for-command-line-use).

`note_url`|`string` | A URL to remind you what app the OAuth token is for.

`client_id`|`string` | The 20 character OAuth app client key for which to create the token.

`client_secret`|`string` | The 40 character OAuth app client secret for which to create the token.

`fingerprint`|`string` |**This attribute is only available when using the[mirage-preview](#deprecation-notice) media type.** A unique string to distinguish an authorization from others created for the same client ID and user.

<%= json:scopes =>["public_repo"],:note => 'admin script' %>

<%= headers 201,:Location => "https://api.github.com/authorizations/1"

%>

<%= json:oauth_access %>

<%= json(:oauth_access) { |h| h.merge("fingerprint" => "") } %>

This method will create a new authorization for the specified OAuth application,

only if an authorization for that application doesn't already exist for the

user.(The URL includes the 20 character client ID for the OAuth app that is

requesting the token.) It returns the user'stokenfor the application if one

exists. Otherwise, it creates one.

user. The URL includes the 20 character client ID for the OAuth app that is

requesting the token. It returns the user'sexisting authorizationfor the

application if one is present. Otherwise, it creates and returns a new one.

`scopes`|`array` | A list of scopes that this authorization is in.

`note`|`string` | A note to remind you what the OAuth token is for.

`note_url`|`string` | A URL to remind you what app the OAuth token is for.

`fingerprint`|`string` |**This attribute is only available when using the[mirage-preview](#deprecation-notice) media type.** A unique string to distinguish an authorization from others created for the same client and user. If provided, this API is functionally equivalent to[Get-or-create an authorization for a specific app and fingerprint](/v3/oauth_authorizations/#get-or-create-an-authorization-for-a-specific-app-and-fingerprint).

<%= json:client_secret => "abcdabcdabcdabcdabcdabcdabcdabcdabcdabcd",:scopes =>["public_repo"],:note => 'admin script' %>

<%= headers 201,:Location => "https://api.github.com/authorizations/1"

%>

<%= json:oauth_access %>

<%= json(:oauth_access) { |h| h.merge("fingerprint" => "") } %>

<%= headers 200,:Location => "https://api.github.com/authorizations/1"

%>

<%= json(:oauth_access) { |h| h.merge("token" => "", "fingerprint" => "") } %>

**This API method is only available when using the

[mirage-preview](#deprecation-notice) media type.**

This method will create a new authorization for the specified OAuth application,

only if an authorization for that application and fingerprint do not already

exist for the user. The URL includes the 20 character client ID for the OAuth

app that is requesting the token.`fingerprint` is a unique string to

distinguish an authorization from others created for the same client ID and

user. It returns the user's existing authorization for the application if one

is present. Otherwise, it creates and returns a new one.

Name | Type | Description

-----|------|--------------

`client_secret`|`string`|**Required**. The 40 character OAuth app client secret associated with the client ID specified in the URL.

`scopes`|`array` | A list of scopes that this authorization is in.

`note`|`string` | A note to remind you what the OAuth token is for.

`note_url`|`string` | A URL to remind you what app the OAuth token is for.

<%= json:client_secret => "abcdabcdabcdabcdabcdabcdabcdabcdabcdabcd",:scopes =>["public_repo"],:note => 'admin script' %>

<%= headers 201,:Location => "https://api.github.com/authorizations/1"

%>

<%= json:oauth_access %>

<%= headers 200,:Location => "https://api.github.com/authorizations/1"

%>

<%= json(:oauth_access) { |h| h.merge("token" => "") } %>

`remove_scopes`|`array` | A list of scopes to remove from this authorization.

`note`|`string` | A note to remind you what the OAuth token is for.

`note_url`|`string` | A URL to remind you what app the OAuth token is for.

`fingerprint`|`string` |**This attribute is only available when using the[mirage-preview](#deprecation-notice) media type.** A unique string to distinguish an authorization from others created for the same client ID and user.

You can only send one of these scope keys at a time.

<%= headers 200 %>

<%= json:oauth_access %>

<%= json(:oauth_access) { |h| h.merge("token" => "") } %>

use the[standard`per_page` and`page` parameters](/v3/#pagination) for pagination, instead of`per_page`,

`top`, and`sha`.

1. Authorization attribute: token

: Recommendation: This attribute will return an empty string in the majority of

the Authorizations API responses. Please see

[the deprecation blog post](/changes/2014-12-08-removing-authorizations-token/)

and the[Authorizations API deprecation notice](/v3/oauth_authorizations/#deprecation-notice)

for full details.

The[beta API](/v3) is deprecated. Its current functionality is stable and unchangeable. Please[file a support issue][support] if you have problems.

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