{"id":21,"date":"2014-04-17T22:18:43","date_gmt":"2014-04-17T22:18:43","guid":{"rendered":"http:\/\/developer-beta.redbooth.com\/?page_id=21"},"modified":"2020-01-09T20:41:45","modified_gmt":"2020-01-09T20:41:45","slug":"authentication","status":"publish","type":"page","link":"https:\/\/redbooth.com\/api\/authentication\/","title":{"rendered":"Authentication"},"content":{"rendered":"
\n

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.<\/p>\n

Start making API calls in three easy steps<\/a>!<\/p>\n

 <\/p>\n

Authentication & Authorization Guide<\/span><\/h1>\n

Getting started with Redbooth’s API? <\/em>Follow the steps and start enjoying our platform…<\/em><\/p>\n

 <\/p>\n

NOTE:<\/strong> 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:<\/p>\n

 <\/p>\n

1. Initial Setup, registering the application<\/h3>\n

 <\/p>\n

Before you can start using OAuth2 with your application, you\u2019ll need to tell Redbooth a bit of information about your application:<\/p>\n

 <\/p>\n

A) Register your application here<\/a>:<\/p>\n

 <\/p>\n

\"Screen<\/a><\/p>\n

 <\/p>\n

Return URI or Callback URL:<\/strong> The redirect URI is the URL within your application that will receive the OAuth2 credentials.<\/p>\n

 <\/p>\n

B) Make a note of both your Api Key and App secret.<\/p>\n

 <\/p>\n

\"App<\/a><\/p>\n

 <\/p>\n

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:<\/p>\n

 <\/p>\n

\"Oauth<\/a><\/p>\n

 <\/p>\n

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

 
\n <\/p>\n

2. Getting the Authorization Code from the User<\/h3>\n

 <\/p>\n

Direct your user to https:\/\/redbooth.com\/oauth2\/authorize<\/a> through either a POST<\/strong> or a GET<\/strong> request with the following parameters:<\/p>\n

Parameters:<\/strong> For POST, include the parameters in the POST body. For GET, include them as query parameters. In both cases, URL encode<\/strong> the parameters.<\/p>\n

 <\/p>\n

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

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

Handling the Response from Redbooth<\/strong><\/p>\n

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:
\nhttps:\/\/www.charle.com\/rose?code=123456abcdef<\/code>
\n <\/p>\n

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

The following conditions may also cause an error:<\/strong><\/p>\n

\n
invalid_request<\/div>\n
The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.<\/div>\n
<\/div>\n
unsupported_response_type<\/div>\n
\n

The authorization server does not support obtaining an authorization code using this method.<\/p>\n

Check the value of the code<\/em> param in your request.<\/p>\n<\/div>\n

<\/div>\n
access_denied<\/div>\n
The resource owner or authorization server denied the request.<\/div>\n
<\/div>\n
server_error<\/div>\n
The device the user is trying to log in from is not authorized to access the user\u2019s account.<\/div>\n
<\/div>\n<\/div>\n

 
\n <\/p>\n

3. Getting the Access Token from Redbooth<\/h3>\n

 <\/p>\n

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.<\/p>\n

 <\/p>\n

From your app, request an Access Token:
\ncurl -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'<\/code>
\n <\/p>\n

If everything goes right and the request is successful, you’ll receive a 200 response containing a JSON body like this:<\/p>\n

{\"access_token\":\"1286198b9c618e86fcc7185338jddweet3wdasd342cf26a2bf84d5f7239b12343g\",\"token_type\":\"bearer\",
\n\"expires_in\":7200,\"refresh_token\":\"c10e7790d130aasd3325e99ea3d123qiwfhfhgc3af93b2ce03506a63c7009992frt\",\"scope\":\"all\"}<\/code>
\n <\/p>\n

Use the Access Token when performing requests. If you were, for example, trying to get a user\u2019s account info, a request would look like this:
\nhttps:\/\/redbooth.com\/api\/3\/me?access_token=urksAIU8RM0QWPVK7WxhK7RZ24PJ8fVeDSCdXAZG<\/code><\/p>\n

NOTE:<\/strong> Tokens expire every 7200 seconds, two hours.<\/p>\n

 
\n <\/p>\n

4. Refreshing the Access Token<\/h3>\n

 <\/p>\n

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.<\/p>\n

This is the message that you will get if you try to make a call with an expired Access Token:<\/p>\n


\n< Status: 401 Unauthorized\n< WWW-Authenticate: Bearer realm=\"Doorkeeper\", error=\"invalid_token\", error_description=\"The access token expired\"\n<\/code><\/p>\n

 <\/p>\n

Make a call like this one and you will get a new Access Token with its corresponding Refresh Token:<\/p>\n

curl -X POST https:\/\/redbooth.com\/oauth2\/token -d 'client_id=APPLICATION_ID&client_secret=SECRET&refresh_token=REFRESH_TOKEN&grant_type=refresh_token'<\/code>
\n <\/p>\n

Here's an example answer:<\/p>\n

{\"access_token\":\"f5fa837fbde6224c0fad6a029654a9d5a9292e63fcc708204151cf65ddf882de\",\"token_type\":\"bearer\",
\n\"expires_in\":7200,\"refresh_token\":\"1b2225c55bea5a985aa9d625ff9b89f3246c9ec59d7ae120d261c76fe4b4d886\",\"scope\":\"all\"}<\/code><\/p>\n

 <\/p>\n

NOTE: <\/strong>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.<\/p>\n

 
\n <\/p>\n

Additional resources<\/h3>\n

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

 <\/p>\n","protected":false},"excerpt":{"rendered":"

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 … Continued<\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"parent":0,"menu_order":0,"comment_status":"open","ping_status":"open","template":"template-redbooth-pages.php","meta":{"footnotes":""},"class_list":["post-21","page","type-page","status-publish","hentry"],"_links":{"self":[{"href":"https:\/\/redbooth.com\/api\/wp-json\/wp\/v2\/pages\/21","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/redbooth.com\/api\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/redbooth.com\/api\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/redbooth.com\/api\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/redbooth.com\/api\/wp-json\/wp\/v2\/comments?post=21"}],"version-history":[{"count":0,"href":"https:\/\/redbooth.com\/api\/wp-json\/wp\/v2\/pages\/21\/revisions"}],"wp:attachment":[{"href":"https:\/\/redbooth.com\/api\/wp-json\/wp\/v2\/media?parent=21"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}