Realogy OAuth

Realogy OAuth

Calling Realogy REST APIs Using OAuth 2.0 Client Credentials

Overview

The OAuth 2.0 (Open Authorization framework) is a standard that lets a website or application access resources hosted by other web apps on behalf of a user. If the access token request is valid and authorized, the authorization server issues an access token and optional refresh token. If the request failed the client authentication or is invalid, the authorization server returns an error response.

The OAuth 2.0 client credentials grant is used to request tokens from Realogy’s default authorization server in order to access the protected Apigee REST APIs. This method must be used when an application needs to request a token to access its own resources in an application context. API keys identify the calling application and make the call to an API. Authentication tokens identify a user that is using the application.

How requesting a token works

  1. The client application requests the access token using its credentials (Client ID, Client Secret, and Scope) to the Realogy Authorization Server token endpoint.
  2. Once the Identity Provider (IdP) successfully validates the application credentials, it issues the access token with the requested scope to the calling application.
  3. The client uses this access token (along with the API Key (apiKey) obtained from the developer portal) to call the API.
  4. After the required validation, the API returns the result to the calling application.

Client Registration

You must register the client application with xxxx . After the registration process is completed, you will be provided the client credentials (Client ID, Client Secret, Scope, and REST API URLs) for your client application. Each client application must have separate credentials set and the API Key.

After client registration, these values will be provided to you for calling the APIs as described in the table below.

Attribute Provision
Client ID The unique identifier of your client application that will be used to get the access token. 
Client Secret  The key that you pass with Client ID to the token endpoint to get the access token.
List of App ID URIs for  REST APIs (for the Scope parameter) 

Provided for the client application based on the application access to  REST APIs. Scope is a space-separated list of App ID URIs for Realogy APIs. Scopes enable your application to access specific  REST APIs.  The App ID URI is a unique identifier for the REST API. It is not where the REST API is hosted

Example: App ID URI for Dash API

https://btt.realogyfg.com/dashapi

REST API URL(s)  REST API URL(s) will be communicated separately for each environment (Non-Prod and Production). This is where the  REST API(s) are hosted.
API Key Every call to the  APIs requires an API Key. This key must be passed in the request header as apiKey.

Additional instructions

  • All access tokens have an expiration and must be cached by the application within 5 minutes of expiration. Applications who fail to cache their access tokens and request new access tokens for every REST API call they make will have their access immediately suspended.
  • Always store the client secret key securely. If you suspect that the secret key has been compromised, then you can request for another client secret. This should never be stored in a Mobile App or Native App.

Consume an API using Postman client

You can consume a protected API using Postman client as shown in the steps below.

Step 1 - Request and receive access token

You must set the Authorization Type to OAuth 2.0 and get the new access token using the client_credentials grant type.

Step 2 - Access token URL

Provide the token_endpoint depending on your environment (prod vs non-prod URLS are given above)

Step 3 - Client ID

Enter the client_id provided to your client application.

Step 4 - Client Secret

Enter the client_secret provided to your client application.

Step 5 - Scope

Enter the specific App ID URI assigned to the Realogy API that you want to call. e.g. https://btt.realogyfg.com/dashapi (Dash API)

Step 6- Client Authentication

Send the client credentials in the body.

Step 7- Receive Access Token (Successful Response)

If the request for access token is valid (i.e., the Client Credentials and Scope values are good) then then the Authorization server will generate the access_token along with additional properties (e.g., token_type, expires_in and scope)

Below is an explanation of the values returned in a successful response:

  • access_token: The access token string as issued by the authorization server.
  • token_type: The type of token this is, typically just the string “bearer”
  • expires_in: (seconds): The duration of time the access token is granted for.
  • scope: The App ID URI assigned to an API. It should be identical to the scope that the client application requested.
Step 8 - Set Headers

Below are the header values:

  • Set access_token: (received in step-1) and apikey (assigned to your client application) as headers (key, value pairs).
  • apiKey: {Api Key assigned to your application}
  • Authorization: Bearer {access_token received in previous step}

Note: You can manually set access_token in the Authorization header, or you can select Authorization Type as OAuth 2.0 (and select the access_token acquired in the previous step).

Step 9 - Call protected Realogy API
Call the Realogy API with the required parameters.Example: Dash API
https://api.realogy.com/1.0/dash/batches/{batchId}

It will return a JSON object as the response.

Realogy Authorization Server Information

Non-Prod IdP Metadata Document:

Prod IdP Metadata Document:

Non-Prod Access Token URL

Prod Access Token URL (token_endpoint):

Grant Type:client_credentials

Scope: Will be communicated in the final approval email

Example: https://api.realogy.com/iprospectapi

References

The references for this guide are shown in the table below.

Title Link
The OAuth 2.0 Authorization Framework OAuth 2.0
JSON Web Token (JWT) JSON Web Token
Implementing the Client Credentials Flow https://developer.okta.com/authentication-guide/implementing-authentication/client-creds
Decode JSON Web Tokens https://jwt.io/
Postman – API Testing Tool https://www.getpostman.com/

Terms and Abbreviations

The terms and abbreviations used in this guide are shown in the table below.

Term/Abbreviation Definition
JSON JavaScript Object Notation
JWT JSON Web Token
REST Representational State Transfer
Client Credentials Flow The Client Credentials flow is recommended for use in machine-to-machine authentication. Your application will need to securely store it’s Client ID and Secret and pass those to Realogy Okta in exchange for an access token.
Access Token (access_token) Access tokens are credentials used to access protected resources.  An access token is a string representing an authorization issued to the client. Access tokens are used as bearer tokens. A bearer token means that the bearer can access authorized resources without further identification.
Note: For Authorization Server, it will be a JSON Web Token (JWT)
Claim Piece of information asserted about an Entity. Simply put, claims are Name/value pairs that contain information about a user.
Issuer Entity that issues a set of Claims
Scope Scopes are space-separated lists of identifiers used to specify what access privileges are being requested
"iss" (Issuer) Claim The issuer of the token (JWT), an entity we trust.
"sub" (Subject) Claim The subject claim identifies the principal that is the subject of the JWT.
"aud" (audience) Claim The audience claim identifies the recipients that the JWT is intended for.
"exp" (expiration time) claim The expiration time claim identifies the expiration time on or after which the JWT MUST NOT be accepted for processing.