Authorization

❗️

IMPORTANT

THE API CLIENT SECRET (part of your API Key) SHOULD NOT BE SHARED WITH ANYONE OUTSIDE YOUR ORGANIZATION, INCLUDING ICE MORGAGE TECHNOLOGY. IT SHOULD BE TREATED LIKE A PASSWORD.

YOU CAN REGENERATE THE API CLIENT SECRET USING THE API KEY MANAGEMENT PAGE. ONCE YOU REGENERATE THE SECRET, THE OLD SECRET EXPIRES IMMEDIATELY. ALL YOUR CLIENT INTEGRATIONS WILL NEED TO BE UPDATED WITH THE NEW CLIENT SECRET.

The Encompass Platform uses OAuth 2.0 for authentication and authorization. OAuth enables a client application to access information on behalf of the user without disclosing the credentials.

If you are new to OAuth, you can learn more from the OAuth 2.0 specification or the one of the many beginner’s guides available online. If you are already familiar with OAuth, continue with Supported Authorization Flows.

Supported Authorization Flows

🚧

Per the OAuth 2.0 specification, the Encompass Platform uses HTTP Basic authentication to authenticate client applications. This means the authorization header must contain the base64 encoded API key, which includes the API client ID and secret in the format: client_id:client_secret. This API key is available from your Encompass super administrator.

The Encompass Platform supports the following authorization flows:

• Authorization Code
  The authorization code flow, also known as three-legged OAuth, allows an application to obtain an access token through a two-step process: obtain an authorization code by authenticating the user (using the authorization endpoint) and then exchange the authorization code for an access token (using the token endpoint).

• Resource Owner Password Credentials (commonly used)
  The resource owner password credentials flow (i.e., username and password) allows an application to obtain an access token via a single API call, simply exchange user credentials for an access token (using the token endpoint).

📘

This grant type should only be used when the authorization code flow is not viable (e.g., console applications).

• Client Credentials
  This flow allows users to log in to your application with their credentials and supports User Token Impersonation. The client credentials flow is the preferred flow when Single Sign-On (SSO) is enabled in Encompass.

📘

Important!

Grant type client_credentials is for ISV partners only. Lenders must use grant type = password.

Support for SSO
Encompass Developer Connect supports SSO authentication with Encompass Developer Connect API integrations and SSO-enabled Encompass instances. Please note the following:

• SSO authentication with Encompass Developer Connect API integrations is meant to be used with authorization code UI login flow (grant_type = authorization_code).


• SSO authentication with Encompass Developer Connect API integrations is supported for lenders, not ISV partners.


• For information about setting up SSO for Encompass Developer Connect, see the Setting Up SSO for Encompass Connect Products guide or visit the Resource Center: ICE Mortgage Technology Identity Management Solutions page page for additional guides, webinars, and videos.

• User Impersonation
  Encompass Developer Connect supports the user impersonation flow. Once an access token is obtained, it can be exchanged by a privileged Encompass user to perform actions in Encompass under a different user account. For user impersonation, Encompass Developer Connect utilizes a grant type token exchange (urn:elli:params:oauth:grant-type:token-exchange) which provides the currently logged-in user with a new access token that includes impersonation semantics. This flow is supported for lenders with grant type resource owner password credentials. To learn how to impersonate a user and make API loan calls as the impersonated user, see User Impersonation Guide.

OAuth Endpoints

The OAuth 2.0 endpoints for the Encompass Platform are:

Authorization Code

Step 1: Authorize User

The first step is to direct the user to the authorization endpoint supplying the query parameters described below.

Example for Non-SSO:

https://idp.elliemae.com/authorize?client_id=<client_id>&response_type=code&redirect_uri=<redirecturi>&scope=lp&is_sso=false

Example for SSO:

https://idp.elliemae.com/authorize?client_id=<client_id>&response_type=code&redirect_uri=<redirecturi>&scope=lp&is_sso=true&instance_id=BE12222222

On the login page, the user will either enter their Encompass instance ID, user ID and password, or will enter their IdP username and password if SSO is configured.

Step 2: Receive Authorization Code

Once authenticated, the Encompass Platform issues an HTTP 302 to the redirect URI. As part of the redirect, the callback receives an authorization code, which is a single-use grant that expires in one minute.

Step 3: Obtain an Access Token

Next, exchange the authorization code for an access token. To do this, pass the authorization code to the token issuance endpoint, https://api.elliemae.com/oauth2/v1/token.

curl -X POST\
     -u '{{client_id}}:{{client_secret}}'\
     -d 'grant_type=authorization_code'\
     -d 'redirect_uri={{redirect_uri}}'\
     -d 'code={{authorization_code}}'\
     https://api.elliemae.com/oauth2/v1/token

{
  "access_token": "6v8wKWREGjeECskvcibQtdiO7tWn",
  "token_type": "Bearer"
}

You now have an access token. The access token is active for 30 minutes, up to a maximum of 24 hours. To avoid expiration, the access token must be used (by calling an API) at least once within 15 minutes. If you make a call after the 15 minutes but before the 30 minutes, the token will expire after 30 minutes.

Resource Owner Password Credentials

To obtain an access token, pass the user's credentials to the token issuance endpoint, https://api.elliemae.com/oauth2/v1/token.

curl -X POST\
     -u '{{client_id}}:{{client_secret}}'\
     -d 'grant_type=password'\
     -d 'username={{username}}'\
     -d 'password={{password}}'\
     https://api.elliemae.com/oauth2/v1/token

Client Credentials

To obtain an access token, pass the grant_type = client_credentials, the instance_id and scope = ‘lp’ with client_id and client_secret in the headers.

📘

Important!

Grant type client_credentials is for ISV partners only, lenders must use grant type = password. In Encompass, ISV Partners are setup as "API Users". Please see the API User (ISV Partner)" section in the guide for more information.

curl -L -X POST 'https://api.elliemae.com/oauth2/v1/token' \
--header 'Authorization: Basic dDB2OWVhaDpaMnRoNUszRjgxRGsmcTFNMW04YjlGa2gjeVJqWEJGaGFSMzZLWHVZekFqdjk4bzFKWiNUb2w4UFVuQDBDaFVy'\
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'instance_id={{instance_id}}' \
--data-urlencode 'scope=lp'

Obtain an Impersonation Token

For user impersonation, exchange the access token for an Impersonation Token. To do this, pass the token-exchange grant type, the recently generated access token (actor_access_token), and impersonated user to be impersonated as the subject user ID, in addition to the client ID and client secret to the token issuance endpoint https://api.elliemae.com/oauth2/v1/token.

📘

Supported Impersonation Scenarios

Impersonation scenarios currently supported by Encompass Developer Connect are provided below. In all cases when a user impersonates another user, the access privileges of the impersonated user are applied to the API calls.

• Super Administrator - Can impersonate all other Encompass users, including other SuperAdmin users.
• API Users - Lenders with grant type resource owner password credentials can impersonate any other users at the same level or below them in the organization hierarchy.

curl -X POST\
     -d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange'\
     -d 'actor_token_type=urn:ietf:params:oauth:token-type:access_token'\
     -d 'subject_user_id={{impersonated_user}}'\
     -d 'actor_token={{token}}'\
     -d 'scope=lp'\
     -d 'client_id={{client_id}}'\
     -d 'client_secret={{client_secret}}'\
     https://api.elliemae.com/oauth2/v1/token

{
  "access_token": "6v8wKWREGjeECskvcibQtdiO7tWn",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access-token",
  "token_type": "Bearer"
}

Token Introspection

To check the status of an access token (and retrieve the associated metadata), pass the API client ID and secret, plus the access token to the token introspection endpoint https://api.elliemae.com/oauth2/v1/token/introspection.

curl -X POST\
--location 'https://api.elliemae.com/oauth2/v1/token/introspection' \
--header 'Authorization: Basic <Base64 encoded username and password>' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=<ACCESS_TOKEN>'

If the token is valid, a JSON string is returned; otherwise, an error is raised.

Response for Authorization Code and Resource Owner Password Credentials Flows

{
  "active": true,
  "scope": "lp",
  "client_id": "nurgbm0b",
  "username": "abcmortgage@encompass:be79039931",
  "token_type": "Bearer",
  "exp": 1481704218,
  "sub": "abcmortgage@encompass:be79039931",
  "encompass_instance_id": "be79039931",
  "user_name": "abcmortgage",
  "user_key": "abcmortgage@encompass:be79039931",
  "encompass_user": "Encompass\\be79039931\\abcmortgage",
  "identity_type": "Enterprise",
  "encompass_client_id": "3569564881",
  "realm_name": "encompass:be79039931"
}

Response for User Token Impersonation Flow
The introspection endpoint returns additional information in the impersonation token response that identifies the impersonated user as well as the impersonator (actor_encompass_user).

📘

User names for both the impersonator and the impersonated user are logged in the audit trail table for loan operations.

{
  "active": true,
  "scope": "lp",
  "client_id": "nurgbm0b",
  "username": "lpusername@encompass:be79039931",
  "token_type": "Bearer",
  "exp": 1620929058,
  "sub": "lpusername@encompass:be79039931",
  "bearer_token ": "be79039931-xxxxcx", “
  "encompass_instance_id": "be79039931",
  "user_name": "lpusername ",
  "user_key": "lpusername@encompass:be79039931",
  "encompass_user": "Encompass\\be79039931\\lpusername",
  "identity_type": "Enterprise",
  "actor_encompass_user": "Encompass\\be79039931\\admin
  "encompass_client_id": "3569564881",
  "realm_name": "encompass:be79039931"
}

Token Revocation

To revoke an access token, pass the API client ID and secret plus the access token to the token revocation endpoint https://api.elliemae.com/oauth2/v1/token/revocation.

curl -X POST\
     -u '{{client_id}}:{{client_secret}}'\
     -d 'token={{access_token}}'\
     https://api.elliemae.com/oauth2/v1/token/revocation

If the token is successfully revoked, the API returns a 204 status; otherwise, an error is returned.