@@ -110,10 +110,19 @@ The access token allows you to make requests to the API on a behalf of a user.
110110
111111GET https://api.github.com/user?access_token=...
112112
113+ You can pass the token in the query params like shown above, but a
114+ cleaner approach is to include it in the Authorization header
115+
116+ Authorization: token OAUTH-TOKEN
117+
118+ For example, in curl you can set the Authorization header like this:
119+
120+ curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com/user
121+
113122##Non-Web Application Flow
114123
115124Use[ Basic Authentication] ( /v3/auth#basic-authentication ) to create an OAuth2
116- token using the[ interface below] ( /v3/oauth /#create-a-new-authorization ) . With
125+ token using the[ interface below] ( /v3/oauth_authorizations /#create-a-new-authorization ) . With
117126this technique, a username and password need not be stored permanently, and the
118127user can revoke access at any time. (Make sure to understand how to[ work with
119128two-factor authentication] ( /v3/auth/#working-with-two-factor-authentication ) if
@@ -129,7 +138,7 @@ subdirectory of the callback URL.
129138
130139CALLBACK: http://example.com/path
131140
132- GOOD:https ://example.com/path
141+ GOOD:http ://example.com/path
133142GOOD: http://example.com/path/subdir/other
134143BAD: http://example.com/bar
135144BAD: http://example.com/
@@ -182,189 +191,79 @@ can specify multiple scopes by separating them with a comma:
182191 client_id=...&
183192 scope=user,public_repo
184193
185- ##OAuth Authorizations API
186-
187- There is an API for users to manage their own tokens. You can only access your
188- own tokens, and only via[ Basic Authentication] ( /v3/auth#basic-authentication ) .
189- (Make sure to understand how to[ work with two-factor
190- authentication] ( /v3/auth/#working-with-two-factor-authentication ) if you or your
191- users have two-factor authentication enabled.)
192-
193- ##List your authorizations
194-
195- GET /authorizations
196-
197- ###Response
198-
199- <%= headers 200,: pagination => default_pagination_rels %>
200- <%= json(: oauth_access ) { |h|[ h] } %>
201-
202- ##Get a single authorization
203-
204- GET /authorizations/:id
205-
206- ###Response
207-
208- <%= headers 200 %>
209- <%= json: oauth_access %>
194+ ##Common errors for the authorization request
210195
211- ##Create a new authorization
196+ There are a few things that can go wrong in the process of obtaining an
197+ OAuth token for a user. In the initial authorization request phase,
198+ these are some errors you might see:
212199
213- If you need a small number of tokens, implementing the[ web flow] ( #web-application-flow )
214- can be cumbersome. Instead, tokens can be created using the Authorizations API using
215- [ Basic Authentication] ( /v3/auth#basic-authentication ) . To create tokens for a particular OAuth application, you
216- must provide its client ID and secret, found on the OAuth application settings
217- page, linked from your[ OAuth applications listing on GitHub] [ app-listing ] . OAuth tokens
218- can also be created through the web UI via the[ Application settings page] ( https://github.com/settings/applications ) .
219- Read more about these tokens on the[ GitHub Help page] ( https://help.github.com/articles/creating-an-access-token-for-command-line-use ) .
200+ ###Application Suspended
220201
221- POST /authorizations
202+ If the OAuth application you set up has been suspended (due to reported
203+ abuse, spam, or a mis-use of the API), GitHub will redirect to the
204+ registered callback URL with the following parameters summerizing the
205+ error:
222206
223- ###Parameters
224-
225- Name | Type | Description
226- -----|------|--------------
227- ` scopes ` |` array ` | A list of scopes that this authorization is in.
228- ` note ` |` string ` | A note to remind you what the OAuth token is for.
229- ` note_url ` |` string ` | A URL to remind you what app the OAuth token is for.
230- ` client_id ` |` string ` | The 20 character OAuth app client key for which to create the token.
231- ` client_secret ` |` string ` | The 40 character OAuth app client secret for which to create the token.
207+ http://your-application.com/callback?error=application_suspended
232208
209+ Please contact[ support] ( https://github.com/contact ) to solve issues
210+ with suspended applications.
233211
234- <%= json : scopes => [ "public_repo" ] , : note => 'admin script' %>
212+ ### Redirect URI mismatch
235213
236- ###Response
214+ If you provide a redirect_uri that doesn't match what you've registered
215+ with your application, GitHub will redirect to the registered callback
216+ URL with the following parameters summerizing the error:
237217
238- <%= headers 201,: Location => "https://api.github.com/authorizations/1 "
239- %>
240- <%= json: oauth_access %>
218+ http://your-application.com/callback?error=redirect_uri_mismatch
241219
242- ##Get-or-create an authorization for a specific app
220+ To correct this error, either provide a redirect_uri that matches what
221+ you registered or leave out this parameter to use the default one
222+ registered with your application.
243223
244- This method will create a new authorization for the specified OAuth application,
245- only if an authorization for that application doesn't already exist for the
246- user. (The URL includes the 20 character client ID for the OAuth app that is
247- requesting the token.) It returns the user's token for the application if one
248- exists. Otherwise, it creates one.
224+ ###Access denied
249225
250- PUT /authorizations/clients/:client_id
226+ If the user rejects access to your application, GItHub will redirect to
227+ the registered callback URL with the following parameters summerizing
228+ the error:
251229
252- ### Parameters
230+ http://your-application.com/callback?error=access_denied
253231
254- Name | Type | Description
255- -----|------|--------------
256- ` client_secret ` |` string ` | The 40 character OAuth app client secret associated with the client ID specified in the URL.
257- ` scopes ` |` array ` | A list of scopes that this authorization is in.
258- ` note ` |` string ` | A note to remind you what the OAuth token is for.
259- ` note_url ` |` string ` | A URL to remind you what app the OAuth token is for.
232+ There's nothing you can do here as users are free to choose not to use
233+ your application. More often that not, users will just close the window
234+ or press back in their browser, so it is likely that you'll never see
235+ this error.
260236
237+ ##Common errors for the access token request
261238
262- <%= json: client_secret => "abcdabcdabcdabcdabcdabcdabcdabcdabcdabcd",: scopes =>[ "public_repo"] ,: note => 'admin script' %>
239+ In the second phase of exchanging a code for an access token, there are
240+ an additional set of errors that can occur. The format of these
241+ responses is determined by the accept header you pass. The following
242+ examples only show JSON responses.
263243
264- ###Response if returning a new token
244+ ###Invalid client credentials
265245
266- <%= headers 201,: Location => "https://api.github.com/authorizations/1 "
267- %>
268- <%= json: oauth_access %>
246+ If the client\_ id and or client\_ secret you pass are incorrect you will
247+ receive this error response.
269248
270- ###Response if returning an existing token
271-
272- <%= headers 200,: Location => "https://api.github.com/authorizations/1 "
273- %>
274- <%= json: oauth_access %>
275-
276- ##Update an existing authorization
277-
278- PATCH /authorizations/:id
279-
280- ###Parameters
281-
282- Name | Type | Description
283- -----|------|--------------
284- ` scopes ` |` array ` | Replaces the authorization scopes with these.
285- ` add_scopes ` |` array ` | A list of scopes to add to this authorization.
286- ` remove_scopes ` |` array ` | A list of scopes to remove from this authorization.
287- ` note ` |` string ` | A note to remind you what the OAuth token is for.
288- ` note_url ` |` string ` | A URL to remind you what app the OAuth token is for.
289-
290-
291- You can only send one of these scope keys at a time.
292-
293- <%= json: add_scopes =>[ 'repo'] ,: note => 'admin script' %>
294-
295- ###Response
296-
297- <%= headers 200 %>
298- <%= json: oauth_access %>
299-
300- ##Delete an authorization
301-
302- DELETE /authorizations/:id
303-
304- ###Response
305-
306- <%= headers 204 %>
307-
308- ##Check an authorization
309-
310- OAuth applications can use a special API method for checking OAuth token
311- validity without running afoul of normal rate limits for failed login attempts.
312- Authentication works differently with this particular endpoint. You must use
313- [ Basic Authentication] ( /v3/auth#basic-authentication ) when accessing it, where the username is the OAuth
314- application` client_id ` and the password is its` client_secret ` . Invalid tokens
315- will return` 404 NOT FOUND ` .
316-
317- GET /applications/:client_id/tokens/:access_token
318-
319- ###Response
320-
321- <%= headers 200 %>
322- <%= json(: oauth_access_with_user ) %>
323-
324- ##Revoke all authorizations for an application
325-
326- OAuth application owners can revoke every token for an OAuth application. You
327- must use[ Basic Authentication] ( /v3/auth#basic-authentication ) when calling
328- this method. The username is the OAuth application` client_id ` and the password
329- is its` client_secret ` . Tokens are revoked via a background job, and it might
330- take a few minutes for the process to complete.
331-
332- DELETE /applications/:client_id/tokens
333-
334- ###Response
335-
336- <%= headers 204 %>
337-
338- ##Revoke an authorization for an application
339-
340- OAuth application owners can also revoke a single token for an OAuth
341- application. You must use[ Basic Authentication] ( /v3/auth#basic-authentication )
342- for this method, where the username is the OAuth application` client_id ` and
343- the password is its` client_secret ` .
344-
345- DELETE /applications/:client_id/tokens/:access_token
346-
347- ###Response
249+ <%= json: error =>: invalid_client_credentials %>
348250
349- <%= headers 204 %>
251+ To solve this error, go back and make sure you have the correct
252+ credentials for your oauth application. Double check the` client_id ` and
253+ ` client_secret ` to make sure they are correct and being passed correctly
254+ to GitHub.
350255
351- ##More Information
256+ ### Bad verification code
352257
258+ If the verification code you pass is incorrect, expired, or doesn't
259+ match what you received in the first request for authorization you will
260+ receive this error.
353261
354- It can be a little tricky to get started with OAuth. Here are a few
355- links that might be of help:
262+ <%= json: error =>: bad_verification_code %>
356263
357- * [ OAuth 2 spec] ( http://tools.ietf.org/html/rfc6749 )
358- * [ Facebook Login API] ( http://developers.facebook.com/docs/technical-guides/login/ )
359- * [ Ruby OAuth2 lib] ( https://github.com/intridea/oauth2 )
360- * [ Simple Ruby/Sinatra example] ( https://gist.github.com/9fd1a6199da0465ec87c )
361- * [ Python Flask example] ( https://gist.github.com/ib-lundgren/6507798 ) using[ requests-oauthlib] ( https://github.com/requests/requests-oauthlib )
362- * [ Simple Python example] ( https://gist.github.com/e3fbd47fbb7ee3c626bb ) using[ python-oauth2] ( https://github.com/dgouldin/python-oauth2 )
363- * [ Ruby OmniAuth example] ( https://github.com/intridea/omniauth )
364- * [ Ruby Sinatra extension] ( https://github.com/atmos/sinatra_auth_github )
365- * [ Ruby Warden strategy] ( https://github.com/atmos/warden-github )
264+ To solve this error, start the[ OAuth process over from the beginning] ( #redirect-users-to-request-github-access )
265+ and get a new code.
366266
367- [ app-listing ] :https://github.com/settings/applications
368267[ oauth changes blog ] :/changes/2013-10-04-oauth-changes-coming/
369268[ basics auth guide ] :/guides/basics-of-authentication/
370269[ deployments ] :/v3/repos/deployments