Skip to main content

API Requirements

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.

info

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 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, please see feature documentation for more information.
500, 502, 503, 504 Server errorsSomething went wrong on MX's end.

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.

On this page