Alternative OAuth 2.0. authentication method

This article provides basic information on the OAuth 2.0. Authentication required to access Cloudbeds API resources.

API keys are the preferred authentication method. Additional information can be found API Keys Authentication Guide for Technology Partners& Quickstart Guide - API Authentication for property-level users

OAuth 2.0. for technology partners

1. API credentials

Once you have your partner account, you can retrieve your API credentials and manage the settings on your App Details Page.

The below details will be required as part of the OAuth 2.0. authentication:

client_id - Client ID issued by Cloudbeds.
client_secret - You can click on 'Generate New Secret' to retrieve your client secret for the first time or to reset it.
redirect_uri - It is the predefined URL where the OAUth 2.0. authorization_code is forwarded to.
Permission scopes - Select the permission scopes required for the API endpoints you intend to use. You can find details on the scopes related to each endpoint in the About PMS API

2. OAuth link and authorization

Based on the User Authorization Flow Options implemented, the property user can find your App in Cloudbeds Marketplace.
When clicking on the Connect App option, the user is directed to your OAuth link (defined in the App Details page) to confirm your permission scopes, and upon successful authorization, they are redirected to your predefined redirect_uri with the authorization_code.

If your redirection URI is <https://www.myredirecturi.com/oauth\_code>, the redirection would be: <https://www.myredirecturi.com/oauth\_code?code=ob7ajLINOP1VNnMfAxCu1aX4jBvyz6vg\&state=12ddc1756afbc3552728d5bb44c78>

3. Exchange your authorization_code for an access_token.

Once the user authorizes the integration with your App and is redirected to your redirect URI with the authorization_code, you need to send an access_token (grant_type: authorization_code) call to exchange the authorization_code for an access_token and refresh_token.

The authorization_code is valid for 10 minutes and can only be used once.

If you get the "The authorization code is invalid or has expired." error in the access_token call response, the user will need to complete the authorization again.

4. Access the property resources

The access_token returned by access_token may be used to access Cloudbeds API by including it in the authorization header of your requests (Authorization: Bearer vjsZOLa2tMazV09T01SlwIQGq8HC56LYL8kXcBBp).

5. Refresh your access_token

The access_token is valid for 60 minutes and the refresh_token is permanent and does not expire.
You can send an access_token (grant_type: refresh_token) call to refresh the access_token.

In the response, a new access_token and the permanent refresh_token will be returned.

Important Note:

`Refresh tokens generated following a successful Authorization Code flow are valid for 30 days, but the expiration extends at each successful use of a corresponding Access Token. If an API Client is inactive for 30 days, the refresh token will expire and the entire oAuth 2.0 process must be re-initiated by a user re-authorization. We strongly recommend making a single API call to any endpoint every 28 days to avoid Refresh token expiration.

For certification, it is mandatory to implement [flow A user authorization](https://integrations.cloudbeds.com/hc/en-us/articles/360006543573-User-Authorization-Flow-Options) and to fully automate the OAuth 2.0. process.`

OAuth 2.0. for property-level users

We strongly recommend property-level API users authenticate using API keys, according to our Quickstart Guide - API Authentication for property-level users.

OAuth 2.0. is still available as an alternative authentication method.

You can follow the steps in this guide to access our API resources with OAuth 2.0. authentication method.

FAQ

Do refresh tokens expire?

Refresh tokens generated following a successful Authorization Code flow are valid for 30 days, but the expiration extends at each successful use of a corresponding Access Token.
If an API Client is inactive for 30 days, the refresh token will expire and the entire oAuth 2.0 process must be re-initiated by a user re-authorization.
We strongly recommend making a single API call to any endpoint every 28 days to avoid Refresh token expiration.

Can webhooks be used as a trigger to refresh the token?

We strongly recommend not using webhooks as a trigger to refresh the token pair as they can come in simultaneously and cause invalidation of tokens.

How to proceed if the Refresh Token expires or it gets invalidated/revoked?

If the Refresh Token expires with a token has expired error, then the property should re-authorize the app.

Why is redirect URI (https) required?

Redirect URI is needed for the OAuth 2.0 flow. We will be providing authorization codes to your preconfigured URI after the user authorizes the connection.

Do you allow sub domains on the OAuth redirect URI?

Yes, we do accept sub domains as the OAuth redirect URL. Not a problem at all.

Are there any limitations with the redirect_uri parameter? Yes there are some limitations:

We do not accept redirect_uri with wildcards, for example, you can not register https://.mydomain.com so that you could send any subdomain in parameter. SSL certificate (https://) is necessary and non-negotiable.
Currently we cannot accept dynamic parameter in redirect URI

How does OAuth work for desktop apps?

OAuth can be used to authenticate your desktop client into Cloudbeds API. OAuth authentication flow requires you to use an endpoint on your side (named redirect url) to which we'll redirect the user with an authorization code that can be used to retrieve access and refresh tokens that work as authentication credentials on all the other requests you may submit to Cloudbeds API. "localhost" can be used as such endpoint, but your desktop app should be able to render a HTML page in which your users will log into Cloudbeds account, and it also should be able to receive and parse HTTP (in dev stages) and HTTPS (beta and live stages) requests.

How to pass dynamic parameters in the OAuth URL?

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.

How to see the propertyID?

PropertyID is a 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.
Cloudbeds users don't know their propertyID and can't obtain it. It must be obtained through the API.

How to set up an environment & test OAuth 2.0. in Postman

For testing purposes, we recommend using Postman. This video explains how to set up a Cloudbeds environment and test OAuth 2.0.

Please ensure that you create an additional set of corresponding testing credentials on your myfrontdesk account under API Credentials which should include as redirect URI the one provided in the video steps https://www.getpostman.com/oauth2/callback