Anywhere OAuth

Calling Anywhere 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 Anywhere’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 Anywhere 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 Anywhere 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.

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

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

Enter the client_id provided to your client application.

Enter the client_secret provided to your client application.

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

Send the client credentials in the body.

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.

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).

It will return a JSON object as the response.

Anywhere 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 Anywhere 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.