OAuth

• Web Application Flow
• Non-Web Application Flow
• Redirect URLs
• Scopes
• OAuth Authorizations API
• List your authorizations
• Get a single authorization
• Create a new authorization
• Get-or-create an authorization for a specific app
• Update an existing authorization
• Delete an authorization
• Check an authorization
• Revoke all authorizations for an application
• Revoke an authorization for an application
• More Information

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.

Web Application Flow

This is a description of the OAuth2 flow from 3rd party web sites.

1. Redirect users to request GitHub access

GET https://github.com/login/oauth/authorize

Parameters

2. GitHub redirects back to your site

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

Parameters

Response

By default, the response will take the following form:

access_token=e72e16c7e42f292c6912e7710c838347ae178b4a&scope=user%2Cgist&token_type=bearer

You can also receive the content in different formats depending on the Accept header:

Accept: application/json
{"access_token":"e72e16c7e42f292c6912e7710c838347ae178b4a", "scope":"repo,gist", "token_type":"bearer"}
Accept: application/xml
<OAuth>
  <token_type>bearer</token_type>
  <scope>repo,gist</scope>
  <access_token>e72e16c7e42f292c6912e7710c838347ae178b4a</access_token>
</OAuth>

3. Use the access token to access the API

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

Non-Web Application Flow

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. (Make sure to understand how to work with two-factor authentication if you or your users have two-factor authentication enabled.)

Redirect URLs

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’s host and port must exactly match the callback URL. The redirect URL’s path must reference a subdirectory of the callback URL.

CALLBACK: https://example.com/path
GOOD: https://example.com/path
GOOD: https://example.com/path/subdir/other
BAD:  https://example.com/bar
BAD:  https://example.com/
BAD:  https://example.com:8080/path
BAD:  https://oauth.example.com:8080/path
BAD:  https://example.org

Scopes

Scopes let you specify exactly what type of access you need. Scopes limit access for OAuth tokens. They do not grant any additional permission beyond that which the user already has.

For the web flow, requested scopes will be displayed to the user on the authorize form.

Check headers to see what OAuth scopes you have, and what the API action accepts.

$ 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

X-OAuth-Scopes lists the scopes your token has authorized. X-Accepted-OAuth-Scopes lists the scopes that the action checks for.

NOTE: Your application can request the scopes in the initial redirection. You can specify multiple scopes by separating them with a comma:

https://github.com/login/oauth/authorize?
  client_id=...&
  scope=user,public_repo

OAuth Authorizations API

There is an API for users to manage their own tokens. You can only access your own tokens, and only via Basic Authentication. (Make sure to understand how to work with two-factor authentication if you or your users have two-factor authentication enabled.)

List your authorizations

GET /authorizations

Response

Status: 200 OK
Link: <https://api.github.com/resource?page=2>; rel="next",
      <https://api.github.com/resource?page=5>; rel="last"
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

[
  {
    "id": 1,
    "url": "https://api.github.com/authorizations/1",
    "scopes": [
      "public_repo"
    ],
    "token": "abc123",
    "app": {
      "url": "https://my-github-app.com",
      "name": "my github app",
      "client_id": "abcde12345fghij67890"
    },
    "note": "optional note",
    "note_url": "https://optional/note/url",
    "updated_at": "2011-09-06T20:39:23Z",
    "created_at": "2011-09-06T17:26:27Z"
  }
]

Get a single authorization

GET /authorizations/:id

Response

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "id": 1,
  "url": "https://api.github.com/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "abc123",
  "app": {
    "url": "https://my-github-app.com",
    "name": "my github app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "https://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z"
}

Create a new authorization

If you need a small number of tokens, implementing the web flow can be cumbersome. Instead, tokens can be created using the Authorizations API using 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. OAuth tokens can also be created through the web UI via the Application settings page. Read more about these tokens on the GitHub Help page.

POST /authorizations

Parameters

{
  "scopes": [
    "public_repo"
  ],
  "note": "admin script"
}

Response

Status: 201 Created
Location: https://api.github.com/authorizations/1
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "id": 1,
  "url": "https://api.github.com/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "abc123",
  "app": {
    "url": "https://my-github-app.com",
    "name": "my github app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "https://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z"
}

Get-or-create an authorization for a specific app

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.

PUT /authorizations/clients/:client_id

Parameters

{
  "client_secret": "abcdabcdabcdabcdabcdabcdabcdabcdabcdabcd",
  "scopes": [
    "public_repo"
  ],
  "note": "admin script"
}

Response if returning a new token

Status: 201 Created
Location: https://api.github.com/authorizations/1
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "id": 1,
  "url": "https://api.github.com/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "abc123",
  "app": {
    "url": "https://my-github-app.com",
    "name": "my github app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "https://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z"
}

Response if returning an existing token

Status: 200 OK
Location: https://api.github.com/authorizations/1
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "id": 1,
  "url": "https://api.github.com/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "abc123",
  "app": {
    "url": "https://my-github-app.com",
    "name": "my github app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "https://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z"
}

Update an existing authorization

PATCH /authorizations/:id

Parameters

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

{
  "add_scopes": [
    "repo"
  ],
  "note": "admin script"
}

Response

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "id": 1,
  "url": "https://api.github.com/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "abc123",
  "app": {
    "url": "https://my-github-app.com",
    "name": "my github app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "https://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z"
}

Delete an authorization

DELETE /authorizations/:id

Response

Status: 204 No Content
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

Check an authorization

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 Basic Authentication when accessing it, where the username is the OAuth application client_id and the password is its client_secret. Invalid tokens will return 404 NOT FOUND.

GET /applications/:client_id/tokens/:access_token

Response

Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

{
  "id": 1,
  "url": "https://api.github.com/authorizations/1",
  "scopes": [
    "public_repo"
  ],
  "token": "abc123",
  "app": {
    "url": "https://my-github-app.com",
    "name": "my github app",
    "client_id": "abcde12345fghij67890"
  },
  "note": "optional note",
  "note_url": "https://optional/note/url",
  "updated_at": "2011-09-06T20:39:23Z",
  "created_at": "2011-09-06T17:26:27Z",
  "user": {
    "login": "octocat",
    "id": 1,
    "avatar_url": "https://github.com/images/error/octocat_happy.gif",
    "gravatar_id": "somehexcode",
    "url": "https://api.github.com/users/octocat",
    "html_url": "https://github.com/octocat",
    "followers_url": "https://api.github.com/users/octocat/followers",
    "following_url": "https://api.github.com/users/octocat/following{/other_user}",
    "gists_url": "https://api.github.com/users/octocat/gists{/gist_id}",
    "starred_url": "https://api.github.com/users/octocat/starred{/owner}{/repo}",
    "subscriptions_url": "https://api.github.com/users/octocat/subscriptions",
    "organizations_url": "https://api.github.com/users/octocat/orgs",
    "repos_url": "https://api.github.com/users/octocat/repos",
    "events_url": "https://api.github.com/users/octocat/events{/privacy}",
    "received_events_url": "https://api.github.com/users/octocat/received_events",
    "type": "User",
    "site_admin": false
  }
}

Revoke all authorizations for an application

OAuth application owners can revoke every token for an OAuth application. You must use Basic Authentication when calling this method. The username is the OAuth application client_id and the password is its client_secret. Tokens are revoked via a background job, and it might take a few minutes for the process to complete.

DELETE /applications/:client_id/tokens

Response

Status: 204 No Content
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

Revoke an authorization for an application

OAuth application owners can also revoke a single token for an OAuth application. You must use Basic Authentication for this method, where the username is the OAuth application client_id and the password is its client_secret.

DELETE /applications/:client_id/tokens/:access_token

Response

Status: 204 No Content
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999

More Information

It can be a little tricky to get started with OAuth. Here are a few links that might be of help:

• OAuth 2 spec
• Facebook Login API
• Ruby OAuth2 lib
• Simple Ruby/Sinatra example
• Python Flask example using requests-oauthlib
• Simple Python example using python-oauth2
• Ruby OmniAuth example
• Ruby Sinatra extension
• Ruby Warden strategy