Defining Credential Requirements

For an application to use EPC's user/company credential management feature, EPC needs to understand the requirements for the application's credentials set. This information helps drive the various touchpoints of this feature across Lender-facing application interfaces.

The credential requirements can be specified when creating/updating a product resource via the
POST https://api.elliemae.com/partner/v2/products/PATCH https://api.elliemae.com/partner/v2/products/:id REST API endpoint.

The credential requirement set can contain any number of fields. Each field needs to be defined within the credential request body attribute of when creating/updating your product configuration as follows:

{
  ...
  "credentials": [
    {
      "id": "field-1",
      "type": "string || number || boolean",
      "title": "field title",
      "secret": true || false,
      "required": true || false,
      "scope": "company || user"
    },
    {
      "id": "field-2",
      "type": "string || number || boolean",
      "title": "field title",
      "secret": true || false,
      "required": true || false,
      "scope": "company || user"
    },
    ...
    {
      "id": "field-n",
      "type": "string || number || boolean",
      "title": "field title",
      "secret": true || false,
      "required": true || false,
      "scope": "company || user"
    }
  ]
}

The requirement definition format for a credentials set loosely follows the json-schema specification definition language for JSON objects, with the addition of custom attributes that hold meaning to the EPC platform (such as secret and scope).

Attribute	Description
`id`	This is the unique key for the credential property. When originating/fulfilling a transaction, you will receive the credential properties indexed against their `id` key in a JSON object, called `credentials`, in the origin/request body.
`type`	Data type of the field. Must be one of `string`, `number`, or `boolean`.
`title`	Title for the field. This is used across Lender-facing application interfaces to display the field in forms.
`required`	Specifies whether the credential property is required by the integration. This will be enforced in the credential input forms for Lender users and administrators.
`secret`	Custom descriptor that defines if the field is a secret field, which influences user-interaction in Lender-facing application interfaces (such as masking).
`scope`	Custom descriptor that defines the scope of the credential set, whether they belong to a Lending organization or to individual users of an organization. This information governs entitlements around the credential field within a Lender's system. Must be either `company` or `user`.

📘
Order Matters!
The properties in the credential schema definition are used to render the input forms where Lender administrators/users can create and edit their credential sets. The input fields for each credential property will appear in the order they are listed in the credential schema definition.

For this example, assume an application in development needs three fields to authenticate a Lending organization and its users:

A Company ID that identifies a Lending organization and provides a unique name-space for its user's credentials
A Username, which is a standard user-level non-secret credential
A Password, which is a standard user-level secret credential

To add this credential's schema definition to an EPC product, use the PATCH operation on the https://api.elliemae.com/partner/v2/products/:id endpoint:

{
  ...
  "credentials": [
    {
      "id": "companyId",
      "type": "string",
      "title": "Company ID",
      "secret": false,
      "required": true,
      "scope": "company"
    },
    {
      "id": "username",
      "type": "string",
      "title": "Username",
      "secret": false,
      "required": true,
      "scope": "user"
    },
    {
      "id": "password",
      "type": "string",
      "title": "Password",
      "secret": true,
      "required": true,
      "scope": "user"
    }
  ]
}

This operation is titled Update a Product and is in the Product Registration and Management folder in the EPC Postman collection:

The {{product_id}} has to be replaced with the actual product_id (returned when the product was created) before the request is sent. If the update is successful, a response like the following will appear:

{
  "id": "562a9740-2e27-44fd-8ff6-8731de6aa0fc"
}

📘Order Matters!

📘
Order Matters!