Trial Demo
OwnerRez
OwnerRez APIs » API for Apps
Updated 2 days ago

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

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

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

Fields Information
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://.
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://. The user/password will be sent using basic authentication.
OAuth API scope The access scope for the API token. Choose either "Full read & write" for access to all endpoints, or "Read only (GET requests only)" to limit the scope to GET endpoints. Note that if you select "Read only", you will not be able to create read & write tokens later.
Token expiration policy Choose either the recommended "Standard" (tokens expire in thirty days) or "None" (tokens never expire; note that this will be removed in the future). In the future, all tokens will be required to have expiration dates.

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
  5. Grant Access to yourself
  6. Refreshing Tokens

⚠️ OwnerRez is currently phasing out permanent tokens, and all permanent tokens will be revoked in the future. We will notify you before this occurs.

This process follows the OAuth 2 Authorization Code Grant spec: RFC 6749-Section 4.1. 

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.
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 by sending a POST request 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 as in 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://api.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://api.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.

5) Grant Access to yourself

Self-use access for your own OAuth app is allowed. If you're connecting your own OAuth app to your own account, add yourself as a User to your app to receive webhooks (especially Messaging) for your account by clicking the Users tab → Grant Access To Me button.
Add yourself as a User to your app to receive webhooks for your own account by clicking the Users tab → Grant Access To Me button.

6) Refreshing Tokens

Depending on your configuration, your tokens may expire after thirty days. To keep your token up to date, repeat your post request to https://api.ownerrez.com/oauth/access_token with the body:

grant_type=refresh_token
refresh_token=rt_...

Store and use your new access and refresh tokens.

Note that attempting to refresh tokens that are not on the "Standard" expiration policy will result in an error. All token responses include refresh_token_supported an indication of whether the token can be refreshed. If you wish to convert an existing permanent token into a refresh token (advisable, since we will eventually be phasing out permanent tokens), you can do so by submitting a POST request  oauth\token with a grant_type of token_upgrade.

You may refresh your tokens after they have expired. Expired access tokens return HTTP 401 with WWW-Authenticate: Bearer error="token_expired" on API calls, but the refresh endpoint accepts a valid refresh token regardless.

POST to /oauth/token works interchangeably with oauth/access_token.

Authorizing Devices

Authorizing devices is similar to authorizing users, in that the steps are roughly the same:

  1. Retrieve a device authorization code and device code from OwnerRez
  2. Direct the user to OwnerRez to enter the authorization code
  3. Users exchange the device code for an access token on OwnerRez's site
  4. Your app accesses the OwnerRez API on the user's device with the device's access token
  5. Optional PKCE Usage

This process follows the OAuth 2.0 Device Authorization Grant Request for Comments (RFCs) process.

1) Retrieve a device authorization code and device code from OwnerRez

To request device authorization, make a POST request to https://api.ownerrez.com/oauth/device_authorization, following the instructions in the OAuth endpoint docs. This endpoint employs the same Basic client authentication method as other similar endpoints.

You will receive a device code that starts with dc_*** and a device authorization code in the form XXXX-XXXX, where each X is an alphanumeric character. Store both codes for later use.

2) Direct the user to OwnerRez to enter the authorization code

Direct the user to https://app.ownerrez.com/oauth/device?user_code=XXXX-XXXX, which is the device authorization code you received. (Note: this URL is located on app.ownerrez.com because it shares the user's logged-in session.)

You can do this through the app on the user's device, or ask them to do it on another device.

3) Users exchange the device code for an access token on OwnerRez's site

The user will approve or deny the scope of device authorization. 

If the user approves your request, move to step 4. If not, repeat steps 1 and 2.

This flow does not redirect back to your application; instead, it prompts the user to return to their device to complete authentication.

4) Your app accesses the OwnerRez API on the user's device with the device's access token

After authorization, the user will be directed to open your app to retrieve a device authorization code and device code from OwnerRez.

In the app, poll the oauth/token endpoint to see whether the device has been authorized, with the dc_... device code you stored earlier.

grant_type=urn:ietf:params:oauth:grant-type:device_code&device_code=dc_...

You may poll this endpoint once every five seconds for up to ten minutes. After that, you must re-request authorization from step 1.

Before the user has authorized, the endpoint will return an error payload:

{
  "error": "authorization_pending",
  "error_description": "The authorization request is still pending."
}

A similar error payload will be used if other errors are encountered, or if the user declines your request.

A successful authorization will return a payload similar to:

{
  "access_token": "at_...",
  "token_type": "bearer",
  "scope": "full",
  "user_id": 123456,
  "user_display_name": "Beach House Rentals",
  "refresh_token": "rt_...",
  "expires_in": 2592000,
  "expires_at": "2026-07-12T12:00:00.0000000Z",
  "refresh_token_supported": true
}

5) Optional PKCE Usage

You may choose to use PCKE when creating tokens. Generate a random code_verifier (43–128 characters, [A-Za-z0-9-._~]), send its hash as code_challenge on authorize, and send the original verifier as code_verifier when exchanging the code.

OwnerRez supports a SHA256 (S256 in the body below) hash.

If you omit PKCE, no verifier is required. For example, if you POST:

https://app.ownerrez.com/oauth/authorize
  ?response_type=code
  &client_id=c_your_client_id
  &redirect_uri=https://yourapp.com/oauth/callback
  &scope=full
  &state=random-csrf-token
  &code_challenge=CODE_CHALLENGE
  &code_challenge_method=S256
Body should include:
code_verifier="your_code_verifier"

Revoking Access

If the user decides they no longer want to use the integration, or you wish to disable it for them or on a specific device, you can revoke access by making the following call with basic authentication, where the username is the Client Id of your OAuth App and the password is the Client Secret of your OAuth app.

This process is the same for both device and user tokens.

DELETE https://api.ownerrez.com/oauth/access_token/<token>

For example:

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

Updating the Webhook URL

Updating the Webhook URL in the OAuth App settings (Developer tab) does not automatically update existing webhook subscriptions. OwnerRez uses two webhook delivery methods.
1. Global Webhook Configuration
  • Configured in the OAuth App settings (Developer tab)
  • Sends all webhook types to a single endpoint
  • Uses the `WebhookUrl` set in the OAuth App settings
  • Applies to all connections for that app
If you want all webhooks to go to your global endpoint:
  • Delete the existing subscription via the API: `DELETE /v2/webhooksubscriptions/{subscriptionId}`
  • Or update the subscription URL via the API: `PUT /v2/webhooksubscriptions/{subscriptionId}`
2. Individual Webhook Subscriptions (via API)
  • Created via the API (`/v2/webhooksubscriptions`)
  • Overrides the global configuration when present
  • Allows per-subscription URLs and filtering by webhook type, action, and category
  • Takes precedence over the global webhook URL
If you want to keep subscriptions but use different URLs, you can manage them individually via the API. View your current for your app using:
  • `GET /v2/webhooksubscriptions` (returns subscriptions for the authenticated connection)
  • Or view them in the OwnerRez UI under Settings → API → [Your App] → Subscriptions

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 at partnerhelp@ownerrez.com.

Why can't I enable Messaging webhooks?

Self-use access for your own OAuth app is allowed, including Message webhooks. See Grant Access to Yourself.

If you are building an OAuth app that you plan to market to others, Message webhooks require a partnership agreement between your business and OwnerRez.To gain access, please contact us at partnerhelp@ownerrez.com 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 at partnerhelp@ownerrez.com with the subject line Listing Endpoints Access.