Skip to main content

Guide

The SSO API's purpose is to add Users to the MX platform, provide their credentials, and log the Users into MoneyDesktop. The API deals with three entities: Client, User, and Member.

A Client is a partner that contracts with MX.

A User will connect to MoneyDesktop through the Client's web page or service.

A User is a person. A User is added to a Client.

A Member is a container attached to the User that holds the credentials used to request the User's data from the Data Provider.

The Client GUID is required to be passed as the "c" parameter on the URL in every SSO API endpoint call. The Client GUID is required to ensure that the external_user_guid for the User is unique within each Client, otherwise collisions could occur between Clients. Either the client_guid or the external_client_guid may be used.

Each API call must also have an API key passed as the "k" parameter to identify the partner who is making the API call.

You will need to use a GUID to identify the Users and Members for the read and create API calls. You can use any value you have in your system for this purpose. It can be a GUID or ID that is already in your User table, a hash of their account number, or any other value that is unique and consistent. When you call the SSO API, you will use that GUID to identify the Users and Members. It is recommended to use your choice of GUID for the User and to derive a GUID for the Member based on the User GUID, such as "M-{userGUID}". This is the convention that will be used in the examples.

Basic SSO API workflow​

  1. READ the User. If the user exists, skip to step 3.
  2. CREATE the User under the proper Client. Skip to step 4.
  3. READ the Member. If the member exists, skip to step 5.
  4. CREATE the Member, containing the credentials for that User. Skip to step 6.
  5. UPDATE the Member. If the credentials change or expire they should be refreshed at this point, otherwise this step can be omitted.
  6. Open MoneyDesktop.

When you log a User into MoneyDesktop you should always follow the API workflow. Perform the User read and create the User if needed. Next, perform the Member read and create the Member if needed. The Member read can be skipped and you can go straight to the Member create if it is immediately following a User create, but otherwise it should be performed each time. It is important to check both the User and the Member as outlined every time the User logs in. If an error or communication interruption occurs during the initial User and Member create requests you might end up with no User in the system, or else a User without a Member attached to hold the credentials. If you follow the API workflow as outlined then the User and/or the Member will be created the next time the User is logged into MoneyDesktop and the situation will resolve itself.

You do not have to keep track of Users that you have created on the MX platform if you follow the API workflow. You can simply check to see if they exist by doing a User read with your GUID, create them if they do not exist, do the same with the Member for that User, and then log the User in. Should you choose to keep track of which Users have been created inside the MX platform, you may do so, but you should still follow the API Workflow. This will allow the MX Client Services team to delete a User if it becomes necessary for some reason and the User and Member will automatically be recreated on the next login, even if you think they already exist in our system. It also prevents issues that would arise if your list of users gets out of synch with our system.

The Member update step needs to occur on every login to refresh the credentials if you use either an expiring userkey or if you use login and password. We highly recommend a userkey over the login and password. If you use a permanent userkey this step can be omitted from the API workflow.

Single Sign-On has now been accomplished and you can log the user . The response from the User read or the User create will contain the fields needed to open MoneyDesktop. The token in the response expires in ten minutes. If it is possible for that amount of time to expire between the time you do the initial Read or Create and when you open MoneyDesktop then you will need to do a fresh User read just before logging the user in.

Here is some specific information about each of the API calls you will need to use. These examples follow MX's Best Practices recommendations.

User read (GET request)​

In the URL, you will pass the GUID for the User. The Client GUID to which the User belongs is passed in the "c" parameter of the URL. No headers or request body are required.

On a successful response (http response code 200), the body will contain a master_widget_url and also a guid and user_token. You can use either the master_widget_url or the guid and user_token to open the master widget. Please see the MoneyDesktop 4.0 guide on the developer portal for more information on how this is accomplished.

warning

Do not attempt to parse the master_widget_url or any other URL provided in current or future SSO API response bodies. They are intended to be used directly as the src for an iFrame only. Their contents can change at any time.

User create (POST request)​

This creates a User on the MX platform. Pass the GUID you want us to associate with that User in the external_user_guid parameter in the request body. This is the same GUID you will always use in the future when you do a User read. It can be any unique string you have in your system. You need to specify "Content-Type:application/json" in the request header.

On a successful response (http response code 200), the body will contain the same master_widget_url, guid, and user_token as does the User read response.

Pass the external_client_guid in the "c" parameter in the URL to specify which Client (Bank or Credit Union) is adding the User. This GUID is determined in advance between the Partner and MX and can be any string of your choosing for each Client. The first_name, last_name, email, phone, birthdate, sex, credit_score, and zip_code parameters are optional, but as much information should be passed as possible. This makes for a better user experience when the user first enters the software when this information is already present. The first and last names and email address are particularly important.

Member read (GET request)​

In the URL, you will pass the GUID for the Member. The Client GUID to which the User belongs is passed in the "c" parameter. This call will tell you if the Member already exists or if the Member should be created. A successful response will return http response code 200.

Member create (POST request)​

Whenever you create a User you will then Create a Member for that User to attach the credentials. These credentials will be used by MoneyDesktop when requesting the account and transaction data for that User.

The external_user_guid parameter identifies the User. Pass in the same User GUID in the Member create API call that you used when you created the User.

It is recommended, although not required, to set an external_member_guid for the member. This is important if you will need to update the credentials at a future time, otherwise you will need to store the MX-created member guid for this purpose. It is recommended that this GUID be manufactured by prepending a value to the user's external_user_guid, such as "M-". For example, if the user GUID was "ABCDE" the recommended member GUID would be "M-ABCDE". Do not use "MBR-" as the prefix because this prefix is reserved by the system.

The credentials parameter is required. The credentials can be either a username/password combination, or a userkey. The userkey can be a hashed or encrypted value of a member or account number, or it can be any other GUID that will uniquely identify the User during data collection. If you use the username/password credential or an expiring userkey then you must also implement the Member update API call to send updated credentials at each login.

You need to specify "Content-Type:application/json" in the request header.

A successful response will return http response code 200.

warning

Do not use any other parameters. The name and institution_guid parameters should not be used unless instructed to do so by a MoneyDesktop integration engineer.

Member update (PUT request)​

Use this to update the user's credentials on each login if the credentials are a login/password combination or an expiring userkey. You do not need to use this call if you use a permanent userkey as the credential.

In the URL, you will pass the GUID for the Member. This is the external_member_guid you specified when you created the Member. The Client GUID to which the User belongs is passed in the "c" parameter.

Pass the credentials as you did in the Member create call with their updated values.

You need to specify "Content-Type:application/json" in the request header.

A successful response will return http response code 200.

Widget-based UI​

The User create and User read response bodies contain a master_widget_url and individual widget URLs that are used to open MoneyDesktop.

See the Personal Finance Management documentation for more information.

Legacy flash-based UI (discontinued)​

This UI has been discontinued. The User read and create response bodies contain a login_url that was used to open the legacy flash-based UI. For backward compatibility that URL is still present in the User create and User read response bodies, but it is deprecated and should no longer be used. It currently returns a URL that will open the HTML5 master widget.

Possible errors​

If you get a 503 error from any API call it means our server is undergoing maintenance and an appropriate message should be displayed. You also want to allow for a 404 or other error return. Do not assume that any error is a "user not found" or "member not found" error. Please check the https response code for the specific value expected in each request.

Converting an SSO v2 API integration to the newer MX APIs​

It is fairly straightforward to transition from using SSO API v2.8 to using the newer MX APIs. The APIs are compatible and can be used simultaneously. A partner can change over when they are ready to do so. All existing client, user, and member ID values can be used.

The functionality of the SSO API v2.8 was split into two different APIs:

  • The endpoints to perform CRUD (create, read, update, delete) actions on user and member objects were moved to the MDX Real Time v5 API.
  • The URL needed to open an MX widget such as the master widget was previously found in the user responses (typically after reading or creating a user). The URL is now obtained with a request to the SSO v3 API.

Are the objects compatible between the APIs?​

The names of some of the object fields have changed, but the fields are the same on the MX back end and all existing values remain and can be used.

  • The external_guid field (also known as external_user_guid) in the user is now id.
  • The external_member_guid field is now id in the member.
  • The client_external_guid (passed on the URL as a c parameter in the old API) is now the client id and is passed in the URL route.

SSO API v2.8 allowed a partner to pass either their own IDs (called external GUIDs) for the client, user, and member objects, or the MX GUIDs. The new APIs work exclusively with partner-provided IDs.

Is JSON still supported?​

Both new MX APIs support either XML or JSON. Since SSO API v2.8 supported only JSON we recommend you stay with JSON, but either encoding can be used.

If XML is desired, substitute xml for json in the URL extension and in the Accept and Content-Type headers.

Do the new APIs authenticate differently?​

You will use the same API key and client ID values that you have been using. They are passed differently in the request, however:

  • The client ID is now passed as part of the URL route instead of being a c parameter on the URL.
  • The API key is now passed in an MD-API-KEY header instead of being a k parameter on the URL.

How has the workflow changed?​

The workflow shown above is slightly altered.

  1. Read a member (MDX Real Time).
    • If the member exists, go to step 5.
    • This step tests whether the user and member already exist. This required two requests in the old API, but can be done with a single request now since both the user ID and member ID values are on the URL and the read member request will only succeed if both objects are present.
  2. Read a user (MDX Real Time).
    • If user exists, go to step 4.
    • This step tests whether the user exists. It is possible that the user was created but not the member, resulting in a Not Found error in step 1. This additional test determines whether the user needs to be created in addition to the member.
  3. Create a user (MDX Real Time).
    • This creates the user if step two shows it does not exist.
  4. Create a member (MDX Real Time).
    • This step creates a member if it is shown not to exist in steps 1 and 2.
    • For newly-created members, no update will be necessary, so go to step 6.
  5. Update the member (MDX Real Time).
    • This is an optional step to refresh the member's credentials. It is only necessary if the On Demand protocol will be used, and then only if the credentials supplied for the member expire or must be refreshed. Most integrations should not need this step because they use a permanent userkey that doesn't need to be refreshed.
  6. Get a widget URL (SSO API)
    • This authenticates the user and returns the appropriate widget URL from the SSO v3 API. If more than one widget will be embedded on the same page, then multiple requests to the SSO v3 API should be made.

Comparing old and new endpoints​

With the examples on the right, you can compare the old and new requests for creating a user and member.

The examples use the following values:

  • API key: your-api-key
  • Client ID: client1234
  • User ID: U-39XBF7
  • Member ID: M-39XBF7

Old create user request (SSO v2.8)

Endpoint: POST https://int-api2.moneydesktop.com/user?c=client1234&k=your-api-key`` Headers: content-type: application/json` Body:


_10
{
_10
"external_user_guid":"U-39XBF7",
_10
"email": "victoria.williams@example.com",
_10
"first_name":"Victoria",
_10
"last_name":"Williams",
_10
"phone":"9015550001"
_10
}

New create user request (MDX Real Time v5)

Endpoint: POST https://int-live.moneydesktop.com/client1234/users Headers:

  • MD-API-KEY:your-api-key
  • accept:application/vnd.moneydesktop.mdx.v5+json
  • content-type:application/vnd.moneydesktop.mdx.v5+json Body:

_10
{
_10
"user": {
_10
"id": "U-39XBF7",
_10
"email": "example@example.com",
_10
"first_name": "John",
_10
"last_name": "Smith",
_10
"phone": "5055551234"
_10
}
_10
}

Old create member request (SSO v2.8)

Endpoint: POST https://int-api2.moneydesktop.com/member?c=client1234&k=your-api-key Headers: content-type: application/json Body:


_10
{
_10
"external_user_guid": "U-39XBF7",
_10
"external_member_guid": "M-39XBF7",
_10
"credentials": [
_10
{
_10
"field_name": "userkey",
_10
"response": "key123"
_10
}
_10
]
_10
}

New create member request (MDX Real Time v5)

Endpoint: POST https://int-live.moneydesktop.com/client1234/users/U-39XBF7/members.json Headers:

  • Content-Type: application/vnd.moneydesktop.mdx.v5+json`
  • Accept: application/vnd.moneydesktop.mdx.v5+json
  • MD-API-KEY: your-api-key" \ Body:

_10
{
_10
"member": {
_10
"id": "M-39XBF7",
_10
"userkey": "key123"
_10
}
_10
}

How do I get a widget URL now?​

The SSO v3 API is now used to authenticate the user and get a URL to open an MX widget. The format of the URL that is returned has not changed and the same rules apply. The URL contains a token which can only be used a single time and that expires in ten minutes if not used. You must get a fresh URL each time the widget is re-rendered on the page.

The is_mobile_webview field shown in the example can be used to signal when the widget is going to be opened in a WebView rather than being embedded in an HTML page. See the Personal Finance Management documentation for more information on embedded widgets on different platforms.

Endpoint to create a widget URL: POST https://int-sso.moneydesktop.com/client1234/users/U-39XBF7/urls.json Headers:

  • Content-Type: application/vnd.moneydesktop.sso.v3+json
  • Accept: application/vnd.moneydesktop.sso.v3+json
  • MD-API-KEY: your-api-key Body

_10
{
_10
"url": {
_10
"type": "connect_widget",
_10
"is_mobile_webview": false
_10
}
_10
}

Several things to note​

In the new APIs, an HTTP status code of 404 Not Found will be returned when an any object is not found. This differs from SSO v2.8 which returns a 400 status on read user and the 500 status code on read member when the objects were not found. The 200 Success status when a request succeeds is unchanged.

The API key and client ID are passed differently, but the same values are used.

Each request needs an Accept header.

POST and PUT requests need a Content-Type header.

Members are now scoped under a user. The member routes will have the user ID on the URL rather than being in the request body.

The request body format has changed. The objects are now "rooted" in the request body rather than being just a list of fields.

The Accept and Content-Type headers are different in the two new APIs. Be sure you use the correct header for the API being used, as shown in the examples above.

On this page