For a quick overview of the OAuth 2.0. flow, please, review our Quickstart guides:
Cloudbeds API v1.1 implements OAuth 2.0 to securely enable applications to access Cloudbeds resources on behalf of a customer.
OAuth 2.0 is a protocol that allows your application, after granted the correct authorization, to request (create/read/update/delete) private details in your customer's Cloudbeds account. This without getting and/or storing their password.
All OAuth 2.0 integrations must use the Authorization Code grant type when requesting access to customer data. At no point does the customer supply their Cloudbeds credentials to your application. Rather, they are redirected to Cloudbeds to authorize your application to access data and make changes on their behalf.
For first time OAuth 2.0 implementers we recommend reading the following documentation and articles. OAuth 2.0 can be tricky initially.
To see a visual representation of the authorization flow check out our User authorization flow guide.
OAuth 2.0 Flow
- Customer (resource owner) is using your application.
- Customer would like to grant your application permission to access and/or make changes to their Cloudbeds data on their behalf.
- To initiate connection you provide the customer with OAuth URL (via a button in your app "Connect to Cloudbeds") or they find it Cloudbeds Marketplace.
-
client_id- Client ID issued by Cloudbeds (find it in App Details page). -
redirect_uri- The endpoint at your application where Cloudbeds forwards authorization codes. -
response_type- Must be code, as the only supported grant type is Authorization code. -
scope- Permissions defined for each method. Find it in API documentation.
-
OAuth URL can be custom built or you can find your preconfigured OAuth link in App Details page of your Cloudbeds Technology Partner Account.
Example: https://hotels.cloudbeds.com/api/v1.1/oauth?client_id=[client_id]&redirect_uri=[redirect_uri]&response_type=code
Make sure to add all the correct scopes to your OAuth URL. When adding additional scopes previously authorized sessions need to be re-authorized to apply new scope. Notify your users, otherwise they won't be able to use newly added functionality.
- When a customer clicks the OAuth URL, they are redirected to Cloudbeds (Authorization Server) to authorize your application's access to their data via API method
/oauth. - If the customer is not currently logged-in to Cloudbeds, they will be presented with the login form.
- Upon successfully logging in, the customer is redirected to the authorization page.
- The customer is presented with "Application XYZ would like access to your Cloudbeds account...", requiring them to "Approve" or "Deny" your application's access to their Cloudbeds data. Customer will also see which permissions your application is requesting, based on the permissions defined by API method/oauth parameter named "scope".
Outcome
- If denied, a permission not granted error is forwarded to your preconfigured redirect URI (callback URL).
- If accepted, an authorization code is forwarded to your preconfigured redirect URI (callback URL).
- The handler at your redirect URI uses the authorization code to request an access token from the
/access_tokenAPI method (Authorization Server). - The
access_tokenreturned by/access_tokenmay be used to access Cloudbeds resources (Resource Server) on behalf of the customer by including it in the authorization header of your resource requests (Authorization: Bearer vjsZOLa2tMazV09T01SlwIQGq8HC56LYL8kXcBBp). - The
refresh_tokenreturned by/access_tokenmay be used to acquire a newaccess_tokenafter token expiration without requiring steps 1-4 again.
Once you make a request to issue new access_token you can't use access_token you had before anymore. You must use the new one.refresh_token is permanent and the same refresh_token is returned whenever an access_token is requested. If you didn't save the new access_token, you still can use the refresh_token to request a new token.
If you didn't save the new access_tokenand don’t have the refresh_token, you will need to re-authorize by starting the process from Step 1.
Example
- You have the
access_token0/refresh_tokenpair. - You make a request for a new access token by using
refresh_tokenand our authorization server issues a new pairaccess_token1. - From this moment all your requests to get resource with
access_token0will fail. - But if you weren't able to save
access_token1you can userefresh_tokento acquire a token again. - NOTE: If you requested multiple token pairs once you use one access token from any pair the other pairs are invalidated.
N.B.: Access token expires every 1 hour (3600 seconds). Refresh token persists after every use and does not expire.
Store the access_token and refresh_token using customer session data in a secure location defined by your client device type.
If you want to know the basic information of the user that has authorized the connection use /userinfo endpoint.
If your application integrates and interacts with MFD backend, or you want us to keep track of a client integration status:
- Your application can send us a call to
/postAppStatemethod, and this status can be retrieved later by/getAppStatemethod. - Read more about how technology partner apps should handle Connecting / Disconnecting with
/postAppState
Test the flow
It's a good idea to test the flow before writing any code. You'll need following credentials to begin:
client_id :: Your application client ID
client_secret :: Your application client secret
redirect_uri :: Your application redirect URL (pre-configured)
Expected Result: 302 redirect to authorization
Expected Result: 302 redirect to your redirect URI
If your redirection URI was https://www.myredirecturi.com/oauth_code, the redirection would be: https://www.myredirecturi.com/oauth_code?code=ob7ajLINOP1VNnMfAxCu1aX4jBvyz6vg&state=12ddc1756afbc3552728d5bb44c78
Request (CURL):
curl "https://hotels.cloudbeds.com/api/v1.1/access_token" -d 'grant_type=authorization_code&client_id=your_client_id&client_secret=your_client_secret&redirect_uri=your_redirect_uri&code=ob7ajLINOP1VNnMfAxCu1aX4jBvyz6vg'Expected Result:
{"access_token": "JtRTwXyjzn5MHi4Ml7y9M2gDM5URfapJhraTnqsQ",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "HN6OyEBEb4eStTJFvTAoiixL3LaWYBngACfdpoI4"}Request (CURL):
curl -H "Authorization: Bearer JtRTwXyjzn5MHi4Ml7y9M2gDM5URfapJhraTnqsQ" https://hotels.cloudbeds.com/api/v1.1/access_token_checkExpected Result:
{"success": true}Request (CURL):
curl "https://hotels.cloudbeds.com/api/v1.1/access_token" -d 'grant_type=refresh_token&client_id=your_client_id&client_secret=your_client_secret&refresh_token=HN6OyEBEb4eStTJFvTAoiixL3LaWYBngACfdpoI4'Expected Result:
{"access_token": "dNqq4S5chDGCesVUqQK99xxTWr7Vaja2XOmUnbsH",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "UQLAqfcxoj0dIOmA97qBQUtVXKQt81wpm6pRWowV"}We strongly recommend not to use webhooks as a trigger to refresh the token pair as they can come in simultaneously and cause invalidation of tokens.
If the Refresh Token expires with token has expired error, then the first action is for the property to re-authorize the app, please see from step 1 in this article. If after that, the issue continues with "token has been revoked / Invalid" then is important to review this section 4. Request access/refresh token pair highlighted in red to ensure that the token handling is correct. It's also important to ensure that webhooks are not used as a trigger for token pair refresh.
It's possible to send information to Cloudbeds authorization and this information will be relayed back to you on your redirect URI endpoint.
The state parameter is defined on RFC 6749 (https://tools.ietf.org/html/rfc6749).
The request below is used to start the OAuth authorization flow and describes the usage of the state parameter:
GET https://hotels.cloudbeds.com/api/v1.1/oauth?
client_id=<app client id>
&redirect_uri=<app redirect url>
&state=<anything relevant>This way, after the property staff authenticates into Cloudbeds and authorizes the integration, they'll be redirected to your endpoint with both the authorization_code and the state as described on the request:
GET <app redirect url>?
authorization_code=<authorization_code>
&state=<value sent before>If no state parameter is passed in the OAuth URL, a random state parameter will be still provided together with the authorization_code when the property is redirected to your redirect URI.
Read more on auth0.com or in our Desktop Apps guide.
PropertyID is unique account identifier in the Cloudbeds system. Right after the OAuth flow is finished you may obtain the propertyID and other info using getHotels or getHotelDetails. These endpoints show you exactly to which properties the OAuth credentials give access to.
Cloudbeds users don't know their propertyID and can't obtain it. It must be obtained through the API.
Terminology
OAuth terminology can be a little confusing, so let's provide some context for this application of OAuth.
Client - You, the client application.
Server - The application serving customer data (Cloudbeds).
Authorization Server - The server authenticating / authorizing the client's requests (Cloudbeds).
Resource Server - The server providing authorized resources to an authenticated client on behalf of the resource owner (Cloudbeds).
Resource Owner - The customer, property, or association whose Cloudbeds data you would like to access.
Third-Party Application (App) - Your application that will access Cloudbeds resources on behalf of a customer, after authorized.
Access Token - A pre-authorized token clients may use to make authenticated resource requests from the Resource Server.
Refresh Token - A pre-authorized token clients may use to refresh their access_tokens after they expire and avoid full re-authentication flow.
Authorization Code - A pre-authorized token. Clients may use to request an access token.
Redirect URI - The endpoint at your application where Cloudbeds forwards authorization codes.
Comments
0 comments
Please sign in to leave a comment.