Skip to main content

​
Authentication

​
API Key

When accessing the SSO API, each request is authenticated using an environment specific API key that was issued to you during your initial integration. API keys are passed in a MD-API-Key request header as follows: MD-API-Key: YOUR_ENVIRONMENT_SPECIFIC_API_KEY If a request is made with an invalid API key, or an API key from a different environment, a 401 (unauthorized) will be returned.

​
IP Filtering

Requests to the SSO API are also filtered by IP address. All IP addresses where API requests originate must be whitelisted. Requests made from invalid IP addresses will receive a 403 (forbidden). All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

​
Base URL

All URL endpoints in the MX SSO API have a base URL. The base URL will depend on the environment being addressed:
  • Production Server: https://sso.moneydesktop.com/{client_id}
  • Integration Server (for initial integration testing): https://int-sso.moneydesktop.com/{client_id}
The :client_id identifies the client whose users are being managed and corresponds to the unique identifier setup with MX during that client’s integration. See MX Architecture In the Getting Started Overview for information about clients in the MX architecture.

​
HTTP Status Codes

The SSO API uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, etc.), and codes in the 5xx range indicate an error with MX’s servers.
Error codes and messages are for logging and for informational purposes only and may change from time to time. Do not check for specific codes or messages as this may break your integration. The http status response codes are sufficient for an integration workflow and processing of the error response body is not needed.
Sometimes simply returning the HTTP status code is not enough to indicate what went wrong. To compensate for this, endpoints may respond with a body containing more information about the error:
Status CodeDescription
200 OKEverything worked as expected.
204 No ContentEverything worked, but no content is returned. Typically returned from DELETE requests.
400 Bad RequestOften missing a required parameter.
401 UnauthorizedNo valid API key provided.
403 ForbiddenThe IP address doesn’t match the API key provided.
404 Not FoundThe requested item doesn’t exist. Either an id on the URL does not exist or the URL format is invalid. This error will also be returned when a resource is requested that is not enabled for that user.
429 Too Many RequestsThis error is triggered when exceeding the maximum number of concurrent connections or rate limit. See details below.
500, 502, 503, 504 Server errorsSomething went wrong on MX’s end.

​
429 Too Many Requests

This error is triggered when exceeding the maximum number of concurrent connections, or the rate limit for requests per second (rps) is surpassed. Requests receiving a 429 status code should be retried once the rate limit window has expired. To prevent this error, decrease the number of concurrent connections or the number of requests per second. Rate limiting is applied per client with the following thresholds:
  • GETs: 2000/rps
  • POSTs: 750/rps
  • PUTs: 750/rps
  • DELETEs: 150/rps
Individual features may implement specific rate limit overrides.

​
Headers

​
Accept Header

An Accept header is required for all requests. It contains the appropriate content type and version information. Use either:
  • Accept: application/vnd.moneydesktop.sso.v3+xml
  • Accept: application/vnd.moneydesktop.sso.v3+json

​
Content-Type Header

POST requests require a Content-Type header to specify the format of the request body. Use either:
  • Content-Type: application/vnd.moneydesktop.sso.v3+xml
  • Content-Type: application/vnd.moneydesktop.sso.v3+json

​
Resources

​
Users

A User is a person that can use MX. A partner will create a User on the MX Platform using MDX Real Time to allow that person to use MX’s products.

​
Widget URLs

Widget URLs are used to authenticate users to the MoneyMap components and to open the widget view. URLs are single-use and expire 10 minutes after being issued. A new URL must be obtained each time a user is authenticated or whenever the widget needs to be reloaded.

​
API Tokens

API tokens are used to authenticate users to MX’s Nexus API. API tokens are single-use, so a new one should be retrieved each time a user is authenticated. API tokens expire 10 minutes after being issued.

​
Response Format

A URL extension should be used to specify the desired response format. XML and JSON are supported:
  • https://sso.moneydesktop.com/{client_id}/users/{user_id}.xml
  • https://sso.moneydesktop.com/{client_id}/users/{user_id}.json
If not specified, XML will be returned.

​
Security

Requests must use TLS 1.2 (or higher) with known secure ciphers. See MX Authentication for more information.

​
Versioning

We strive to make changes to the API backwards-compatible. When do we make backwards-incompatible changes to the API, we increment the version. Because of this, it’s best to specify the version of the API with each request. Versions are passed as part of the request’s Accept header as shown in the examples to follow. Requests that don’t specify a version will return a 404 error.