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.
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:
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:
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:
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:
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: 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