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 Ellie Mae oAuth2 Identity Service endpoint that generates an access token. If the credentials are valid, Ellie Mae returns an access token to the client application.

591591

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


This API request can be found under Authentication and Authorization > Partner Authentication > [Partner] Create Partner Authentication Token in the sample EPC postman collection. 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:

Parameter

Description

api_client_id

The unique identifier for the partner. Replace <api_client_id> with the API client ID portion of the API key.

api_client_secret

The secret for the partner. Replace <api_client_secret> with the API client secret portion of the API key.

grant_type

The grant type. This must be client_credentials

scope

The 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 API request can be found under Authentication and Authorization > Partner Authentication > [Partner] Introspect Partner Authentication Token in the sample EPC postman collection. Use this endpoint to check the status of an access token (and retrieve its 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:

Parameter

Description

api_client_id

The unique identifier for the partner. Replace <api_client_id> with the API client ID portion of the API key.

api_client_secret

The secret for the partner. Replace <api_client_secret> with the API client secret portion of the API key.

token

The 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:

Parameter

Description

active

An indicator of whether the access token is valid

scope

The OAuth scope

client_id

The OAuth client ID

token_type

The token type, always Bearer

exp

The seconds until the token expires (from January 1, 1970 UTC)

environment

An 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_type

The identity type of the subject, which will always be Partner for Encompass Partner Connect

encompass_client_id

A 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 API request can be found under Authentication and Authorization > Partner Authentication > [Partner] Revoke Partner Authentication Token in the sample EPC postman collection. Use this endpoint to revoke an active 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.


Did this page help you?