Built by owners, for owners.

Getting Started

Recommended Reading

Overview

Bookings & Quotes

Properties

Guests

Quotes

My Account

Messaging

Email Template Library

Door Locks

Property Management

Reviews

Listing Site Integration

Widgets

Hosted Websites

Technical Stuff

Privacy & Security

Insurance and Damage Protection

Data Management

QuickBooks Integration

Rates

Rules

SMS Messaging

Security Deposits

Taxes

Payments

Dynamic Pricing Integrations

OwnerRez API

Other Integrations

Channel Management

Page-Specific Help

Testing

Change Log

OwnerRez API - OAuth Apps

OAuth Apps let you create an app that can be granted access to access other users accounts. We only support the OAuth 2 Authorization Code Grant: RFC 6749-Section 4.1 (web application flow). If you only need to access your own account, or are looking for a Client Credentials Grant type flow, use a Personal Access Token instead.

Setting up a new OAuth App

First, contact us and let us know what you're building! We love hearing about new apps and scenarios using OwnerRez.

Then, go to the Developer/API Settings under the dropdown arrow in the top-right of your OwnerRez screen and create an account. Required fields:

Name
Name your app something recognizable to your users -- this will be shown during authorization.
Homepage Url
The link to your public homepage, or preferably a landing page describing how your app integrates with OwnerRez.
OAuth Redirect URL
The redirect URL where users will be sent after authorizing your application. This URL must start with https:// unless it is localhost/loopback -- useful for testing.
Webhook URL/User/Password
The Webhook information where updates will be sent to your app when the application is revoked. This URL must start with https:// unless the OAuth Redirect Url is localhost/loopback -- useful for testing. The user/password will be sent using basic authentication.

You can also set a description and logo to further identify your app.

When you create your app, you'll be given a client secret starting with s_. Record this as you won't be able to access it again. If you need to, you can always regenerate a new secret for your app.

Authorizing Users

The flow to authorize users for your app is:

  1. Your app redirects users to OwnerRez to request authorization
  2. Users are redirected back to your site by OwnerRez with a temporary code  
  3. Your app exchanges the temporary code for an access token
  4. Your app accesses the OwnerRez API with the user's access token

This process follows the OAuth 2 Authorization Code Grant spec: RFC 6749-Section 4.1. Access Tokens are long lived so there are no Refresh Tokens or process for that.

1) Request a user's authorization

To request user authorization, redirect the user to the OwnerRez OAuth App authorization URL https://secure.ownerreservations.com/oauth/authorize with the following parameters:

Name Description
response_type Required. Must be "code".
client_id Required. The Client Id of your OwnerRez app. Will start with c_
redirect_uri

The URL in your application where users are sent after authorization. Optional, but if set it must match exactly the Redirect URI configured in your OAuth App config.

There is one exception: for localhost URI's, the port and subfolder can be different.

state This parameter will be returned to your app exactly as sent here in Step 2. Used for tracking information about the request as well as random unguessable string for anti request forgery protection.

For example:

https://secure.ownerreservations.com/oauth/authorize?response_type=code&client_id=c_foobar

 

2) Users are redirected back to your site

After the user takes action on your request, OwnerRez redirects back to your site using the redirect_uri parameter you provided in step 1 or the Redirect URL from your app configuration if no redirect was provided in step 1.

If the user successfully authorized your application, we'll send back a temporary code in the code parameter as well as the state you provide in step 1 in the state parameter. The temporary code will expire after 10 minutes. If the state doesn't match the state you originally provided, then a third party altered the request and you should abort the process.

For example:

https://acmeapp.com/path/to?code=tc_12345&state=mystate

If the user declined to authorize your application or if some other error occurred, we'll send back error details in the error and error_description parameters. error is a machine readable string such as redirect_uri_mismatch or access_denied. error_description is optional and if specified will contain a human readable error message.

For example:

https://acmeapp.com/path/to?error=access_denied&error_description=The+user+denied+you+access

 

3) Exchange the temporary code for an access token

Once you have the temporary code from step 2, you can convert it into an Access Token. Temporary codes are only good for 10 minutes and must be upgraded to an Access Token before that time expires. Temporary codes can only be used once. If it's been more than 10 minutes or the code has been used, any subsequent requests will generate an error.

Access Tokens are long lived so there is no need for a Refresh Token like there is with some OAuth implementations. All you will need is the Access Token.  Access Tokens will never expire unless either you delete them or the user revokes access to the application.

To exchange an temporary code for an Access Token, make a POST to the https://secure.ownerreservations.com/oauth/access_token endpoint using basic authentication where the username is the Client Id of your OAuth App and the password is the Client Secret of your OAuth app. Send the following parameters using the "application/x-www-form-urlencoded" format:

Name Description
grant_type Required. Must be "authorization_code".
code Required. The code you received as a response to Step 1.
redirect_uri The URL in your application where users are sent after authorization, if sent in Step 1 -- must match exactly if sent.

Here's an example curl:

curl -u c_foo:s_bar -d code=tc_baz -d grant_type=authorization_code -i -X POST https://secure.ownerreservations.com/oauth/access_token -H "Content-Type:application/json"

The response will be JSON and include the resulting access_token and user_id. For example:

{
  "access_token" : "at_foobarbaz",
  "token_type" : "bearer",
  "scope" : "all",
  "user_id": 123456
}

In the case of a failure, the response will be a 400 status code and include JSON with error and (optionally) error_description attributes. For example:

{
  "error" : "invalid_grant",
  "error_description" : "It's been too long."
}

 

4) Access the OwnerRez API

Once you have a user's access token, use bearer token auth to access the API, as outlined in the Authentication guide.

Revoking Access

If the user decides they no longer want to use the integration, you can revoke access by making the following call using basic authentication where the username is the Client Id of your OAuth App and the password is the Client Secret of your OAuth app.

DELETE https://secure.ownerreservations.com/oauth/access_token/<token>

For example:

curl -u c_foo:s_bar -i -X DELETE https://secure.ownerreservations.com/oauth/access_token/at_baz

Handling User Revoked Access via Webhooks

Users can also revoke access to your app from within OwnerRez. To handle this case, you must handle the webhooks sent from OwnerRez when an account is revoked. We plan to eventually add webhooks for other cases but right now the only one is authorization revoked.

We will POST to the Webhook URL you specify in your OAuth App settings, sending the username and password you specify using basic authentication.

The webhook body will be JSON in the following format:

{ 
  "action" : "application_authorization_revoked",
  "user_id" : 347311458
}