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
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:
- Your app sends users to OwnerRez to request authorization
- Users are redirected back to your site by OwnerRez with a temporary code
- Your app exchanges the temporary code for an access token
- 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:
| 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, the scheme, hostname and path must match the Redirect URI configured in your OAuth App config. There is one exception: for localhost URI's, the port and subfolder may 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://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. 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:
| 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://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.