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
- The client application requests the access token using its credentials (Client ID, Client Secret, and Scope) to the Anywhere Authorization Server token endpoint.
- Once the Identity Provider (IdP) successfully validates the application credentials, it issues the access token with the requested scope to the calling application.
- The client uses this access token (along with the API Key (apiKey) obtained from the developer portal) to call the API.
- 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 |
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. |