Integrations with desktop apps and desktop apps that work with external hardware (e.g. door locks, scanners) are possible but may be tricky to build considering our OAuth 2.0 flow requirements.
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 URI) 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. You can also specify a port in your "localhost" redirect URI.
Note: The Cloudbeds user that approves the connection, needs to do it only once. As soon as they approve, we will send OAuth code to your redirect URI and with this code refresh/access token pair can be obtained and refreshed once per hour without further involvement by the Cloudbeds user.
How to pass dynamic parameters in the OAuth URL?
Sometimes it can be necessary to preserve the app state or to have some information about the user persisted through the OAuth authorization flow. Different software architectures may deal differently with each OAuth step and some may have issues on one part of the other. For that reason, 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, he'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>
Example use case
POS integrations can benefit from this. If your POS software does not support parsing HTTP(S) requests to receive the authorization code and land the user back from OAuth flow, it is possible to have a public web server act as token repository as well as landing page for the user. The issue here would be to identify the POS station/device that initiated the authorization flow and associate it with the authorization code received, but that can easily be covered by the state parameter (see above).
FAQ
Webhooks need to be anything that the "internet" can access on your servers (or desktop app). So let's say the enduser has a fixed IP address, That IP address can be accessed via the internet (has a port open). You could use that IP (e.g. http://179.121.79.1:8120/hook/).
Or even if the IP is dynamic, every time it changes, your desktop app would see it changed, and request the unsubscription of your previous subscription and subscribe again, using the new IP (e.g. http://181.211.79.1:8120/hook/).
We do not suggest the use of any specific solution, but another option is a localhost tunneling. Something like localtunnel or ngrok. The only issue you guys have to be totally sure is that whatever solution you use returns an HTTP code 200 to our servers. If this does not occur, our servers will continuously send the same request back to you and it will only proceed with the rest of the queue, once this request receives a 200.
Comments
0 comments
Please sign in to leave a comment.