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:

application/vnd.github.mirage-preview+json

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

<div class="alert">

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

<p>

The <code>token</code> attribute is <a href="/v3/versions/#v3-deprecations">deprecated</a> in all

of the following OAuth Authorizations API responses:

</p>

<ul>

<li><a href="#list-your-authorizations">List your authorizations</a></li>

<li><a href="#get-a-single-authorization">Get a single authorization</a></li>

<li><a href="#get-or-create-an-authorization-for-a-specific-app">Get-or-create an authorization for a specific app</a> - <code>token</code> is still returned for "create" </li>

<li><a href="#get-or-create-an-authorization-for-a-specific-app-and-fingerprint">Get-or-create an authorization for a specific app and fingerprint</a> - <code>token</code> is still returned for "create" </li>

<li><a href="#update-an-existing-authorization">Update an existing authorization</a></li>

</ul>

<p>

Please see <a href="/changes/2014-12-08-removing-authorizations-token/">the blog post</a> for full details.

</p>

<p>

In order to reduce the impact of removing the <code>token</code> attribute,

the OAuth Authorizations API has added a new request attribute

(<code>fingerprint</code>), added three new response attributes

(<code>token_last_eight</code>, <code>hashed_token</code>, and

<code>fingerprint</code>), and added

<a href="#get-or-create-an-authorization-for-a-specific-app-and-fingerprint">one new API</a>.

</p>

<p>

To access the new API functionality during the preview period, you must

provide a custom <a href="/v3/media/">media type</a> in the

<code>Accept</code> header:

<pre>application/vnd.github.mirage-preview+json</pre>

</p>

</div>

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

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

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

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].

`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(:oauth_access) { |h| h.merge("fingerprint" => "") } %>

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

requesting the token. It returns the user's existing authorization for the

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

`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(:oauth_access) { |h| h.merge("fingerprint" => "") } %>

<%= 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.

PUT /authorizations/clients/:client_id/:fingerprint

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"

%>

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

%>

<%= json(:oauth_access) { |h| h.merge("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(:oauth_access) { |h| h.merge("token" => "") } %>

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.

"token" => "abcdefgh12345678",

"token_last_eight" => "12345678",

"hashed_token" => "JflKKlx/uvSZxmW8c9Z8HIfkltqJhRMWM+4KlYGdsug=",

"created_at" => "2011-09-06T17:26:27Z",

"fingerprint" => "jklmnop12345678",