OAuth Apps

OAuth Apps let you create an app that can be granted permission 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
• Authorizing Users
• Revoking Access
• Handling User Revoked Access via Webhooks
• Getting Notified when Entities Change via Webhooks
• Common Issues & Questions
  • Why am I getting a 403?
  • Why can't I enable Messaging webhooks?
  • Why can't I query Listing endpoints?

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 app. 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 public URL where updates will be sent to your app from OwnerRez when the application is revoked by the user or when entities (eg. bookings, guests) are updated. 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 sends 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, send the user to the OwnerRez OAuth App authorization URL https://app.ownerrez.com/oauth/authorize with the following parameters:

For example:

https://app.ownerrez.com/oauth/authorize?response_type=code&client_id=c_foobar

2) Users are redirected back to your site

After the user approves or rejects 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 via a POST to the /oauth/access_token endpoint. 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 a temporary code for an Access Token, make a POST to the https://app.ownerrez.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:

Here's an example curl:

curl -u c_foo:s_bar -d code=tc_baz -d grant_type=authorization_code -i -X POST https://app.ownerrez.com/oauth/access_token

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://app.ownerrez.com/oauth/access_token/<token>

For example:

curl -u c_foo:s_bar -i -X DELETE https://app.ownerrez.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
}

Getting Notified when Entities Change via Webhooks

It's important for your app to know when bookings or guest records change in OwnerRez without having to make many requests, in a loop, throughout the day.  To help you know when bookings or guest records change, OwnerRez can send a POST request to your application any time a booking or guest record changes.  Read more about webhooks in the OwnerRez Webhooks support article.

Common Issues & Questions

Why am I getting a 403?

403 errors most often occur due to missing User-Agent headers, suspicious content, or a blocked IP address. If you suspect you have fallen foul of our IP block list, please contact us.

Why can't I enable Messaging webhooks?

Message webhooks require a partnership agreement between your business and OwnerRez.To gain access, please contact us with the subject line Messaging API Access.

Why can't I query Listing endpoints?

Listing endpoints requires a partnership agreement between your business and OwnerRez. To gain access, please contact us with the subject line Listing Endpoints Access.