OAuth 2.0 Overview

Getting Started

Authentication begins by requesting integration partner access by emailing us at rentalfeeds@zillow.com.  Upon successful onboarding as a new integration partner, Zillow Group will grant you an API key, a Client ID and Client Secret.  You will then be able to use this Client ID and Client Secret in the OAuth handshake between Zillow Group and your integration.

 

There are four main steps in leveraging OAuth to connect your user’s account and get an Authorization token that you can use.  Each of the steps is detailed below.

 

Step 1:  Create Authentication URL

The first step is to create the authorization URL that you will use to send the user to Zillow Group’s authentication server. The query parameters that you can pass as part of an authorization URL are shown below.

 

https://authv2.zillow.com/oauth/authorize

Parameter Required?

Description

Example
client_id Yes The Client ID, which we send you at time of onboarding. 7fff1e36-2d40-4ae1-bbb1-5266d59564fb
response_type Yes The grant type that is required. Use ‘code’ unless advised otherwise. code
redirect_uri Yes The URL that the user will be redirected to after they authorize your app for the requested scopes. For production applications, https is required https://www.example.com/auth-callback

 

To start the OAuth 2.0 process, send the user to the authorization URL.  Here’s an example URL:

https://authv2.zillow.com/oauth/authorize?client_id=7fff1e36-2d40-4ae1-bbb1-5266d59564fb&response_type=code&redirect_uri=https://www.example.com/auth-callback

 

Step 2:  Zillow Group Gets Consent from Mutual User

The user will be sent to Zillow Rental Manager and asked to login to their account.  They will be prompted to grant access to your company. Please note, the user that is granting access must have access to “Integrations” in Zillow Rental Manager.

 

User being prompted to login to their Zillow Rental Manager account:

 

Your application will not be doing anything at this point as the user will be interacting with our site.  Once access is granted, we will send a request to the callback URI defined in the authorization URL.

 

Step 3: Receive User Redirect and Manage Response

Once step 2 is completed, we will send a GET request to the redirect URI specified in your authentication URL.  If the access requested is granted by the user, the redirect URI will have a code parameter attached when it’s returned.

 

Step 4: Exchange Authorization Code for Tokens

Once you have received an authorization code back from us, you will need to exchange it for an access and refresh token.  You can do this by sending a URL-form encoded POST request to https://authv2.zillow.com/oauth/token with the parameters shown below:

 

POST  https://authv2.zillow.com/oauth/token

Parameter Description Example
grant_type Must be authorization_code authorization_code
redirect_uri The redirect URI that was used when the user authorized your application https://www.example.com/auth-callback
code The authorization code received from Zillow Group 5771f587-2fe7-40e8-8784-042fb4bc2c31

 

You also need to send your client ID and client secret in a Basic authentication header. If the client ID is “client-id” and the client secret is “client-secret”, then you need to send “client-id:client-secret” encoded in base 64: “Y2xpZW50LWlkOmNsaWVudC1zZWNyZXQ=”

 

curl ‘https://authv2.zillow.com/oauth/token?grant_type=authorization_code&code=58e0c6f3df205d1ab4fbca8f447ba97c&redirect_uri=https%3A%2F%2Fwww.example.com%2Fauth-callback’ -X POST -H ‘Authorization: Basic Y2xpZW50LWlkOmNsaWVudC1zZWNyZXQ=’

 

The body of the token response will be JSON data with the form:

{

“access_token”:”8f3bb902954dcef7e52ddb793d181fc7″,

“Token_type”:”bearer”,

“refresh_token”:”5b292f513d03764051cc4f426d8f7e6d”,

“id_token”:”eyJhbGciOiJSUzI1NiJ9.eyJpYXQiO…jE1NTE3MjczNjMsI”

}

 

Once you have received back the access token, you can make API calls to our API on behalf of the user.  Please note you will only be able to make those calls for which you have been authorized.

 

Making API Calls Using your Access Token

Use your access token as a query parameter for any API calls you make on behalf of the mutual user.  Here’s an example of how it would work:

 

https://rentalsapi.zillowgroup.com/listings/v1/listingsForUser?accessToken=8f3bb902954dcef7e52ddb793d181fc7&clientId=7fff1e36-2d40-4ae1-bbb1-5266d59564fb&apiKey=demo

 

Refreshing Your Access Token

Your access token will expire after a given period of time.  This helps enhance security as it limits access in case unauthorized individuals are able to get access to these tokens.

 

If your access token has expired, you will need to obtain a new access token by sending a URL-form encoded POST request to https://authv2.zillow.com/oauth/token.  Parameters for this request are defined below:

 

POST  https://authv2.zillow.com/oauth/token

Parameter Description Example
grant_type Must be refresh_token refresh_token
redirect_uri The redirect URI that was used when the user authorized your application https://www.example.com/auth-callback
refresh_token The refresh token received when the user authorized your app 5b292f513d03764051cc4f426d8f7e6d

 

You also need to send your client ID and client secret in a Basic authentication header. If the client ID is “client-id” and the client secret is “client-secret”, then you need to send “client-id:client-secret” encoded in base 64: “Y2xpZW50LWlkOmNsaWVudC1zZWNyZXQ=”

 

curl ‘https://authv2.zillow.com/oauth/token?grant_type=refresh_token&refresh_token=5b292f513d03764051cc4f426d8f7e6d&redirect_uri=https%3A%2F%2Fwww.example.com%2Fauth-callback’ -X POST -H ‘Authorization: Basic Y2xpZW50LWlkOmNsaWVudC1zZWNyZXQ=’