Apps connect to Redbooth via OAuth2, an open standard followed by most last generation APIs to authenticate and authorise external apps. The following walkthrough will show you how to register an app in Redbooth; how to get the authorisation from a user to retrieve private information from his Redbooth account and how to get an Access Token and a Refresh Token.

Start making API calls in three easy steps!

Authentication & Authorization Guide

Getting started with Redbooth’s API? Follow the steps and start enjoying our platform…

NOTE: OAuth 2 can have different architectures. Redbooth’s API v3 works with a 3 legged architecture and temporary tokens that require a refresh flow. The three entities involved are: the app, the user and the service provider (Redbooth). Let’s see how they work together:

1. Initial Setup, registering the application

Before you can start using OAuth2 with your application, you’ll need to tell Redbooth a bit of information about your application:

A) Register your application here:

Return URI or Callback URL: The redirect URI is the URL within your application that will receive the OAuth2 credentials.

B) Make a note of both your Api Key and App secret.

Now that you have your Client id and Client Secret, this is the flow that you will have to follow in order to get your Access Token and Refresh Token and start making calls to Redbooth’s API:

If this is your first time using OAuth2, we recommend you to take a look at the following article: http://oauth.net/about/. On the other hand, with Runscope’s Oauth2 Tool you will be able to get your Access Token and Refresh Token fast and easily, in an interactive way.

2. Getting the Authorization Code from the User

Direct your user to https://redbooth.com/oauth2/authorize through either a POST or a GET request with the following parameters:

Parameters: For POST, include the parameters in the POST body. For GET, include them as query parameters. In both cases, URL encode the parameters.

A sample GET request could therefore look like:
GET https://redbooth.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=http%3A%2F%2Fmysite.com%2Fauth&response_type=code
 

Handling the Response from Redbooth

If the user clicked Allow in the previous screen, Redbooth will redirect to the URI you specified earlier with a code parameter. For example, if your redirect URI was https://www.charle.com/rose, Redbooth would redirect to:
https://www.charle.com/rose?code=123456abcdef
 

However, if the user clicked Deny, you will receive a request with an error and error_description parameter, such as:
GET https://www.charle.com/rose?error=access_denied&error_description=The+user+denied+access+to+your+application
 

The following conditions may also cause an error:

3. Getting the Access Token from Redbooth

Once your application has completed the above section and gotten an Authorization Code, it’ll now need to exchange the Authorization Code for an Access Token from Redbooth. That Access Token will come with a Refresh Token that you will have to store in your app in order to refresh the Access Token when it expires. Each Access Token comes with its unique Refresh Token.

From your app, request an Access Token:
curl -X POST https://redbooth.com/oauth2/token -d 'client_id=APPLICATION_ID&client_secret=SECRET&code=THE_CODE_YOU_GOT_FROM_REDBOOTH&grant_type=authorization_code&redirect_uri=http%3A%2F%2Fmysite.com%2Faut'
 

If everything goes right and the request is successful, you’ll receive a 200 response containing a JSON body like this:

{"access_token":"1286198b9c618e86fcc7185338jddweet3wdasd342cf26a2bf84d5f7239b12343g","token_type":"bearer",
"expires_in":7200,"refresh_token":"c10e7790d130aasd3325e99ea3d123qiwfhfhgc3af93b2ce03506a63c7009992frt","scope":"all"}
 

Use the Access Token when performing requests. If you were, for example, trying to get a user’s account info, a request would look like this:
https://redbooth.com/api/3/me?access_token=urksAIU8RM0QWPVK7WxhK7RZ24PJ8fVeDSCdXAZG

NOTE: Tokens expire every 7200 seconds, two hours.

4. Refreshing the Access Token

Your Access Token will always expire after 7200 seconds (2 hours), that’s why it is extremely important to always keep the Refresh Token that Redbooth sends with each Access Token in your app. With that Refresh Token, you will be able to get a new Access Token and its corresponding Refresh Token.

This is the message that you will get if you try to make a call with an expired Access Token:


< Status: 401 Unauthorized < WWW-Authenticate: Bearer realm="Doorkeeper", error="invalid_token", error_description="The access token expired"

Make a call like this one and you will get a new Access Token with its corresponding Refresh Token:

curl -X POST https://redbooth.com/oauth2/token -d 'client_id=APPLICATION_ID&client_secret=SECRET&refresh_token=REFRESH_TOKEN&grant_type=refresh_token'
 

Here's an example answer:

{"access_token":"f5fa837fbde6224c0fad6a029654a9d5a9292e63fcc708204151cf65ddf882de","token_type":"bearer",
"expires_in":7200,"refresh_token":"1b2225c55bea5a985aa9d625ff9b89f3246c9ec59d7ae120d261c76fe4b4d886","scope":"all"}

NOTE: Take into account that you will have to update the stored Refresh Token every time you ask for a new Access Token, since each Access Token has his unique Refresh Token.

Additional resources

If you're planning to work with Ruby, Redbooth's Official Ruby Gem will make your life easier! Check how we deal with the authentication process in GitHub.