Authentication & Authorization

πŸ“˜

OAuth 2.0

The Encompass Partner Connect Platform (EPC) uses OAuth 2.0 for authentication and authorization. OAuth enables a client application to gain delegated access to information without disclosing the user's credentials. More information on OAuth can be found in the OAuth 2.0 specification or one of the many beginner’s guides available online.

Partner products are 3rd-party applications that access resources (loans, borrowers' data, company and user settings) owned by Encompass lenders. EPC uses the Client Credentials grant type to give Partner products secure access to lender-owned resources.


Client Credentials Grant Type


With the Client Credentials grant type, a client application sends its own credentials (its Client ID and Client Secret) to an ICE Mortgage Technology oAuth2 Identity Service endpoint that generates an access token. If the credentials are valid, ICE Mortgage Technology returns an access token to the client application.


OAuth 2.0 REST API Endpoints


The OAuth 2.0 endpoints for Encompass Partner Connect are described in this section.

🚧

All request attributes described below are required unless specified otherwise.


Token Issuance


Use this endpoint to obtain an OAuth token:

curl -X POST\
     -u '<api_client_id>:<api_client_secret>'\
     -d 'grant_type=client_credentials'\
     -d 'scope=<pc pcapi>'\
     https://api.elliemae.com/oauth2/v1/token

This endpoint accepts the following parameters:

ParameterDescription
api_client_idThe unique identifier for the partner. Replace <api_client_id> with the API client ID portion of the API key.
api_client_secretThe secret for the partner. Replace <api_client_secret> with the API client secret portion of the API key.
grant_typeThe grant type. This must be client_credentials
scopeThe scope of the request. This must be pc pcapi

The response looks like:

{
    "access_token": "5zs6RdBtEHRFFbhziXMxmsZKtWtn",
    "token_type": "Bearer",
    "expires_in": 7200
}

201 - an access token is created.

🚧

The access token is active for 15 minutes, up to a maximum of 120 minutes (2 hours). To avoid expiration, the access token must be used (by calling an API) at least once every 15 minutes.


Token Introspection


This endpoint checks the status of an access token (and retrieves the associated metadata).

curl -X POST\
     -u '<api_client_id>:<api_client_secret>'\
     -d 'token=<access_token>'\
     https://api.elliemae.com/oauth2/v1/token/introspection

This endpoint accepts the following parameters:

ParameterDescription
api_client_idThe unique identifier for the partner. Replace <api_client_id> with the API client ID portion of the API key.
api_client_secretThe secret for the partner. Replace <api_client_secret> with the API client secret portion of the API key.
tokenThe access token. If the token is valid, a JSON string is returned; otherwise, an error is raised.

The response looks like:

{
    "active": true,
    "scope": "pc pcapi",
    "client_id": "7tep2yp6",
    "token_type": "Bearer",
    "exp": 1575928099,
    "environment": "Test",
    "identity_type": "Partner",
    "encompass_client_id": "007001"
}

The following table describes each attribute in the response:

ParameterDescription
activeAn indicator of whether the access token is valid
scopeThe OAuth scope
client_idThe OAuth client ID
token_typeThe token type, always Bearer
expThe seconds until the token expires (from January 1, 1970 UTC)
environmentAn indicator of whether the subject is operating in a test/sandbox vs. production environment, which may govern parameters such as rate-limiting and billing
identity_typeThe identity type of the subject, which will always be Partner for Encompass Partner Connect
encompass_client_idA unique identifier for the subject in the Encompass Partner Connect system. Also referred to as the Partner ID in other areas of our API interface, such as the /products API

Token Revocation


This endpoint revokes an access token.

curl -X POST\
     -u '<api_client_id>:<api_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.


What’s Next