# Supplemental Information 

* [Description](#description)
* [URL Invocation Points](#url-invocation-points)
* [Authentication](#authentication)
* [Request Headers](#request-headers)
* [Sample Code for SSO using DataConnect SSO](#sample-code-for-sso-using-dataconnect)
* [Sample Code for JWT SSO using Morningstar Authentication](#sample-code-for-jwt-sso-using-morningstar-authentication)
* [Supplemental Response Model Information for GET /credentials/accounts](#supplemental-response-model-information-for-get-credentialsaccounts)
* [Account and Credential Error Information](#account-and-credential-error-information)
* [Activity in Progress Information](#activity-in-progress-information)
* [Authentication Aggregation Status Messages](#authentication-aggregation-status-messages)
* [Account Types](#account-types)
* [Related Information](#related-information)

### Description 
This REST API implements account setup functionality. This page describes endpoints that can be used with the Morningstar Connect component which is available for use with the Morningstar ByAllAccounts (BAA) aggregation service.

Use the API to:

*  Register a new user

*  Get profile data for a user

*  Get credentials and account information

*  Get a collection of all positions

*  Request aggregation of accounts for an authenticated investor user

*  Monitor the status of asynchronous authentication or aggregation activities

*  Delete an account

*  Delete a credential and all associated accounts from the system


### URL Invocation Points

The BAA REST API is accessed by a URL invocation point.

*  BAA server https://www.byallaccounts.net/api/v1

*  With Morningstar Authentication https://www.us-api.morningstar.com/aggapi/v1

### Authentication 
 Authentication can be accomplished via SSO using DataConnect or via Morningstar Authentication which is UIM JWT SSO authentication. Use one method of authentication. Regardless of the method used, only an Investor user can authenticate to the REST API. Advisor and Assistant users cannot authenticate to the REST API.

Single Sign On (SSO) using the DataConnect API
* Authenticate and obtain values for `jsessionId` and `csrfToken` by calling the DataConnect API SESSIONAUTHRQ request. 
* Use the `jsessionId` and `csrfToken` to invoke the REST API endpoint(s), sending the `jsessionId` in the URI and the `csrfToken` in a request header. 
* For more details about DataConnect SSO, refer to  http://www.byallaccounts.net/Manuals/DataConnect/DataConnect_V4_Ultra_User_Guide.PDF.

Single Sign On (SSO) using Morningstar Authentication 
* Implementations that use Morningstar Authentication for SSO use UIM JWT for authentication. 
* When using Morningstar Authentication, the User logs into UIM, which issues a JSON web token (JWT) string, which then needs to be submitted to the REST API. 
For more information about Morningstar Authentication see the [Authentication](/knowledge-base/getting-started/authentication/overview) page.
* When the UIM JWT is used to access the REST API, the other existing authentication tokens are not expected nor required.  If others are used, there is a precedence order: 1) UIM JWT, 2) DataConnect SSO.
* The UIM JWT is submitted to the API endpoints using the authorization header with the header value "Bearer *token-value*".
* The JWT will expire after a pre-determined amount of time (the expiration time is set in the JWT itself by UIM). Requests with expired tokens will receive an error from the REST API indicating that the token has expired. Morningstar Authentication can then be used to obtain a new token. 

### Request Headers 

The following table contains information about headers that are applicable to all endpoints with exceptions noted.  The X-CSRF-Token header is used only with certain forms of authentication.

|Attribute|Description|
|:--------|:----------|
|`Authorization`|Only used for UIM authentication, and is then required. Used to provide the UIM JWT value, prepended with "Bearer". |
|`X-CSRF-Token`|CSRF Token for REST API. Only used for SSO authentication model for endpoints requiring authentication, and is then required. Refer to [Sample Code for SSO using DataConnect SSO](#sample-code-for-sso-using-dataconnect).|
| `Content-type`|Indicates media type of resource. Only required for POST endpoints where content is expected in the POST body. When not required can be omitted or left empty. |
| `Accept`|Content type client is requesting. Supported type is application/json. Required. |


### Sample Code for SSO using DataConnect
This example shows passing the credentials for the summary endpoint. In this example: 
* var myCsrfToken = “AD30BFA5CD5B5450515A40ACAF852D66F7456D5432C4DA14”
*	var myJsessionId = “CE2D0A6E7C60394ED1D9F46AFC02E632.s1a”    
* The url shown as https://www.byallaccounts.net is for production environment

````
var xhttpGetSummary = new XMLHttpRequest();
. 
. 
. 
function getSummaryState() {
	var href = “https://www.byallaccounts.net/api/v1/activities/summary;jsessionid=" + myJsessionId;
	xhttpGetSummary.open("GET", href, true);         
	xhttpGetSummary.setRequestHeader("X-CSRF-TOKEN", myCsrfToken);  
	xhttpGetSummary.setRequestHeader("Accept", "application/json");        
	xhttpGetSummary.send(); 
} 
````

### Sample Code for JWT SSO using Morningstar Authentication
This code example assumes that UIM JWT is being used for Morningstar Authentication SSO.
*	To access the REST API, this example maps to the URL for the Morningstar Authentication server for PROD, which is https://www.us-api.morningstar.com/aggapi/v1 
*	Any URIs returned in the JSON REST API response bodies will also reference this base URL. 

````
var xhttpGetSummary = new XMLHttpRequest();
.
.
.
function getSummaryState() {
    var href = “https://www.us-api.morningstar.com/aggapi/v1/activities/summary";
    xhttpGetSummary.open("GET", href, true);         
    xhttpGetSummary.setRequestHeader("Authorization", "Bearer "+myUIMJWT);  
    xhttpGetSummary.setRequestHeader("Accept", "application/json");        
    xhttpGetSummary.send(); 
} 
````

### Supplemental Response Model Information for GET /credentials/accounts  

The following sections supplement the response model information for GET /credentials/accounts

### Account and Credential Error Information  
Credentials and Accounts can be incomplete (missing required information like a login, or an account number), or they can be complete and have errors as reported by the custodian when the credentials are used to attempt to access a customer’s data at the custodian. These errors could include wrong login/password, account number could not be found, etc.   

The unifiedStatusInfoType field indicates an error condition that should be relayed to the user.  If unifiedStatusInfoType is absent then no error condition exists at the present time.  When unifiedStatusInfoType is present there will always be a unifiedStatusInfoMessage that will contain a suggested text form of the message for presentation to the user.  
For more information about unifiedStatusInfoType, refer to Table of Authentication/Aggregation Status Messages on page 16.  Note that some errors listed may not occur frequently, but they are included for completeness.  

There are other fields in the response that contain a variety of information about status, but these fields should not be used.  They are present for historical reasons and are superseded by unifiedStatusInfoType.   

These fields will likely be removed in a future version of the REST API. The following fields should NOT be used to determine whether a credential or account is incomplete or has another type of error: 
*	aggregationStatusErrorCode
*	authenticationStatusErrorCode
*	alarm
*	credentialComplete





### Activity in Progress Information  
As described above, this endpoint can return information about server “activity in progress” for objects in the response collection.  Activity in progress includes:
*	testing that a credential authenticates at a custodian
*	discovering accounts available for a credential at a custodian
*	aggregating data for accounts from the custodian 


These operations are initiated and running in the ByAllAccounts server while the UI or API caller is awaiting the results of those operations. This activity information can be provided for two different scopes:  `SESSION` or `GLOBAL`.  The default is `SESSION` if you have a session, and `GLOBAL` if you do not (some forms of authentication do not use a session).  If you have a session you can request `GLOBAL` using the scope query parameter.  For session scope, the progress information is reported for the above operations that were initiated during the current session.  For global scope,  the information will be reported for all activity initiated through the REST API for the target objects (regardless of who initiated that activity).   
The activityInProgress field at the top of the response will have a value of “true” if there is activity in progress for any object in the collection, otherwise “false”.  
For each object, the activityInProgressStatus field:
*	is absent if no activity occurred for the scope of the request  (as determined by the query parameters: scope and limitToProgressAfter). 
*	if present and value is:


    *	 “In Progress” then authentication or aggregation activity is currently occurring for this object within the ByAllAccounts Server for the scope of the request (as determined by the query parameters: scope and limitToProgressAfter). 

    *	 “Complete” then authentication or aggregation activity has completed for this object within the ByAllAccounts Server for the scope of the request (as determined by the query parameters: scope and limitToProgressAfter).

While asynchronous activity is occurring for objects in the response, the error status on objects can change multiple times and additional objects can be added to the response.  For example, if a new credential was added and account discovery was initiated (e.g. by the BAA ConsumerUI), then as accounts are discovered they will appear in the response, and subsequently data for those accounts will be aggregated and their market value will appear.  

### Authentication Aggregation Status Messages
These are the status information types and messages provided in the response of GET /credentials/accounts.

|unifiedStatisInfoType|unifiedStatusInfoMessage|
|:--------|:----------|
|`accountClosed`|Account closed. |
|`aggCannotLoadDataCheckLater`|We are having trouble accessing this institution. Please check back later.
|`badAccountCheckLater`|We are having trouble accessing this account. Please check back later  |
|`badAccountVerifyAccountNum`|We are having trouble accessing this account. Please verify the account number.|
|`cannotConnectBadLoginPw`|	Cannot connect. The {{loginTerm}} or {{passwordTerm}} is incorrect. |
|`cannotConnectBadLoginPwIsac`|Cannot connect. The {{loginTerm}}, {{passwordTerm}}, or activation code is incorrect. |
|`cannotConnectBadLoginPwSqa`|Cannot connect. The {{loginTerm}}, {{passwordTerm}}, or an answer to a security question is incorrect. |
|`cannotConnectBadLoginPwSqaIsac`|Cannot connect. The {{loginTerm}}, {{passwordTerm}}, an answer to a security question, or activation code is incorrect. |
|`cannotConnectMissingAcctNum`|Cannot connect. Missing account number. |
|`cannotConnectMissingLoginPW`|Cannot connect. Missing {{loginTerm}} or {{passwordTerm}}. |
|`cannotConnectNotAuthorized`|Cannot connect.  Access to accounts is not authorized. |
|`cannotConnectOauthAcctNotAuthorized`|Cannot connect. Account is not authorized.|
|`cannotConnectOauthNotConfigured`|Cannot connect. Further configuration is required to use this institution.  |
|`cannotConnectUserActionUserAgreement`|Cannot connect. The institution requires you to login on their website and accept a user agreement. |
|`cannotConnectUserActionPersonalInfo`|Cannot connect. The institution requires you to login on their website and update or verify personal information or preferences. |
|`cannotLoadDataCheckLater`|We are having trouble accessing this institution. Please check back later. |
|`cannotVerifyFiLimitation`|Cannot verify credentials due to institution limitation. |
|`credHasNoAccounts`|No accounts are connected to this credential yet. |
|`filoginCannotConnectBadLoginPw1`|Cannot connect. The {{loginTerm}} or {{passwordTerm}} is incorrect. |
|`fiNotYetSupported`|Institution is not yet supported. |
|`fiRequestMissingElements`|Institution is not yet supported. A login, password, and account number are required before support can be processed. |
|`isacCannotConnectBadIsac`|Cannot connect. The information you provided is incorrect. |
|`noAccountsFound`|No accounts found at this institution. |
|`noConnectAttemptYet`|No connection attempt made yet. |
|`noNewAccountsFound`|All accounts are already set up. |
|`oauthCannotConnectBadAuthorization`|Cannot connect.  Authorization failed. |
|`sqaCannotConnectBadSqa`|Cannot connect. The answer to a security question is incorrect. |
	
	
### Account Types 
|Type|Type|
|:--------|:----------|
|UNKNOWN|OTHER |
|BANKING_CD|BANKING_CHECKING |	
|BANKING_CREDITLINE|BANKING_DEPOSIT |
|BANKING_MONEYMARKET|BANKING_OTHER |
|BANKING_SAVINGS|CREDITCARD |
|HEALTHACCOUNT_FSA|HEALTHACCOUNT_HRA |	
|HEALTHACCOUNT_HSA|HEALTHACCOUNT_OTHER |
|INSURANCE_ANNUITY|INSURANCE_LIFEINSURANCE|
|INSURANCE_OTHER|INVESTMENT_401A |
|INVESTMENT_401K|INVESTMENT_403B |
|INVESTMENT_457B|INVESTMENT_529 |
|INVESTMENT_BROKERAGE|INVESTMENT_CASHMANAGEMENT |
|INVESTMENT_COVERDELL|	INVESTMENT_ROTHIRA|
|INVESTMENT_IRA | INVESTMENT_KEOGH |
|INVESTMENT_MUTUALFUND|INVESTMENT_OTHER |
|INVESTMENT_PENSION|	INVESTMENT_PREPAIDTUITION	LOAN_PERSONAL
 INVESTMENT_PROFITSHARE| INVESTMENT_SARSEP  |
|INVESTMENT_RETIREMENT|INVESTMENT_SAVINGSBOND |
|INVESTMENT_SEPIRA| INVESTMENT_TREASURYBOND|	
|INVESTMENT_TRUST| INVESTMENT_UGMA|
|INVESTMENT_UTMA|LOAN_AUTO |
|LOAN_BANK|LOAN_BOAT |
|LOAN_HOMEEQUITY|LOAN_MORTGAGE |	
|LOAN_OTHER|LOAN_STUDENT |


### Related Information  

* [*Morningstar Connect Evaluation Guide*](http://www.byallaccounts.net/Manuals/Accountview/CustomElement_Evaluation_Guide.pdf)
* [*Introduction to Morningstar Connect*](http://www.byallaccounts.net/Manuals/Accountview/CustomElement_AccountSetup.pdf)
* [*DataConnect V4 Ultra User Guide*](http://www.byallaccounts.net/Manuals/DataConnect/DataConnect_V4_Ultra_User_Guide.PDF)