Fandom

Resighting Wiki

Authorisation Guide

71pages on
this wiki
Add New Page
Comments0 Share

Authorisation is the process of asking a user of Resighting if they wish your Application to be able to access their Resighting account on their behalf. Resighting users never enter their credentials into your website or native application, your Application should redirect the user to a page on the Resighting website where they can log in and view the details of your Application and decide whether they wish to accept or deny. If they accept, your Application will be provided with an Access Token with which to access the API.

An Access Token is specific to your Application and the user who authorised it, and the user may cancel it any time they no longer wish to use your Application.


Creating an ApplicationEdit

Before any authorisation can take place you need to register your Application with Resighting. In order to do this see the Application Creation Guide.

OAuth 2.0Edit

For authorisation, the Resighting API uses OAuth 2.0. This page isn’t designed to be full documentation of OAuth 2.0 but a quick-start to give you an idea of what’s involved. We recommend you take a look at the OAuth 2.0 documentation available at http://oauth.net/2/ before starting to work with the API.

AuthorisationEdit

Once you have created your Application you need to get an Access Token to pass to each API method. An Access Token allows your Application to access Resighting on behalf of one user. For example, if your Application represents an iPhone App which uses Resighting data, you will create an Application for your iPhone App and then each user who uses your iPhone App will have to authorise with the Resighting API and each will have a distinct Access Token.

The most important concept behind the Resighting API authorisation process is that Resighting users must not enter their Resighting credentials into your application or website, you must redirect them to a page on resighting.com where they enter their credentials and choose whether to give your application access. If your application is a website then redirecting to resighting.com should not be a problem, if you have a native application then it may be a little more work to embed or call-out to a web browser.

Resighting supports two flows defined by OAuth 2.0 - the Authorisation Code flow and the Implicit flow, which are suitable for different types of application. When you created your Application, if you chose Native Application for your application type then you will be using the Implicit Flow, while if you chose Website you will be using the slightly more complicated but more secure Authorisation Code flow. For more information on flows please read the OAuth 2.0 documentation.

Depending upon your chosen application type jump to the appropriate flow below.

Implicit Flow (for application type native application)Edit

This flow must be used for Applications which cannot keep their Client Secret a secret. Examples of this type of Application are Javascript applications running in web browsers (because the Javascript code and therefore the Client Secret are visible publicly) and iPhone apps (because the distributed app can be decompiled to reveal the Client Secret). If the Application can keep the Client Secret a secret the Authorisation Code flow should be used instead as it provides better security.

When a user wants to use your application with Resighting, redirect a web browser to the following url. Note that this request must use a non-SSL http connection.

http://www.resighting.com/oauth?response_type=token&client_id=APPLICATION_ID&redirect_uri=REDIRECT_URI&state=STATE


If your Application runs on a mobile device you may wish to use the mobile website instead which is optimised for smaller screens. To do this replace the first part of the url above with http://www.resighting.com/m/oauth.

Insert into the url:

  • The unique APPLICATION_ID for your Application which was created when you registered your Application and can be retrieved on the Resighting developer website.
  • A REDIRECT_URI to which Resighting will redirect the web browser after the user has accepted or denied access by your Application. The Access Token or error message (for example if the user has denied access) will be encoded in the fragment of this URI.
  • An optional STATE which should be a randomly-generated string which Resighting will pass back to you in the redirect URI. You should check that this string is the same that you passed-in to help protect again cross-site request forgeries.

At the above url the user is asked first to log in if they aren’t already logged-in and then they are displayed the name and description of your Application, a link to your website and asked whether they wish to allow your application access to their Resighting account. The page looks as follows:

Create Application 4














When the user accepts or denies, Resighting redirects the web browser to the redirect URI which you specified. If the user authorised the connection the Access Token will be contained in the fragment, for example:

resighting:/oauth#access_token=7ab9e944aadd97d6fa92c904620959a6&token_type=http%3A%2F%2Fwww.resighting.com%2Foauth%2Ftoken_type&state=1234


If an error occurs then the error details are included in the fragment in the following two fields:

  • error: A short string representing the type of error.
  • error_description: More details of the error.


A list of possible errors can be found in the OAuth 2.0 documentation. For example, if the user denies access:

resighting:/oauth#state=1234&error_description=The+user+denied+the+request+to+authorise&error=access_denied

Authorisation Code Flow (for application type website)Edit

This flow must be used for Applications which can keep their Client Secret a secret. It provides more security than the Implicit flow as long as the Client Secret can be kept a secret. It is perfect if your Application is a website as the Client Secret can be maintained on the server where it is not accessible publicly. Note that if the authorisation is performed from Javascript running on your website then it probably won't be possible for you to keep the Client Secret a secret and the Implicit flow would be better.

Unlike the Implicit flow, with the Authorisation Code flow there are two calls which need to be made to Resighting in order to obtain an Access Token. The first call is almost identical to the call for the Implicit flow but this time it results in an Authorisation Code rather than an Access Token. You then make a second call to Resighting passing the Authorisation Code obtained from the first call and your Client Secret to prove to Resighting that you are who you say you are. The response from the second call contains the Access Token.

Step 1: Obtain an Authorisation CodeEdit

When a user wants to use your application with Resighting, redirect a web browser to the following url. Note that this request must use a non-SSL http connection.

http://www.resighting.com/oauth?response_type=code&client_id=APPLICATION_ID&redirect_uri=REDIRECT_URI&state=STATE


Note that the difference between this url and the one used for the Implicit flow lies in the response_type query parameter.

If your Application runs on a mobile device you may wish to use the mobile website instead which is optimised for smaller screens. To do this replace the first part of the url above with http://www.resighting.com/m/oauth.

Insert into the url:

  • The unique APPLICATION_ID for your Application which was created when you registered your Application and can be retrieved on the Resighting developer website.
  • A REDIRECT_URI to which Resighting will redirect the web browser after the user has accepted or denied access by your Application. The Authorisation Code or error message (for example if the user has denied access) will be encoded as query parameters of this URI. Note in the query parameters and not in the fragment as is the case for the Implicit flow.
  • An optional STATE which should be a randomly-generated string which Resighting will pass back to you in the redirect URI. You should check that this string is the same that you passed-in to help protect again cross-site request forgeries.

At the above url the user is asked first to log in if they aren’t already logged-in and then they are displayed the name and description of your Application, a link to your website and asked whether they wish to allow your application access to their Resighting account. The page looks as follows:

Create Application 4














When the user accepts or denies, Resighting redirects the web browser to the redirect URI which you specified. If the user authorised the connection an Authorisation Code will be specified in a query parameter, for example:

https://example.com/resighting?state=1234&code=19bc679e17a71c58bc81c9ffd7bd3a66

If an error occurs then the error details are included as query parameters with the following names:

  • error: A short string representing the type of error.
  • error_description: More details of the error.

A list of possible errors can be found in the OAuth 2.0 documentation. For example, if the user denies access:

https://example.com/resighting?state=1234&error_description=The+user+denied+the+request+to+authorise&error=access_denied

Step 2: Obtain an Access TokenEdit

Once you have successfully obtained an Authorisation Code you can make the second call to Resighting, passing the Authorisation Code and your Client Secret. A successful second call results in an Access Token.

This call must be a POST request and it does not require any interaction from the user so it does not need to be performed via a redirect in the web browser.

Make a POST request to the url https://resighting-api.appspot.com/oauth/access_token. This call must use SSL and note the use of the domain resighting-api.appspot.com rather than www.resighting.com.

Prior to August 2013, all API access was to https://resighting.appspot.com. This URL remains active, however we recommend switching over to https://resighting-api.appspot.com when possible.

The following data should be contained in the request encoded as application/x-www-form-urlencoded:

  • grant_type: Set to the string “authorization_code”.
  • code: The Authorisation Code returned in the first step.
  • redirect_uri: Exactly the same redirect URI that you sent Resighting in the first step. Resighting does not redirect to this URI in this step but does check that it is the same URI which was specified in step 1.
  • client_id: Your Application's Application Id.
  • client_secret: Your Application's Client Secret.

If the call is successful the response is a JSON document containing the Access Token, for example:

{
    "access_token":"263275da27a80922d0e104c6cd9fb42a",
    "token_type":"http://www.resighting.com/oauth/token_type"
}

If an error occurs the response is a JSON document containing details of the error using the two standard elements error and error_description described in step 1.

Worthy of note is that Authorisation Codes are only valid for 60 seconds, after which you'll have to perform Step 1 again. If you provide an Authorisation Code to this step which has expired you'll get the following error:

{
    "error":"invalid_grant",
    "error_description":"Code has expired"
}

Redirect URIsEdit

When invoking the Resighting authorisation urls you need to specify a redirect URI to which Resighting will redirect the web browser once the user has chosen whether to accept or deny your authorisation request.

What you use for this URI will depend upon the type of application you are integrating with Resighting. Some examples are given below.

WebsitesEdit

If your application is a website you'll most likely want Resighting to redirect to a page on your website which you can then use to process the response. In the Authorisation Code flow example above we gave the following example URI:

https://example.com/resighting


If the user accepts the authorisation request then Resighting would redirect to the following URL:

https://example.com/resighting?state=1234&code=19bc679e17a71c58bc81c9ffd7bd3a66


The page you implement at that URL can extract the Authorisation Code and do whatever processing is necessary.

Note that if your redirect URI is a web page it MUST be on the same domain as the URL you specified when you created your Application (see Create Application). Redirect URLs can be SSL or not as required, though SSL is recommended.

Native ApplicationsEdit

If your application is a native application you'll need a mechanism for your native application to be notified when the web browser you have launched is redirected. How you do this is beyond the scope of this document and will vary from platform to platform.

As an example though, in iOS you can define a URI scheme which when opened in the web browser causes your app to be opened. The Resighting iPhone app defines the scheme resighting and when the URI we gave as an example in the Implicit flow above is visited, the iPhone app is opened and can process the fragment containing the Access Token.

resighting:/oauth#access_token=7ab9e944aadd97d6fa92c904620959a6&token_type=http%3A%2F%2Fwww.resighting.com%2Foauth%2Ftoken_type&state=1234

Obtaining details of the Resighting userEdit

Once you have obtained an Access Token from the Resighting authorisation endpoints you'll probably need to store it for later use when invoking API methods.

One of the first things you are likely to want to do is to find out the details of the user who authorised. You can do this by calling the User method as follows. Note the use of SSL and the domain resighting-api.appspot.com for all API access.

$ curl https://resighting-api.appspot.com/api/1/user?access_token=ACCESS_TOKEN

Ad blocker interference detected!


Wikia is a free-to-use site that makes money from advertising. We have a modified experience for viewers using ad blockers

Wikia is not accessible if you’ve made further modifications. Remove the custom ad blocker rule(s) and the page will load as expected.