The Roomorama API is being deprecated in favour of our new API powered by our new business

Please email us at for more information.

3. Authentication

Authentication to the API is only required for the protected parts of the API, denoted in the documentation by the OAuth icon.

Authentication to the API is done through OAuth 2.0 (draft 18). OAuth 2.0 is a simple and secure authentication mechanism. It allow applications to acquire an access token for the Roomorama API via various authentication flows depending on the type of application you are integrating with Roomorama.

To get started using OAuth, you'll first have to register your application.

3.1. Overview

The Roomorama API comprises of both protected and public API methods. The protected API methods relate to a particular user account and require authentication via OAuth 2.0. These method calls are prefixed by the OAuth icon in the documentation so you can easily recognize them. We currently support OAuth2 (draft 18) with Bearer Tokens (draft 6) or MAC authentication (draft 00).

We strongly recommend that you use one of the many OAuth2 client libraries available instead of trying to build the requirest by yourself. There are OAuth2 libraries available for many languages, some of which you can find on the OAuth wiki.

OAuth2 authentication works by obtaining an access token for a certain user account and passing this token in the header or parameters of your request. Obtaining this access token can be done through a number of different flows. Roomorama currently supports the Web Server and User-Agent flows for obtaining an access token.

Roomorama access-tokens are currently long-lived and will not expire unless the user revokes access to the application.

To get started using OAuth, you'll first have to register your application. The callback URL that you enter is where we'll redirect users after they authorize your application. After registering your application you will get your client ID which will be used to generate the request.

3.2. Web Server Flow

In the web server flow, your application will first ask the user to authorize access by redirecting him to the authorize URL. On successful authorization the user will be redirected to the Callback URL specified in your application, passing in an authorization pre. Your application will then use this authorization pre with your client ID and client secret to obtain an access token for the user account.

3.2.1. Get the User's access token

If the user authorizes your application, he will be redirected to the callback URL you passed in the redirect_uri parameter with a new code parameter appended.

You will POST this code to passing in your client_id the same redirect_uri and your client secret as client_secret in order to obtain an access token.

curl -d "grant_type=authorization_code&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri="

If successful, we'll return a response that has a JSON body containing your access token:

  "access_token": "ACCESS_TOKEN"

3.3. User-Agent flow

The User-Agent flow is is typically executed within a browser using JavaScript. You'll receive the access token as part of the user authorizing your application (as opposed to making a separate request as you would in the Web Server flow). You won't use your client secret as part of this flow since it would be accessible to the user.

3.3.1. Get the User to Authorize your Application

To get an access token for a user, you will have to ask him to authorize your application by redirecting them to the authorize URL on Roomorama. You will need the client ID and the callback URL that you registered your application with. From your application, redirect the user to with the parameters client_id set to your client ID and redirect_uri set to the callback URL you registered.

3.3.2. Generate Access Token

Generating access token 741cd65b80cc86736d9807da6e3dd2a24cb43272393c9ff56c56614935fc23e7 Access token 94a092beff3454c9f5e4d39a03796a9de87502c986663ca5c33ae514daca7bfc

3.4. Obtaining an access token for testing

To quickly obtain an access token for testing out API functionality for your account, perform the following steps:

  • Login to Roomorama with your user account that has been activated for API access
  • Head to your Account section then click on API
  • Click the 'Register your application for API access' link
  • Enter your application name, application website, and callback URL (for testing purposes your callback URL can be http://localhost)
  • Copy-paste the URL indicated next to the Web Server flow authorization URL into a new browser tab and when prompted authorize the account access
  • You will be redirected to your callback url (http://localhost) with the access token appended as the pre query string parameter
  • Use this access token in all your requests to the API!
Your browser is out dated

For the best experience, update your browser to view this website correctly. Update my browser now