developer.github.com/v3/oauth/index.html at webhook-header-docs · JavaLeaks/developer.github.com

963 lines (839 loc) · 45.7 KB
<!DOCTYPE html>
<html lang="en">
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  <meta http-equiv="Content-Language" content="en-us" />
  <meta http-equiv="imagetoolbar" content="false" />
  <meta name="MSSmartTagsPreventParsing" content="true" />
  <title>OAuth | GitHub API</title>
  <link rel="alternate" type="application/atom+xml" title="API Changes" href="/changes.atom" />
  <link href="/css/reset.css" rel="stylesheet" type="text/css" />
  <link href="/css/960.css" rel="stylesheet" type="text/css" />
  <link href="/css/uv_active4d.css" rel="stylesheet" type="text/css" />
  <link href="/shared/css/documentation.css" media="screen" rel="stylesheet" type="text/css">
  <link href="/shared/css/pygments.css" media="screen" rel="stylesheet" type="text/css">
  <script src="/shared/js/jquery.js" type="text/javascript"></script>
  <script src="/shared/js/documentation.js" type="text/javascript"></script>
<body class="api">
	<div id="header-wrapper">
  <div id="header">
      <a class="logo" href="/">GitHub:Developer</a>
      <ul class="nav">
        <li><a href="/" class="nav-overview">Overview</a></li>
        <li><a href="/v3/" class="nav-api">API</a></li>
        <li><a href="/changes/" class="nav-blog">Blog</a></li>
        <li><a href="https://github.com/contact">Support</a></li>
        <li id="search-container">
          <input type="text" id="searchfield" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" /><label class="search-placeholder">Search</label>
          <div class="cancel-search"></div>
          <ul id="search-results">
          </ul>
        </li>
      </ul>
  </div><!-- #header -->
</div><!-- #header-wrapper -->
	<div class="sub-nav">
		<h2><a href="/v3/">API</a></h2>
      <li><a href="/v3/" class="active">Documentation</a></li>
      <li><a href="/guides/">Guides</a></li>
      <li><a href="/libraries/">Libraries</a></li>
  <div id="wrapper">
  	<div class="content">
    	<h1 id="oauth">OAuth</h1>
<ul id="markdown-toc">
  <li><a href="#web-application-flow">Web Application Flow</a></li>
  <li><a href="#non-web-application-flow">Non-Web Application Flow</a></li>
  <li><a href="#redirect-urls">Redirect URLs</a></li>
  <li><a href="#scopes">Scopes</a></li>
  <li><a href="#oauth-authorizations-api">OAuth Authorizations API</a></li>
  <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="#create-a-new-authorization">Create a new 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></li>
  <li><a href="#update-an-existing-authorization">Update an existing authorization</a></li>
  <li><a href="#delete-an-authorization">Delete an authorization</a></li>
  <li><a href="#check-an-authorization">Check an authorization</a></li>
  <li><a href="#revoke-all-authorizations-for-an-application">Revoke all authorizations for an application</a></li>
  <li><a href="#revoke-an-authorization-for-an-application">Revoke an authorization for an application</a></li>
  <li><a href="#more-information">More Information</a></li>
<p>OAuth2 is a protocol that lets external apps request authorization to
private details in a user’s GitHub account without getting their
password. This is preferred over <a href="/v3/auth#basic-authentication">Basic Authentication</a> because tokens can
be limited to specific types of data, and can be revoked by users at any
<p>All developers need to <a href="https://github.com/settings/applications/new">register their
application</a> before getting
started. A registered OAuth application is assigned a unique Client ID
and Client Secret. The Client Secret should not be shared.</p>
<h2 id="web-application-flow">Web Application Flow</h2>
<p>This is a description of the OAuth2 flow from 3rd party web sites.</p>
<h3 id="redirect-users-to-request-github-access">1. Redirect users to request GitHub access</h3>
<pre><code>GET https://github.com/login/oauth/authorize
</code></pre>
<h3 id="parameters">Parameters</h3>
      <th>Name</th>
      <th>Type</th>
      <th>Description</th>
      <td><code>client_id</code></td>
      <td><code>string</code></td>
<strong>Required</strong>. The client ID you received from GitHub when you <a href="https://github.com/settings/applications/new">registered</a>.</td>
      <td><code>redirect_uri</code></td>
      <td><code>string</code></td>
      <td>The URL in your app where users will be sent after authorization. See details below about <a href="#redirect-urls">redirect urls</a>.</td>
      <td><code>scope</code></td>
      <td><code>string</code></td>
      <td>A comma separated list of <a href="#scopes">scopes</a>. If not provided, <code>scope</code> defaults to an empty list of scopes for users that don’t have a valid token for the app. For users who do already have a valid token for the app, the user won’t be shown the OAuth authorization page with the list of scopes. Instead, this step of the flow will automatically complete with the same scopes that were used last time the user completed the flow.</td>
      <td><code>state</code></td>
      <td><code>string</code></td>
      <td>An unguessable random string. It is used to protect against cross-site request forgery attacks.</td>
<h3 id="github-redirects-back-to-your-site">2. GitHub redirects back to your site</h3>
<p>If the user accepts your request, GitHub redirects back to your site
with a temporary code in a <code>code</code> parameter as well as the state you provided in
the previous step in a <code>state</code> parameter. If the states don’t match, the request
has been created by a third party and the process should be aborted.</p>
<p>Exchange this for an access token:</p>
<pre><code>POST https://github.com/login/oauth/access_token
</code></pre>
<h3 id="parameters-1">Parameters</h3>
      <th>Name</th>
      <th>Type</th>
      <th>Description</th>
      <td><code>client_id</code></td>
      <td><code>string</code></td>
<strong>Required</strong>. The client ID you received from GitHub when you <a href="https://github.com/settings/applications/new">registered</a>.</td>
      <td><code>client_secret</code></td>
      <td><code>string</code></td>
<strong>Required</strong>. The client secret you received from GitHub when you <a href="https://github.com/settings/applications/new">registered</a>.</td>
      <td><code>code</code></td>
      <td><code>string</code></td>
<strong>Required</strong>. The code you received as a response to <a href="#redirect-users-to-request-github-access">Step 1</a>.</td>
      <td><code>redirect_uri</code></td>
      <td><code>string</code></td>
      <td>The URL in your app where users will be sent after authorization. See details below about <a href="#redirect-urls">redirect urls</a>.</td>
<h3 id="response">Response</h3>
<p>By default, the response will take the following form:</p>
<pre><code>access_token=e72e16c7e42f292c6912e7710c838347ae178b4a&amp;scope=user%2Cgist&amp;token_type=bearer
</code></pre>
<p>You can also receive the content in different formats depending on the Accept
header:</p>
<pre><code>Accept: application/json
{"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a", "scope":"repo,gist", "token_type":"bearer"}
Accept: application/xml
&lt;OAuth&gt;
  &lt;token_type&gt;bearer&lt;/token_type&gt;
  &lt;scope&gt;repo,gist&lt;/scope&gt;
  &lt;access_token&gt;e72e16c7e42f292c6912e7710c838347ae178b4a&lt;/access_token&gt;
&lt;/OAuth&gt;
</code></pre>
<h4 id="requested-scopes-vs-granted-scopes">Requested scopes vs. granted scopes</h4>
<p>The <code>scope</code> attribute lists scopes attached to the token that were granted by
the user. Normally, these scopes will be identical to what you requested.
However, users <a href="/changes/2013-10-04-oauth-changes-coming/">will soon be able to edit their scopes</a>, effectively
granting your application less access than you originally requested. Also, users
will also be able to edit token scopes after the OAuth flow completed.
You should be aware of this possibility and adjust your application’s behavior
accordingly.</p>
<p>It is important to handle error cases where a user chooses to grant you
less access than you originally requested. For example, applications can warn
or otherwise communicate with their users that they will see reduced
functionality or be unable to perform some actions.</p>
<p>Also, applications can always send users back through the flow again to get
additional permission, but don’t forget that users can always say no.</p>
<p>Check out the <a href="/guides/basics-of-authentication/">Basics of Authentication guide</a> which
provides tips on handling modifiable token scopes.</p>
<h3 id="use-the-access-token-to-access-the-api">3. Use the access token to access the API</h3>
<p>The access token allows you to make requests to the API on a behalf of a user.</p>
<pre><code>GET https://api.github.com/user?access_token=...
</code></pre>
<h2 id="non-web-application-flow">Non-Web Application Flow</h2>
<p>Use <a href="/v3/auth#basic-authentication">Basic Authentication</a> to create an OAuth2
token using the <a href="/v3/oauth/#create-a-new-authorization">interface below</a>.  With
this technique, a username and password need not be stored permanently, and the
user can revoke access at any time. (Make sure to understand how to <a href="/v3/auth/#working-with-two-factor-authentication">work with
two-factor authentication</a> if
you or your users have two-factor authentication enabled.)</p>
<h2 id="redirect-urls">Redirect URLs</h2>
<p>The <code>redirect_uri</code> parameter is optional. If left out, GitHub will
redirect users to the callback URL configured in the OAuth Application
settings. If provided, the redirect URL’s host and port must exactly
match the callback URL. The redirect URL’s path must reference a
subdirectory of the callback URL.</p>
<pre><code>CALLBACK: http://example.com/path
GOOD: https://example.com/path
GOOD: http://example.com/path/subdir/other
BAD:  http://example.com/bar
BAD:  http://example.com/
BAD:  http://example.com:8080/path
BAD:  http://oauth.example.com:8080/path
BAD:  http://example.org
</code></pre>
<h2 id="scopes">Scopes</h2>
<p>Scopes let you specify exactly what type of access you need. Scopes <em>limit</em>
access for OAuth tokens. They do not grant any additional permission beyond
that which the user already has.</p>
<p>For the web flow, requested scopes will be displayed to the user on the
authorize form.</p>
<p>Check headers to see what OAuth scopes you have, and what the API action
accepts.</p>
<pre><code>$ curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com/users/technoweenie -I
HTTP/1.1 200 OK
X-OAuth-Scopes: repo, user
X-Accepted-OAuth-Scopes: user
</code></pre>
<p><code>X-OAuth-Scopes</code> lists the scopes your token has authorized.
<code>X-Accepted-OAuth-Scopes</code> lists the scopes that the action checks for.</p>
      <th>Name</th>
      <th>Description</th>
      <td><code>(no scope)</code></td>
      <td>Public read-only access (includes public user profile info, public repo info, and gists)</td>
      <td><code>user</code></td>
      <td>Read/write access to profile info only.  Note: this scope includes <code>user:email</code> and <code>user:follow</code>.</td>
      <td><code>user:email</code></td>
      <td>Read access to a user’s email addresses.</td>
      <td><code>user:follow</code></td>
      <td>Access to follow or unfollow other users.</td>
      <td><code>public_repo</code></td>
      <td>Read/write access to public repos and organizations.</td>
      <td><code>repo</code></td>
      <td>Read/write access to public and private repos and organizations.</td>
      <td><code>repo:status</code></td>
      <td>Read/write access to public and private repository commit statuses. This scope is only necessary to grant other users or services access to private repository commit statuses without granting access to the code. The <code>repo</code> and <code>public_repo</code> scopes already include access to commit status for private and public repositories, respectively.</td>
      <td><code>delete_repo</code></td>
      <td>Delete access to adminable repositories.</td>
      <td><code>notifications</code></td>
      <td>Read access to a user’s notifications.  <code>repo</code> is accepted too.</td>
      <td><code>gist</code></td>
      <td>Write access to gists.</td>
<p>NOTE: Your application can request the scopes in the initial redirection. You
can specify multiple scopes by separating them with a comma:</p>
<pre><code>https://github.com/login/oauth/authorize?
  client_id=...&amp;
  scope=user,public_repo
</code></pre>
<h2 id="oauth-authorizations-api">OAuth Authorizations API</h2>
<p>There is an API for users to manage their own tokens.  You can only access your
own tokens, and only via <a href="/v3/auth#basic-authentication">Basic Authentication</a>.
(Make sure to understand how to <a href="/v3/auth/#working-with-two-factor-authentication">work with two-factor
authentication</a> if you or your
users have two-factor authentication enabled.)</p>
<h2 id="list-your-authorizations">List your authorizations</h2>
<pre><code>GET /authorizations
</code></pre>
<h3 id="response-1">Response</h3>
<pre class="headers"><code>Status: 200 OK
Link: &lt;https://api.github.com/resource?page=2&gt;; rel="next",
      &lt;https://api.github.com/resource?page=5&gt;; rel="last"
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999</code></pre>
<pre><code class="language-javascript"><span class="p">[</span>
  <span class="p">{</span>
    <span class="s2">"id"</span><span class="o">:</span> <span class="mi">1</span><span class="p">,</span>
    <span class="s2">"url"</span><span class="o">:</span> <span class="s2">"https://api.github.com/authorizations/1"</span><span class="p">,</span>
    <span class="s2">"scopes"</span><span class="o">:</span> <span class="p">[</span>
      <span class="s2">"public_repo"</span>
    <span class="p">],</span>
    <span class="s2">"token"</span><span class="o">:</span> <span class="s2">"abc123"</span><span class="p">,</span>
    <span class="s2">"app"</span><span class="o">:</span> <span class="p">{</span>
      <span class="s2">"url"</span><span class="o">:</span> <span class="s2">"http://my-github-app.com"</span><span class="p">,</span>
      <span class="s2">"name"</span><span class="o">:</span> <span class="s2">"my github app"</span><span class="p">,</span>
      <span class="s2">"client_id"</span><span class="o">:</span> <span class="s2">"abcde12345fghij67890"</span>
    <span class="p">},</span>
    <span class="s2">"note"</span><span class="o">:</span> <span class="s2">"optional note"</span><span class="p">,</span>
    <span class="s2">"note_url"</span><span class="o">:</span> <span class="s2">"http://optional/note/url"</span><span class="p">,</span>
    <span class="s2">"updated_at"</span><span class="o">:</span> <span class="s2">"2011-09-06T20:39:23Z"</span><span class="p">,</span>
    <span class="s2">"created_at"</span><span class="o">:</span> <span class="s2">"2011-09-06T17:26:27Z"</span>
  <span class="p">}</span>
<span class="p">]</span></code></pre>
<h2 id="get-a-single-authorization">Get a single authorization</h2>
<pre><code>GET /authorizations/:id
</code></pre>
<h3 id="response-2">Response</h3>
<pre class="headers"><code>Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999</code></pre>
<pre><code class="language-javascript"><span class="p">{</span>
  <span class="s2">"id"</span><span class="o">:</span> <span class="mi">1</span><span class="p">,</span>
  <span class="s2">"url"</span><span class="o">:</span> <span class="s2">"https://api.github.com/authorizations/1"</span><span class="p">,</span>
  <span class="s2">"scopes"</span><span class="o">:</span> <span class="p">[</span>
    <span class="s2">"public_repo"</span>
  <span class="p">],</span>
  <span class="s2">"token"</span><span class="o">:</span> <span class="s2">"abc123"</span><span class="p">,</span>
  <span class="s2">"app"</span><span class="o">:</span> <span class="p">{</span>
    <span class="s2">"url"</span><span class="o">:</span> <span class="s2">"http://my-github-app.com"</span><span class="p">,</span>
    <span class="s2">"name"</span><span class="o">:</span> <span class="s2">"my github app"</span><span class="p">,</span>
    <span class="s2">"client_id"</span><span class="o">:</span> <span class="s2">"abcde12345fghij67890"</span>
  <span class="p">},</span>
  <span class="s2">"note"</span><span class="o">:</span> <span class="s2">"optional note"</span><span class="p">,</span>
  <span class="s2">"note_url"</span><span class="o">:</span> <span class="s2">"http://optional/note/url"</span><span class="p">,</span>
  <span class="s2">"updated_at"</span><span class="o">:</span> <span class="s2">"2011-09-06T20:39:23Z"</span><span class="p">,</span>
  <span class="s2">"created_at"</span><span class="o">:</span> <span class="s2">"2011-09-06T17:26:27Z"</span>
<span class="p">}</span></code></pre>
<h2 id="create-a-new-authorization">Create a new authorization</h2>
<p>If you need a small number of tokens, implementing the <a href="#web-application-flow">web flow</a>
can be cumbersome. Instead, tokens can be created using the Authorizations API using
<a href="/v3/auth#basic-authentication">Basic Authentication</a>. 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 <a href="https://github.com/settings/applications">OAuth applications listing on GitHub</a>. OAuth tokens
can also be created through the web UI via the <a href="https://github.com/settings/applications">Application settings page</a>.
Read more about these tokens on the <a href="https://help.github.com/articles/creating-an-access-token-for-command-line-use">GitHub Help page</a>.</p>
<pre><code>POST /authorizations
</code></pre>
<h3 id="parameters-2">Parameters</h3>
      <th>Name</th>
      <th>Type</th>
      <th>Description</th>
      <td><code>scopes</code></td>
      <td><code>array</code></td>
      <td>A list of scopes that this authorization is in.</td>
      <td><code>note</code></td>
      <td><code>string</code></td>
      <td>A note to remind you what the OAuth token is for.</td>
      <td><code>note_url</code></td>
      <td><code>string</code></td>
      <td>A URL to remind you what app the OAuth token is for.</td>
      <td><code>client_id</code></td>
      <td><code>string</code></td>
      <td>The 20 character OAuth app client key for which to create the token.</td>
      <td><code>client_secret</code></td>
      <td><code>string</code></td>
      <td>The 40 character OAuth app client secret for which to create the token.</td>
<pre><code class="language-javascript"><span class="p">{</span>
  <span class="s2">"scopes"</span><span class="o">:</span> <span class="p">[</span>
    <span class="s2">"public_repo"</span>
  <span class="p">],</span>
  <span class="s2">"note"</span><span class="o">:</span> <span class="s2">"admin script"</span>
<span class="p">}</span></code></pre>
<h3 id="response-3">Response</h3>
<pre class="headers"><code>Status: 201 Created
Location: https://api.github.com/authorizations/1
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999</code></pre>
<pre><code class="language-javascript"><span class="p">{</span>
  <span class="s2">"id"</span><span class="o">:</span> <span class="mi">1</span><span class="p">,</span>
  <span class="s2">"url"</span><span class="o">:</span> <span class="s2">"https://api.github.com/authorizations/1"</span><span class="p">,</span>
  <span class="s2">"scopes"</span><span class="o">:</span> <span class="p">[</span>
    <span class="s2">"public_repo"</span>
  <span class="p">],</span>
  <span class="s2">"token"</span><span class="o">:</span> <span class="s2">"abc123"</span><span class="p">,</span>
  <span class="s2">"app"</span><span class="o">:</span> <span class="p">{</span>
    <span class="s2">"url"</span><span class="o">:</span> <span class="s2">"http://my-github-app.com"</span><span class="p">,</span>
    <span class="s2">"name"</span><span class="o">:</span> <span class="s2">"my github app"</span><span class="p">,</span>
    <span class="s2">"client_id"</span><span class="o">:</span> <span class="s2">"abcde12345fghij67890"</span>
  <span class="p">},</span>
  <span class="s2">"note"</span><span class="o">:</span> <span class="s2">"optional note"</span><span class="p">,</span>
  <span class="s2">"note_url"</span><span class="o">:</span> <span class="s2">"http://optional/note/url"</span><span class="p">,</span>
  <span class="s2">"updated_at"</span><span class="o">:</span> <span class="s2">"2011-09-06T20:39:23Z"</span><span class="p">,</span>
  <span class="s2">"created_at"</span><span class="o">:</span> <span class="s2">"2011-09-06T17:26:27Z"</span>
<span class="p">}</span></code></pre>
<h2 id="get-or-create-an-authorization-for-a-specific-app">Get-or-create an authorization for a specific app</h2>
<p>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’s token for the application if one
exists. Otherwise, it creates one.</p>
<pre><code>PUT /authorizations/clients/:client_id
</code></pre>
<h3 id="parameters-3">Parameters</h3>
      <th>Name</th>
      <th>Type</th>
      <th>Description</th>
      <td><code>client_secret</code></td>
      <td><code>string</code></td>
      <td>The 40 character OAuth app client secret associated with the client ID specified in the URL.</td>
      <td><code>scopes</code></td>
      <td><code>array</code></td>
      <td>A list of scopes that this authorization is in.</td>
      <td><code>note</code></td>
      <td><code>string</code></td>
      <td>A note to remind you what the OAuth token is for.</td>
      <td><code>note_url</code></td>
      <td><code>string</code></td>
      <td>A URL to remind you what app the OAuth token is for.</td>
<pre><code class="language-javascript"><span class="p">{</span>
  <span class="s2">"client_secret"</span><span class="o">:</span> <span class="s2">"abcdabcdabcdabcdabcdabcdabcdabcdabcdabcd"</span><span class="p">,</span>
  <span class="s2">"scopes"</span><span class="o">:</span> <span class="p">[</span>
    <span class="s2">"public_repo"</span>
  <span class="p">],</span>
  <span class="s2">"note"</span><span class="o">:</span> <span class="s2">"admin script"</span>
<span class="p">}</span></code></pre>
<h3 id="response-if-returning-a-new-token">Response if returning a new token</h3>
<pre class="headers"><code>Status: 201 Created
Location: https://api.github.com/authorizations/1
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999</code></pre>
<pre><code class="language-javascript"><span class="p">{</span>
  <span class="s2">"id"</span><span class="o">:</span> <span class="mi">1</span><span class="p">,</span>
  <span class="s2">"url"</span><span class="o">:</span> <span class="s2">"https://api.github.com/authorizations/1"</span><span class="p">,</span>
  <span class="s2">"scopes"</span><span class="o">:</span> <span class="p">[</span>
    <span class="s2">"public_repo"</span>
  <span class="p">],</span>
  <span class="s2">"token"</span><span class="o">:</span> <span class="s2">"abc123"</span><span class="p">,</span>
  <span class="s2">"app"</span><span class="o">:</span> <span class="p">{</span>
    <span class="s2">"url"</span><span class="o">:</span> <span class="s2">"http://my-github-app.com"</span><span class="p">,</span>
    <span class="s2">"name"</span><span class="o">:</span> <span class="s2">"my github app"</span><span class="p">,</span>
    <span class="s2">"client_id"</span><span class="o">:</span> <span class="s2">"abcde12345fghij67890"</span>
  <span class="p">},</span>
  <span class="s2">"note"</span><span class="o">:</span> <span class="s2">"optional note"</span><span class="p">,</span>
  <span class="s2">"note_url"</span><span class="o">:</span> <span class="s2">"http://optional/note/url"</span><span class="p">,</span>
  <span class="s2">"updated_at"</span><span class="o">:</span> <span class="s2">"2011-09-06T20:39:23Z"</span><span class="p">,</span>
  <span class="s2">"created_at"</span><span class="o">:</span> <span class="s2">"2011-09-06T17:26:27Z"</span>
<span class="p">}</span></code></pre>
<h3 id="response-if-returning-an-existing-token">Response if returning an existing token</h3>
<pre class="headers"><code>Status: 200 OK
Location: https://api.github.com/authorizations/1
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999</code></pre>
<pre><code class="language-javascript"><span class="p">{</span>
  <span class="s2">"id"</span><span class="o">:</span> <span class="mi">1</span><span class="p">,</span>
  <span class="s2">"url"</span><span class="o">:</span> <span class="s2">"https://api.github.com/authorizations/1"</span><span class="p">,</span>
  <span class="s2">"scopes"</span><span class="o">:</span> <span class="p">[</span>
    <span class="s2">"public_repo"</span>
  <span class="p">],</span>
  <span class="s2">"token"</span><span class="o">:</span> <span class="s2">"abc123"</span><span class="p">,</span>
  <span class="s2">"app"</span><span class="o">:</span> <span class="p">{</span>
    <span class="s2">"url"</span><span class="o">:</span> <span class="s2">"http://my-github-app.com"</span><span class="p">,</span>
    <span class="s2">"name"</span><span class="o">:</span> <span class="s2">"my github app"</span><span class="p">,</span>
    <span class="s2">"client_id"</span><span class="o">:</span> <span class="s2">"abcde12345fghij67890"</span>
  <span class="p">},</span>
  <span class="s2">"note"</span><span class="o">:</span> <span class="s2">"optional note"</span><span class="p">,</span>
  <span class="s2">"note_url"</span><span class="o">:</span> <span class="s2">"http://optional/note/url"</span><span class="p">,</span>
  <span class="s2">"updated_at"</span><span class="o">:</span> <span class="s2">"2011-09-06T20:39:23Z"</span><span class="p">,</span>
  <span class="s2">"created_at"</span><span class="o">:</span> <span class="s2">"2011-09-06T17:26:27Z"</span>
<span class="p">}</span></code></pre>
<h2 id="update-an-existing-authorization">Update an existing authorization</h2>
<pre><code>PATCH /authorizations/:id
</code></pre>
<h3 id="parameters-4">Parameters</h3>
      <th>Name</th>
      <th>Type</th>
      <th>Description</th>
      <td><code>scopes</code></td>
      <td><code>array</code></td>
      <td>Replaces the authorization scopes with these.</td>
      <td><code>add_scopes</code></td>
      <td><code>array</code></td>
      <td>A list of scopes to add to this authorization.</td>
      <td><code>remove_scopes</code></td>
      <td><code>array</code></td>
      <td>A list of scopes to remove from this authorization.</td>
      <td><code>note</code></td>
      <td><code>string</code></td>
      <td>A note to remind you what the OAuth token is for.</td>
      <td><code>note_url</code></td>
      <td><code>string</code></td>
      <td>A URL to remind you what app the OAuth token is for.</td>
<p>You can only send one of these scope keys at a time.</p>
<pre><code class="language-javascript"><span class="p">{</span>
  <span class="s2">"add_scopes"</span><span class="o">:</span> <span class="p">[</span>
    <span class="s2">"repo"</span>
  <span class="p">],</span>
  <span class="s2">"note"</span><span class="o">:</span> <span class="s2">"admin script"</span>
<span class="p">}</span></code></pre>
<h3 id="response-4">Response</h3>
<pre class="headers"><code>Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999</code></pre>
<pre><code class="language-javascript"><span class="p">{</span>
  <span class="s2">"id"</span><span class="o">:</span> <span class="mi">1</span><span class="p">,</span>
  <span class="s2">"url"</span><span class="o">:</span> <span class="s2">"https://api.github.com/authorizations/1"</span><span class="p">,</span>
  <span class="s2">"scopes"</span><span class="o">:</span> <span class="p">[</span>
    <span class="s2">"public_repo"</span>
  <span class="p">],</span>
  <span class="s2">"token"</span><span class="o">:</span> <span class="s2">"abc123"</span><span class="p">,</span>
  <span class="s2">"app"</span><span class="o">:</span> <span class="p">{</span>
    <span class="s2">"url"</span><span class="o">:</span> <span class="s2">"http://my-github-app.com"</span><span class="p">,</span>
    <span class="s2">"name"</span><span class="o">:</span> <span class="s2">"my github app"</span><span class="p">,</span>
    <span class="s2">"client_id"</span><span class="o">:</span> <span class="s2">"abcde12345fghij67890"</span>
  <span class="p">},</span>
  <span class="s2">"note"</span><span class="o">:</span> <span class="s2">"optional note"</span><span class="p">,</span>
  <span class="s2">"note_url"</span><span class="o">:</span> <span class="s2">"http://optional/note/url"</span><span class="p">,</span>
  <span class="s2">"updated_at"</span><span class="o">:</span> <span class="s2">"2011-09-06T20:39:23Z"</span><span class="p">,</span>
  <span class="s2">"created_at"</span><span class="o">:</span> <span class="s2">"2011-09-06T17:26:27Z"</span>
<span class="p">}</span></code></pre>
<h2 id="delete-an-authorization">Delete an authorization</h2>
<pre><code>DELETE /authorizations/:id
</code></pre>
<h3 id="response-5">Response</h3>
<pre class="headers no-response"><code>Status: 204 No Content
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999</code></pre>
<h2 id="check-an-authorization">Check an authorization</h2>
<p>OAuth applications can use a special API method for checking OAuth token
validity without running afoul of normal rate limits for failed login attempts.
Authentication works differently with this particular endpoint. You must use
<a href="/v3/auth#basic-authentication">Basic Authentication</a> when accessing it, where the username is the OAuth
application <code>client_id</code> and the password is its <code>client_secret</code>. Invalid tokens
will return <code>404 NOT FOUND</code>.</p>
<pre><code>GET /applications/:client_id/tokens/:access_token
</code></pre>
<h3 id="response-6">Response</h3>
<pre class="headers"><code>Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999</code></pre>
<pre><code class="language-javascript"><span class="p">{</span>
  <span class="s2">"id"</span><span class="o">:</span> <span class="mi">1</span><span class="p">,</span>
  <span class="s2">"url"</span><span class="o">:</span> <span class="s2">"https://api.github.com/authorizations/1"</span><span class="p">,</span>
  <span class="s2">"scopes"</span><span class="o">:</span> <span class="p">[</span>
    <span class="s2">"public_repo"</span>
  <span class="p">],</span>
  <span class="s2">"token"</span><span class="o">:</span> <span class="s2">"abc123"</span><span class="p">,</span>
  <span class="s2">"app"</span><span class="o">:</span> <span class="p">{</span>
    <span class="s2">"url"</span><span class="o">:</span> <span class="s2">"http://my-github-app.com"</span><span class="p">,</span>
    <span class="s2">"name"</span><span class="o">:</span> <span class="s2">"my github app"</span><span class="p">,</span>
    <span class="s2">"client_id"</span><span class="o">:</span> <span class="s2">"abcde12345fghij67890"</span>
  <span class="p">},</span>
  <span class="s2">"note"</span><span class="o">:</span> <span class="s2">"optional note"</span><span class="p">,</span>
  <span class="s2">"note_url"</span><span class="o">:</span> <span class="s2">"http://optional/note/url"</span><span class="p">,</span>
  <span class="s2">"updated_at"</span><span class="o">:</span> <span class="s2">"2011-09-06T20:39:23Z"</span><span class="p">,</span>
  <span class="s2">"created_at"</span><span class="o">:</span> <span class="s2">"2011-09-06T17:26:27Z"</span><span class="p">,</span>
  <span class="s2">"user"</span><span class="o">:</span> <span class="p">{</span>
    <span class="s2">"login"</span><span class="o">:</span> <span class="s2">"octocat"</span><span class="p">,</span>
    <span class="s2">"id"</span><span class="o">:</span> <span class="mi">1</span><span class="p">,</span>
    <span class="s2">"avatar_url"</span><span class="o">:</span> <span class="s2">"https://github.com/images/error/octocat_happy.gif"</span><span class="p">,</span>
    <span class="s2">"gravatar_id"</span><span class="o">:</span> <span class="s2">"somehexcode"</span><span class="p">,</span>
    <span class="s2">"url"</span><span class="o">:</span> <span class="s2">"https://api.github.com/users/octocat"</span><span class="p">,</span>
    <span class="s2">"html_url"</span><span class="o">:</span> <span class="s2">"https://github.com/octocat"</span><span class="p">,</span>
    <span class="s2">"followers_url"</span><span class="o">:</span> <span class="s2">"https://api.github.com/users/octocat/followers"</span><span class="p">,</span>
    <span class="s2">"following_url"</span><span class="o">:</span> <span class="s2">"https://api.github.com/users/octocat/following{/other_user}"</span><span class="p">,</span>
    <span class="s2">"gists_url"</span><span class="o">:</span> <span class="s2">"https://api.github.com/users/octocat/gists{/gist_id}"</span><span class="p">,</span>
    <span class="s2">"starred_url"</span><span class="o">:</span> <span class="s2">"https://api.github.com/users/octocat/starred{/owner}{/repo}"</span><span class="p">,</span>
    <span class="s2">"subscriptions_url"</span><span class="o">:</span> <span class="s2">"https://api.github.com/users/octocat/subscriptions"</span><span class="p">,</span>
    <span class="s2">"organizations_url"</span><span class="o">:</span> <span class="s2">"https://api.github.com/users/octocat/orgs"</span><span class="p">,</span>
    <span class="s2">"repos_url"</span><span class="o">:</span> <span class="s2">"https://api.github.com/users/octocat/repos"</span><span class="p">,</span>
    <span class="s2">"events_url"</span><span class="o">:</span> <span class="s2">"https://api.github.com/users/octocat/events{/privacy}"</span><span class="p">,</span>
    <span class="s2">"received_events_url"</span><span class="o">:</span> <span class="s2">"https://api.github.com/users/octocat/received_events"</span><span class="p">,</span>
    <span class="s2">"type"</span><span class="o">:</span> <span class="s2">"User"</span><span class="p">,</span>
    <span class="s2">"site_admin"</span><span class="o">:</span> <span class="kc">false</span>
  <span class="p">}</span>
<span class="p">}</span></code></pre>
<h2 id="revoke-all-authorizations-for-an-application">Revoke all authorizations for an application</h2>
<p>OAuth application owners can revoke every token for an OAuth application. You
must use <a href="/v3/auth#basic-authentication">Basic Authentication</a> when calling
this method. The username is the OAuth application <code>client_id</code> and the password
is its <code>client_secret</code>. Tokens are revoked via a background job, and it might
take a few minutes for the process to complete.</p>
<pre><code>DELETE /applications/:client_id/tokens
</code></pre>
<h3 id="response-7">Response</h3>
<pre class="headers no-response"><code>Status: 204 No Content
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999</code></pre>
<h2 id="revoke-an-authorization-for-an-application">Revoke an authorization for an application</h2>
<p>OAuth application owners can also revoke a single token for an OAuth
application. You must use <a href="/v3/auth#basic-authentication">Basic Authentication</a>
for this method, where the username is the OAuth application <code>client_id</code> and
  the password is its <code>client_secret</code>.</p>
<pre><code>DELETE /applications/:client_id/tokens/:access_token
</code></pre>
<h3 id="response-8">Response</h3>
<pre class="headers no-response"><code>Status: 204 No Content
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999</code></pre>
<h2 id="more-information">More Information</h2>
<p>It can be a little tricky to get started with OAuth. Here are a few
links that might be of help:</p>
  <li><a href="http://tools.ietf.org/html/rfc6749">OAuth 2 spec</a></li>
  <li><a href="http://developers.facebook.com/docs/technical-guides/login/">Facebook Login API</a></li>
  <li><a href="https://github.com/intridea/oauth2">Ruby OAuth2 lib</a></li>
  <li><a href="https://gist.github.com/9fd1a6199da0465ec87c">Simple Ruby/Sinatra example</a></li>
<a href="https://gist.github.com/ib-lundgren/6507798">Python Flask example</a> using <a href="https://github.com/requests/requests-oauthlib">requests-oauthlib</a>
<a href="https://gist.github.com/e3fbd47fbb7ee3c626bb">Simple Python example</a> using <a href="https://github.com/dgouldin/python-oauth2">python-oauth2</a>
  <li><a href="https://github.com/intridea/omniauth">Ruby OmniAuth example</a></li>
  <li><a href="https://github.com/atmos/sinatra_auth_github">Ruby Sinatra extension</a></li>
  <li><a href="https://github.com/atmos/warden-github">Ruby Warden strategy</a></li>
		<div id="js-sidebar" class="sidebar-shell">
  <div class="js-toggle-list sidebar-module expandable">
      <li class="js-topic">
        <h3><a href="#" class="js-expand-btn collapsed arrow-btn"></a><a href="/v3/">Overview</a></h3>
        <ul class="js-guides">
          <li><a href="/v3/media/">Media Types</a></li>
          <li><a href="/v3/oauth/">OAuth</a></li>
          <li><a href="/v3/auth/">Other Authentication Methods</a></li>
          <li><a href="/v3/troubleshooting/">Troubleshooting</a></li>
          <li><a href="/v3/versions/">Versions</a></li>
        </ul>
      </li>
      <li class="js-topic">
        <h3><a href="#" class="js-expand-btn collapsed arrow-btn"></a><a href="/v3/activity/">Activity</a></h3>
        <ul class="js-guides">
          <li><a href="/v3/activity/events/">Events</a></li>
          <li><a href="/v3/activity/events/types/">Event Types</a></li>
          <li><a href="/v3/activity/feeds/">Feeds</a></li>
          <li><a href="/v3/activity/notifications/">Notifications</a></li>
          <li><a href="/v3/activity/starring/">Starring</a></li>
          <li><a href="/v3/activity/watching/">Watching</a></li>
        </ul>
      </li>
      <li class="js-topic">
        <h3><a href="#" class="js-expand-btn collapsed arrow-btn"></a><a href="/v3/gists/">Gists</a></h3>
        <ul class="js-guides">
          <li><a href="/v3/gists/comments/">Comments</a></li>
        </ul>
      </li>
      <li class="js-topic">
        <h3><a href="#" class="js-expand-btn collapsed arrow-btn"></a><a href="/v3/git/">Git Data</a></h3>
        <ul class="js-guides">
          <li><a href="/v3/git/blobs/">Blobs</a></li>
          <li><a href="/v3/git/commits/">Commits</a></li>
          <li><a href="/v3/git/refs/">References</a></li>
          <li><a href="/v3/git/tags/">Tags</a></li>
          <li><a href="/v3/git/trees/">Trees</a></li>
        </ul>
      </li>
      <li class="js-topic">
        <h3><a href="#" class="js-expand-btn collapsed arrow-btn"></a><a href="/v3/issues/">Issues</a></h3>
        <ul class="js-guides">
          <li><a href="/v3/issues/assignees/">Assignees</a></li>
          <li><a href="/v3/issues/comments/">Comments</a></li>
          <li><a href="/v3/issues/events/">Events</a></li>
          <li><a href="/v3/issues/labels/">Labels</a></li>
          <li><a href="/v3/issues/milestones/">Milestones</a></li>
        </ul>
      </li>
      <li class="js-topic">
        <h3><a href="#" class="js-expand-btn collapsed arrow-btn"></a><a href="/v3/misc/">Miscellaneous</a></h3>
        <ul class="js-guides">
          <li><a href="/v3/emojis/">Emojis</a></li>
          <li><a href="/v3/gitignore/">Gitignore</a></li>
          <li><a href="/v3/markdown/">Markdown</a></li>
          <li><a href="/v3/meta/">Meta</a></li>
          <li><a href="/v3/rate_limit/">Rate Limit</a></li>
        </ul>
      </li>
      <li class="js-topic">
        <h3><a href="#" class="js-expand-btn collapsed arrow-btn"></a><a href="/v3/orgs/">Organizations</a></h3>
        <ul class="js-guides">
          <li><a href="/v3/orgs/members/">Members</a></li>
          <li><a href="/v3/orgs/teams/">Teams</a></li>
        </ul>
      </li>
      <li class="js-topic">
        <h3><a href="#" class="js-expand-btn collapsed arrow-btn"></a><a href="/v3/pulls/">Pull Requests</a></h3>
        <ul class="js-guides">
          <li><a href="/v3/pulls/comments/">Review Comments</a></li>
        </ul>
      </li>
      <li class="js-topic">
        <h3><a href="#" class="js-expand-btn collapsed arrow-btn"></a><a href="/v3/repos/">Repositories</a></h3>
        <ul class="js-guides">
          <li><a href="/v3/repos/collaborators/">Collaborators</a></li>
          <li><a href="/v3/repos/comments/">Comments</a></li>
          <li><a href="/v3/repos/commits/">Commits</a></li>
          <li><a href="/v3/repos/contents/">Contents</a></li>
          <li><a href="/v3/repos/keys/">Deploy Keys</a></li>
          <li><a href="/v3/repos/deployments/">Deployments</a></li>
          <li><a href="/v3/repos/downloads/">Downloads</a></li>
          <li><a href="/v3/repos/forks/">Forks</a></li>
          <li><a href="/v3/repos/hooks/">Hooks</a></li>
          <li><a href="/v3/repos/merging/">Merging</a></li>
          <li><a href="/v3/repos/releases/">Releases</a></li>
          <li><a href="/v3/repos/statistics/">Statistics</a></li>
          <li><a href="/v3/repos/statuses/">Statuses</a></li>
        </ul>
      </li>
      <li class="js-topic">
        <h3><a href="#" class="js-expand-btn collapsed arrow-btn"></a><a href="/v3/search/">Search</a></h3>
        <ul class="js-guides">
          <li><a href="/v3/search/#search-repositories">Repositories</a></li>
          <li><a href="/v3/search/#search-code">Code</a></li>
          <li><a href="/v3/search/#search-issues">Issues</a></li>
          <li><a href="/v3/search/#search-users">Users</a></li>
          <li><a href="/v3/search/legacy/">Legacy Search</a></li>
        </ul>
      </li>
      <li class="js-topic">
        <h3><a href="#" class="js-expand-btn collapsed arrow-btn"></a><a href="/v3/users/">Users</a></h3>
        <ul class="js-guides">
          <li><a href="/v3/users/emails/">Emails</a></li>
          <li><a href="/v3/users/followers/">Followers</a></li>
          <li><a href="/v3/users/keys/">Public Keys</a></li>
        </ul>
      </li>
  </div> <!-- /sidebar-module -->
  <div class="sidebar-module notice">
    <p>This website is a <a href="https://github.com/github/developer.github.com" target="_blank">public GitHub repository</a>. Please help us by forking the project and adding to it.</p>
	<div class="sidebar-module api-status"><a href="https://status.github.com" class="unknown">API Status</a></div>
</div><!-- /sidebar-shell -->
  </div><!-- #wrapper -->
		<div id="footer" >
    <div class="lower_footer">
      <ul class="footer-cell">
        <li><a href="http://help.github.com/terms-of-service/">Terms</a></li>
        <li><a href="http://help.github.com/privacy-policy/">Privacy</a></li>
        <li><a href="http://help.github.com/security/">Security</a></li>
        <li><a href="https://github.com/contact">Contact</a></li>				
      </ul>
      <span class="footer-cell">
        <a href="https://github.com" class="mega-octicon octicon-mark-github"></a>
      </span>
      <ul class="footer-cell">
        <li><a href="https://status.github.com/">Status</a></li>
        <li><a href="http://training.github.com/">Training</a></li>
        <li><a href="http://shop.github.com/">Shop</a></li>
        <li><a href="https://github.com/blog">Blog</a></li>
        <li><a href="https://github.com/about">About</a></li>
      </ul>
		<div class="wrapper">
			<p>Design &copy; <span class="js-year">2014</span> GitHub, Inc. All rights reserved. Except where otherwise noted, content on this site is licensed under a <a href="http://creativecommons.org/licenses/by/3.0/us/">Creative Commons CC-BY license</a>.</p>
  </div><!-- /#footer -->
  <script type="text/javascript">
    var _gauges = _gauges || [];
    (function() {
      var t   = document.createElement('script');
      t.type  = 'text/javascript';
      t.async = true;
      t.id    = 'gauges-tracker';
      t.setAttribute('data-site-id', '4f2038e0cb25bc1b55000003');
      t.src = '//secure.gaug.es/track.js';
      var s = document.getElementsByTagName('script')[0];
      s.parentNode.insertBefore(t, s);
  </script>
  <script type="text/javascript">
      var _gaq = _gaq || [];
      _gaq.push(['_setAccount', 'UA-3769691-27']);
      _gaq.push(['_trackPageview']);
      (function() {
        var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
        ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
        var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
      })();
  </script>
  <script src="/shared/js/retina.js" type="text/javascript"></script>
Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

FilesExpand file tree

index.html

Latest commit

History

index.html

File metadata and controls
