Merge pull request github#439 from github/document-oauth-errors

izuzak · izuzak · commit c27998cba3b8 · 2014-02-17T17:52:12.000+01:00
Give authorization API dedicated section and document common problems
diff --git a/content/changes/2012-12-06-create-authorization-for-app.html b/content/changes/2012-12-06-create-authorization-for-app.html
@@ -34,5 +34,5 @@
 No more implementing the [web flow][web-flow] just to get a token tied to your
 app's rate limit.
 
-[oauth-api]: /v3/oauth/#oauth-authorizations-api
+[oauth-api]: /v3/oauth_authorizations/#oauth-authorizations-api
 [web-flow]: /v3/oauth/#web-application-flow
diff --git a/content/guides/basics-of-authentication.md b/content/guides/basics-of-authentication.md
@@ -347,7 +347,7 @@ available as a separate project.
 [sinatra auth github test]: https://github.com/atmos/sinatra-auth-github-test
 [oauth scopes]: /v3/oauth/#scopes
 [edit scopes post]: /changes/2013-10-04-oauth-changes-coming/
-[check token valid]: /v3/oauth/#check-an-authorization
+[check token valid]: /v3/oauth_authorizations/#check-an-authorization
 [platform samples]: https://github.com/github/platform-samples/tree/master/api/ruby/basics-of-authentication
 [new oauth app]: https://github.com/settings/applications/new
 [app settings]: https://github.com/settings/applications
diff --git a/content/guides/getting-started.md b/content/guides/getting-started.md
@@ -517,7 +517,7 @@ Keep learning with the next API guide [Basics of Authentication][auth guide]!
 [media types]: /v3/media/
 [oauth]: /v3/oauth/
 [webflow]: /v3/oauth/#web-application-flow
-[authorizations api]: /v3/oauth/#create-a-new-authorization
+[authorizations api]: /v3/oauth_authorizations/#create-a-new-authorization
 [scopes]: /v3/oauth/#scopes
 [repos-api]: /v3/repos/
 [pages]: http://pages.github.com
diff --git a/content/v3.md b/content/v3.md
@@ -213,7 +213,7 @@ $ curl https://api.github.com/?access_token=OAUTH-TOKEN
 </pre>
 
 Read [more about OAuth2](/v3/oauth/).  Note that OAuth2 tokens can be [acquired
-programmatically](/v3/oauth/#create-a-new-authorization), for applications that
+programmatically](/v3/oauth_authorizations/#create-a-new-authorization), for applications that
 are not websites.
 
 ### OAuth2 Key/Secret
diff --git a/content/v3/auth.md b/content/v3/auth.md
@@ -71,7 +71,7 @@ token to [authenticate via OAuth][oauth-auth] for most API access.
 Alternately, you can create access tokens from the Personal Access Token
 section of your [application settings page](https://github.com/settings/applications).
 
-[create-access]: /v3/oauth/#create-a-new-authorization
+[create-access]: /v3/oauth_authorizations/#create-a-new-authorization
 [curl]: http://curl.haxx.se/
 [oauth-auth]: /v3/#authentication
 [personal-access-tokens]: https://github.com/blog/1509-personal-api-tokens
diff --git a/content/v3/oauth.md b/content/v3/oauth.md
@@ -110,10 +110,19 @@ 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=...
 
+You can pass the token in the query params like shown above, but a
+cleaner approach is to include it in the Authorization header
+
+    Authorization: token OAUTH-TOKEN
+
+For example, in curl you can set the Authorization header like this:
+
+    curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com/user
+
 ## Non-Web Application Flow
 
 Use [Basic Authentication](/v3/auth#basic-authentication) to create an OAuth2
-token using the [interface below](/v3/oauth/#create-a-new-authorization).  With
+token using the [interface below](/v3/oauth_authorizations/#create-a-new-authorization).  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](/v3/auth/#working-with-two-factor-authentication) if
@@ -129,7 +138,7 @@ subdirectory of the callback URL.
 
     CALLBACK: http://example.com/path
 
-    GOOD: https://example.com/path
+    GOOD: http://example.com/path
     GOOD: http://example.com/path/subdir/other
     BAD:  http://example.com/bar
     BAD:  http://example.com/
@@ -182,189 +191,79 @@ can specify multiple scopes by separating them with a comma:
       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](/v3/auth#basic-authentication).
-(Make sure to 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.)
-
-## List your authorizations
-
-    GET /authorizations
-
-### Response
-
-<%= headers 200, :pagination => default_pagination_rels %>
-<%= json(:oauth_access) { |h| [h] } %>
-
-## Get a single authorization
-
-    GET /authorizations/:id
-
-### Response
-
-<%= headers 200 %>
-<%= json :oauth_access %>
+## Common errors for the authorization request
 
-## Create a new authorization
+There are a few things that can go wrong in the process of obtaining an
+OAuth token for a user. In the initial authorization request phase,
+these are some errors you might see:
 
-If you need a small number of tokens, implementing the [web flow](#web-application-flow)
-can be cumbersome. Instead, tokens can be created using the Authorizations 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).
-Read more about these tokens on the [GitHub Help page](https://help.github.com/articles/creating-an-access-token-for-command-line-use).
+### Application Suspended
 
-    POST /authorizations
+If the OAuth application you set up has been suspended (due to reported
+abuse, spam, or a mis-use of the API), GitHub will redirect to the
+registered callback URL with the following parameters summerizing the
+error:
 
-### Parameters
-
-Name | Type | Description
------|------|--------------
-`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.
-`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.
+    http://your-application.com/callback?error=application_suspended
 
+Please contact [support](https://github.com/contact) to solve issues
+with suspended applications.
 
-<%= json :scopes => ["public_repo"], :note => 'admin script' %>
+### Redirect URI mismatch
 
-### Response
+If you provide a redirect_uri that doesn't match what you've registered
+with your application, GitHub will redirect to the registered callback
+URL with the following parameters summerizing the error:
 
-<%= headers 201, :Location => "https://api.github.com/authorizations/1"
-%>
-<%= json :oauth_access %>
+    http://your-application.com/callback?error=redirect_uri_mismatch
 
-## Get-or-create an authorization for a specific app
+To correct this error, either provide a redirect_uri that matches what
+you registered or leave out this parameter to use the default one
+registered with your application.
 
-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.
+### Access denied
 
-    PUT /authorizations/clients/:client_id
+If the user rejects access to your application, GItHub will redirect to
+the registered callback URL with the following parameters summerizing
+the error:
 
-### Parameters
+    http://your-application.com/callback?error=access_denied
 
-Name | Type | Description
------|------|--------------
-`client_secret`|`string`| 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.
+There's nothing you can do here as users are free to choose not to use
+your application. More often that not, users will just close the window
+or press back in their browser, so it is likely that you'll never see
+this error.
 
+## Common errors for the access token request
 
-<%= json :client_secret => "abcdabcdabcdabcdabcdabcdabcdabcdabcdabcd", :scopes => ["public_repo"], :note => 'admin script' %>
+In the second phase of exchanging a code for an access token, there are
+an additional set of errors that can occur. The format of these
+responses is determined by the accept header you pass. The following
+examples only show JSON responses.
 
-### Response if returning a new token
+### Invalid client credentials
 
-<%= headers 201, :Location => "https://api.github.com/authorizations/1"
-%>
-<%= json :oauth_access %>
+If the client\_id and or client\_secret you pass are incorrect you will
+receive this error response.
 
-### Response if returning an existing token
-
-<%= headers 200, :Location => "https://api.github.com/authorizations/1"
-%>
-<%= json :oauth_access %>
-
-## Update an existing authorization
-
-    PATCH /authorizations/:id
-
-### Parameters
-
-Name | Type | Description
------|------|--------------
-`scopes`|`array` | Replaces the authorization scopes with these.
-`add_scopes`|`array` | A list of scopes to add to this authorization.
-`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.
-
-
-You can only send one of these scope keys at a time.
-
-<%= json :add_scopes => ['repo'], :note => 'admin script' %>
-
-### Response
-
-<%= headers 200 %>
-<%= json :oauth_access %>
-
-## Delete an authorization
-
-    DELETE /authorizations/:id
-
-### Response
-
-<%= headers 204 %>
-
-## 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](/v3/auth#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
-
-<%= headers 200 %>
-<%= json(:oauth_access_with_user) %>
-
-## Revoke all authorizations for an application
-
-OAuth application owners can revoke every token for an OAuth application. You
-must use [Basic Authentication](/v3/auth#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
-
-<%= headers 204 %>
-
-## Revoke an authorization for an application
-
-OAuth application owners can also revoke a single token for an OAuth
-application. You must use [Basic Authentication](/v3/auth#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
+<%= json :error => :invalid_client_credentials %>
 
-<%= headers 204 %>
+To solve this error, go back and make sure you have the correct
+credentials for your oauth application. Double check the `client_id` and
+`client_secret` to make sure they are correct and being passed correctly
+to GitHub.
 
-## More Information
+### Bad verification code
 
+If the verification code you pass is incorrect, expired, or doesn't
+match what you received in the first request for authorization you will
+receive this error.
 
-It can be a little tricky to get started with OAuth. Here are a few
-links that might be of help:
+<%= json :error => :bad_verification_code %>
 
-* [OAuth 2 spec](http://tools.ietf.org/html/rfc6749)
-* [Facebook Login API](http://developers.facebook.com/docs/technical-guides/login/)
-* [Ruby OAuth2 lib](https://github.com/intridea/oauth2)
-* [Simple Ruby/Sinatra example](https://gist.github.com/9fd1a6199da0465ec87c)
-* [Python Flask example](https://gist.github.com/ib-lundgren/6507798) using [requests-oauthlib](https://github.com/requests/requests-oauthlib)
-* [Simple Python example](https://gist.github.com/e3fbd47fbb7ee3c626bb) using [python-oauth2](https://github.com/dgouldin/python-oauth2)
-* [Ruby OmniAuth example](https://github.com/intridea/omniauth)
-* [Ruby Sinatra extension](https://github.com/atmos/sinatra_auth_github)
-* [Ruby Warden strategy](https://github.com/atmos/warden-github)
+To solve this error, start the [OAuth process over from the beginning](#redirect-users-to-request-github-access)
+and get a new code.
 
-[app-listing]: https://github.com/settings/applications
 [oauth changes blog]: /changes/2013-10-04-oauth-changes-coming/
 [basics auth guide]: /guides/basics-of-authentication/
 [deployments]: /v3/repos/deployments
diff --git a/content/v3/oauth_authorizations.md b/content/v3/oauth_authorizations.md
diff --git a/layouts/sidebar.html b/layouts/sidebar.html
