Roomorama API » Authentication

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.

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.

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 https://www.roomorama.com/oauth/authorize?response_type=code with the parameters client_id set to your client ID and redirect_uri set to the callback URL you registered.

        https://www.roomorama.com/oauth/authorize?
        response_type=code&
        client_id=CLIENT_ID&
        redirect_uri=http://www.example.com/callback
      

2. 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 https://www.roomorama.com/oauth/token?grant_type=authorization_code 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=http://www.example.com/callback&\
        code=AUTHORIZATION_CODE" \
        https://www.roomorama.com/oauth/token

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

{
        "access_token": "ACCESS_TOKEN"
      }

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.

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 https://www.roomorama.com/oauth/authorize?response_type=token with the parameters client_id set to your client ID and redirect_uri set to the callback URL you registered.

https://www.roomorama.com/oauth/authorize?
          response_type=token&
          client_id=CLIENT_ID&
          redirect_uri=http://www.example.com/callback

2. Extract the Access Token from the URL Fragment

When the user authorizes your application, we'll redirect to the callback URL you passed as a param and you can extract the access token from the URI fragment:

http://www.example.com/callback#access_token=ACCESS_TOKEN

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!