Guides and Articles

API Keys Authentication Guide for Technology Partners

This API Keys Authentication Guide provides basic information on the API Keys Authentication required to access Cloudbeds API resources.

For the OAuth 2.0 authentication method please see the article Alternative OAuth 2.0. authentication method.

Suggest Edits

This article explains the process to configure and use partner-level API keys. If you want to get started quickly, you can generate a property-level API key to access API resources for your partner account, by following the steps in our Quickstart Guide - API Authentication for property-level users

**It is strongly recommended to implement the API Keys automatic delivery method to automate the onboarding process from Cloudbeds Marketplace.**

1. What are API keys?

API keys are long-lived, permanent tokens that, as opposed to OAuth 2.0 tokens, don’t need to be refreshed. They will not expire unless the API key is unused for a period of 30 days.

2. API key settings

Once you have access to your [Partner Dev Account](access to your Partner Dev Account) and our team has confirmed that the API Keys Authentication is enabled, you can proceed to set up your API Key Delivery method: Automatic or email delivery.

You can amend your API delivery options at any time.

Automatic delivery

Settings

If you set the API Keys to automatic delivery, Cloudbeds will deliver an authorization_code to your predefined redirect URI when your app is connected by a property. This authorization code can be then exchanged for an API key.

The below details will be required to set up the API Key Automatic Delivery Method:

  1. client_id - Client ID issued by Cloudbeds.
  2. client_secret - You can click on 'Generate New Secret' to retrieve your client secret for the first time or to reset it.
  3. API Key Delivery > Automatic
  4. redirect_uri - It is the predefined URL where the authorization_code is forwarded to.
  5. 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 APIdocumentation.

App authorization and redirection

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 a consent screen to confirm your permission scopes, and, upon successful authorization, they are redirected to your predefined redirect_uri with the authorization_code.

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

Exchange your authorization_code for an API key

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: urn:ietf:params:oauth:grant-type:api-key) call to exchange the authorization_code for an API key. The API key will be returned to you in the access token field, the API key will always start with “cbat_”.

curl \--location '<https://hotels.cloudbeds.com/api/v1.1/access\_token'> \  
--form 'grant\_type="urn:ietf:params:oauth:grant-type:api-key"' \  
--form 'client\_id="myOwnApp\_fjiPSJNll89"' \  
--form 'client\_secret="myclientsecret"' \  
--form 'redirect\_uri="<https://webhook.site/dd227653-0b40-4"'> \  
--form 'code="mQB4BivWyIb-z2tqRj9JgXEwFGGvrSSp7NhZbW4r2IQ"'

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.

Access the property resources

The API key returned by /access_token may be used to access Cloudbeds API by including it in the authorization header of your requests (Authorization: Bearer cbat\_9T01SlwIQGq8HC56LYL8kXcBBp). Each key gives access to either the single property that requested it, or to all properties of an organization that requested it.

curl \--location '<https://hotels.cloudbeds.com/api/v1.1/getHotels'>  
\--header 'Authorization: Bearer cbat\_HgRtFd02sdU587LyW59zrtm3JV5Xc' \

E-mail delivery

Settings

If you set the API Keys to email delivery, Cloudbeds will send an email notifying you that a new property has connected to your app. Then, you should log in to your Partner account and find the property in the API Keys list.

The below details will be required to set up the API Key Automatic Delivery Method:

  1. API Key Delivery > Via Email
  2. Email addresses: Email address for new property-connected notifications
  3. 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 API documentation.
  4. API Keys: List of properties that have connected your app where you can reset the API Keys.


The Client ID and Client Secret are not required for API Key email delivery and you may ignore these parameters.

App authorization

The property user can find your App in Cloudbeds Marketplace. When clicking on the Connect App option and confirming the permission scopes, a pop-up will show to the property user notifying them that you will potentially follow up shortly with any additional onboarding instructions. You will also receive an email confirmation that a new property has connected your app.

Retrieve/reset an API key

Once you receive an email notification that a new property has connected to your app, you simply need to log in to your Partner Account, access the App Details page, and find the property in the API Keys List.

Then, you will need to click regenerate the API key for this property and the API key will be displayed in a pop-up window. You will need to store the API key safely on your side.

If you fail to save it or need to reset it, you will need to reset the API key, which will generate a new API key and invalidate the previous one.


Access the property resources

The API key retrieved from the API Keys List may be used to access Cloudbeds API by including it in the authorization header of your requests (Authorization: Bearer cbat\_9T01SlwIQGq8HC56LYL8kXcBBp. Each key gives access to either the single property that requested it, or to all properties of an organization that requested it.

curl \--location '<https://hotels.cloudbeds.com/api/v1.1/getHotels'>  
\--header 'Authorization: Bearer cbat\_HgRtFd02sdU587LyW59zrtm3JV5Xc' \

3. FAQ

Do API Keys expire?

They won’t expire, as long as they are used at least once every 30 days.

Can I reset an API key?

  • Automatic delivery: The property would need to re-authorize the integration (disconnect/reconnect your app) for you to be able to request a new API key.
  • Email delivery: You can access the API Keys Lists in your App Details Page to reset the API Key for a specific property.
    In both cases, the previous API key will be invalidated once a new one is generated.

How can I connect my partner account using a partner-level API key?

You can test the Marketplace connection flow using API keys (automatic or email delivery) creating an app connection link with the below parameters:

https://hotels.cloudbeds.com/connect/**propertyID**\#/app/**clientID**

The client_id can be retrieved from your App Details page and you can get your propertyID from the URL line when connected to Cloudbeds.


**Cloudbeds does make reasonable efforts to ensure that API keys are not exposed in any public-facing repositories (Github, Gitlab, etc). Should an API key be compromised by public exposure we reserve the right to disable that key and require that you create a replacement Key and update any code to obscure the new key from exposure by unauthorized parties.**

Updated about 1 month ago

What’s Next