Authorizing via OAuth

Estimote Cloud’s RESTful API supports authorization via the OAuth 2.0 protocol, which allows third-party platforms to easily integrate with Estimote Cloud and query the Estimote Cloud RESTful API on behalf of their users.

Important: You only need OAuth if you’re building a generic app/platform, and want to give the users of your app/platform an option to connect their accounts with their Estimote Accounts—in a fashion similar to, e.g., Pinterest giving their users an option to connect their Facebook accounts, so that their pins are automatically posted to their Facebook feed.

For example, if you’re building a beacon CMS, you might want to set it up with our OAuth integration, so that the users of your CMS can connect their Estimote Accounts, and then your CMS can automatically import the list of their Estimote Beacons.

If, however, you only want your app to access your own Estimote Account, you don’t need to go through the OAuth integration process. Just add your own app to your Estimote Cloud account, and you’ll obtain an App ID and App Token necessary for the app to access your Estimote Account.

Read the full story behind OAuth support in the Estimote Cloud on our blog: OAuth support makes it easier to build beacon-enabled platforms powered by Estimote.

Keep in mind: At this time, we only support the Authorization Code method, which is suitable for every scenario in which you can treat your client secret … well, secret. This means e.g. server-side web apps (in which your secret is securely stored on your server), but not mobile apps or JavaScript apps (in which the secret is stored in the code that is potentially accessible to the general public).

Basic steps

1. Obtain your client ID and secret

Authorization via OAuth is currently in private beta. To obtain your client ID and client secret, please email us. No worries, we don’t bite! =:^)

2. Obtain the authorization code

Initiate the flow by redirecting the user of your app to:

https://cloud.estimote.com/v1/oauth2/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=YOUR_CALLBACK_URL

If the user is not logged into the Estimote Cloud, they’ll be asked to log in, and then presented with an authorization dialog:

OAuth authorization dialog

Once they allow your app to access their beacon data, they’ll be redirected to the URL indicated by the redirect_uri parameter. Assuming an example value of https://example.com/oauth2/callback, here’s what the final URL would look like:

https://example.com/oauth2/callback?code=e539vgttejnaweku60mdeeq1fixi5cx

Note the code parameter, which you’ll exchange for an access token in the next step.

3. Obtain the access token

To exchange your authorization code for an access token, issue a POST request to https://cloud.estimote.com/v1/oauth2/access_token with the following parameters included:

  • grant_type=authorization_code
  • code=YOUR_AUTHORIZATION_CODE
  • client_id=YOUR_CLIENT_ID
  • client_secret=YOUR_CLIENT_SECRET

This can be a regular application/x-www-form-urlencoded request or a JSON request—just make sure to set the Content-Type HTTP header accordingly.

The response is a JSON object containing your access token:

{access_token: "TOKEN_HERE"}

Make sure to save it, since for security reasons, each authorization code can only be redeemed once!

4. Query the API using the access token

Now that you have the access token at hand, you can query the Estimote Cloud RESTful API on behalf of the user that granted your app the appropriate authorization.

To authorize yourself with the access token, use the following Authorization header:

Authorization: Bearer TOKEN_HERE
# e.g. assuming the access token is "04isuvcxyeg26lhe3ac9zdg2rbfjr5g"
Authorization: Bearer 04isuvcxyeg26lhe3ac9zdg2rbfjr5g

For a full list of API methods available, consult the API documentation: cloud.estimote.com/docs