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:

 

Screen Shot 2015-01-13 at 6.50.16 PM

 

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.

 

App credentials

 

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:

 

Oauth (1)

 

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.

 

response_type
required
Whether the endpoint returns an Authorization Code. For web applications, a value of code should be used. For browser-based apps or mobile apps token should be used. More information here.
client_id
required
The client_id you obtained in the Initial Setup.
redirect_uri
required
Redbooth will redirect the user back to the url specified in redirect_uri returning an Authorization Code. The redirect_uri must have the same hostname and path as the callback url specified in your app settings.

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:

invalid_request
The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.
unsupported_response_type

The authorization server does not support obtaining an authorization code using this method.

Check the value of the code param in your request.

access_denied
The resource owner or authorization server denied the request.
server_error
The device the user is trying to log in from is not authorized to access the user’s account.

 
 

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.