ver. 1958 (4e4db56)

Authorize the Request Token
:: services/oauth/authorize method

Minimum Authentication: Level 0 (see Authentication Levels)

Unlike other methods, the authorize method is to be executed inside the User's browser. Consumer's role is to redirect the User to this URL, then wait if he ever comes back with a callback request.

Once the User is redirected to this URL, several things will happen:

  • If he's not already logged in, he will be asked to do so.
  • OKAPI will check if the User haven't previously granted your application access to his Opencaching account.
  • If User did not previously authorize your application, OKAPI will display an "Authorization Request" form to the User. User will be presented with a choice to allow or not to allow your application access to his account.
  • If the User clicks one of these two options ("allow" or "don't allow"), he's browser will be redirected to the callback_url you defined while getting your Request Token. If you did not provide a callback (in other word, provided "oob"), user will be redirected to a default "authorized" page, where he will be presented with an oauth_verifier (user will know it by name of a PIN code) and asked to type it into your application.
oauth_token required Consult OAuth 1.0a documentation for details.
interactivity optional

Default value: minimal

Currently, one of the following values:

  • minimal - OKAPI will use as little interactivity as it can. It will assume that currently logged in user is the user which you want to authorize. If the user has already authorized your application, he will not be asked to do this again.
  • confirm_user - even if a user is logged in, OKAPI will NOT assume that this is the user who wants to be authorized. OKAPI will offer to authorize a different user (e.g. by automatically logging out the user who is currently logged in).
langpref optional

Pipe-separated list of ISO 639-1 language codes. This indicates the order of preference in which the language will be chosen for the authorization page.

By default, OKAPI will display the page in the primary native language of local Opencaching installation.

No additional authentication parameters are required.

Returned value:

Technically, an HTTP 302 Redirect - it will direct user's browser to the OKAPI apps authorization page.

Whether with callback_url or with a manual user entry - you will get your oauth_verifier, which allows you to continue the 3-legged authentication dance.

If you used callback_url, you should wait for an HTTP GET request, with one additional GET parameter appended:

  • oauth_token - the Request Token that has been just authorized,
  • oauth_verifier - the PIN code required to get an Access Token.

OR, in case when user denied the request:

  • oauth_token - the Request Token,
  • error - codename of an error - access_denied.