| title | OAuth | GitHub API |
|---|
- TOC {:toc}
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 Basic Authentication because tokens can be limited to specific types of data, and can be revoked by users at any time.
All developers need to register their application before getting started. A registered OAuth application is assigned a unique Client ID and Client Secret. The Client Secret should not be shared.
This is a description of the OAuth flow from 3rd party web sites.
GET https://github.com/login/oauth/authorize
client_id : Required string - The client ID you received from GitHub when you registered.
redirect_uri : Optional string - URL in your app where users will be sent after authorization. See details below about redirect urls.
scope : Optional string - Comma separated list of scopes.
state : Optional string - An unguessable random string. It is used to protect against cross-site request forgery attacks.
If the user accepts your request, GitHub redirects back to your site
with a temporary code in a code parameter as well as the state you provided in
the previous step in a state parameter. If the states don't match, the request
has been created by a third party and the process should be aborted.
Exchange this for an access token:
POST https://github.com/login/oauth/access_token
client_id : Required string - The client ID you received from GitHub when you registered.
redirect_uri : Optional string
client_secret : Required string - The client secret you received from GitHub when you registered.
code : Required string - The code you received as a response to Step 1.
state : Required string - The state value you provided in Step 1.
By default, the response will take the following form:
access_token=e72e16c7e42f292c6912e7710c838347ae178b4a&token_type=bearer
You can also receive the content in different formats depending on the Accept header:
Accept: application/json
{"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a","token_type":"bearer"}
Accept: application/xml
<OAuth>
<token_type>bearer</token_type>
<access_token>e72e16c7e42f292c6912e7710c838347ae178b4a</access_token>
</OAuth>
The access token allows you to make requests to the API on a behalf of a user.
GET https://api.github.com/user?access_token=...
Use basic authentication to create an OAuth2 token using the interface below. With this technique, a username and password need not be stored permanently, and the user can revoke access at any time.
The redirect_uri 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 must match the callback URL's
host.
CALLBACK: http://foo.com
GOOD: https://foo.com
GOOD: http://foo.com/bar
BAD: http://foo.com:8080
BAD: http://oauth.foo.com:8080
BAD: http://bar.com
Scopes let you specify exactly what type of access you need. This will be displayed to the user on the authorize form.
Check headers to see what OAuth scopes you have, and what the API action accept.
$ curl -H "Authorization: bearer TOKEN" https://api.github.com/users/technoweenie -I
HTTP/1.1 200 OK
X-OAuth-Scopes: repo, user
X-Accepted-OAuth-Scopes: user
X-OAuth-Scopes lists the scopes your token has authorized.
X-Accepted-OAuth-Scopes lists the scopes that the action checks for.
(no scope) : public read-only access (includes public user profile info, public repo info, and gists).
user : Read/write access to profile info only.
public_repo : Read/write access to public repos and organizations.
repo : Read/write access to public and private repos and organizations.
repo:status
: Read/write access to public and private repo statuses. Does not
include access to code - use repo for that.
delete_repo : Delete access to adminable repositories.
gist : write access to gists.
NOTE: Your application can request the scopes in the initial redirection. You can specify multiple scopes by separating them by a comma.
https://github.com/login/oauth/authorize?
client_id=...&
scope=user,public_repo
There is an API for users to manage their own tokens. You can only access your own tokens, and only through Basic Authentication.
GET /authorizations
<%= headers 200, :pagination => true %> <%= json(:oauth_access) { |h| [h] } %>
GET /authorizations/:id
<%= headers 200 %> <%= json :oauth_access %>
Note: Authorizations created from the API will show up in the GitHub API app.
POST /authorizations
scopes : Optional array - A list of scopes that this authorization is in.
note : Optional string - A note to remind you what the OAuth token is for.
note_url : Optional string - A URL to remind you what app the OAuth token is for.
<%= json :scopes => ["public_repo"], :note => 'admin script' %>
<%= headers 201, :Location => "https://api.github.com/authorizations/1" %> <%= json :oauth_access %>
PATCH /authorizations/:id
scopes : Optional array - Replaces the authorization scopes with these.
add_scopes : Optional array - A list of scopes to add to this authorization.
remove_scopes : Optional array - A list of scopes to remove from this authorization.
note : Optional string - A note to remind you what the OAuth token is for.
note_url : Optional string - A URL to remind you what app the OAuth token is for.
You can only send one of these scope keys at a time.
<%= json :add_scopes => ['repo'], :note => 'admin script' %>
<%= headers 200 %> <%= json :oauth_access %>
DELETE /authorizations/:id
<%= headers 204 %>
It can be a little tricky to get started with OAuth. Here are a few links that might be of help: