SSO
SSO APIs are exposed as a transparent passthrough to the MX SSO APIs via the Candescent APIs Gateway. After OAuth V2 token validation and routing, the gateway forwards request headers, paths, query parameters, and payloads to MX and returns responses unchanged.
The MX SSO APIs are a RESTful interface for authenticating users on the MX platform. They
provide endpoints to obtain widget URLs (for Personal Finance Management and Financial Insights
experiences) and an api_token for initiating a Nexus API session.
For complete schemas and the full set of supported operations, see the MX SSO APIs documentation.
End-user benefits
- Launch MX widgets (for example, Mini Budgets and other PFM experiences) within a webview or iframe without exposing long-lived MX credentials.
- Authenticate users on the MX platform using SSO-based sessions and short-lived redirect URLs.
- Access Financial Insights and MoneyMap-style experiences through a consistent single sign-on authentication process.
Integration capabilities
- Transparent passthrough ensures that SSO headers, paths, query parameters, and payloads are forwarded to MX, and that HTTP status codes and responses are returned unchanged.
- Gateway controls are applied by Candescent, including OAuth V2
Bearertoken validation, spike arrest, and quota enforcement, before requests are forwarded to MX. - MX routing is configured by setting
ext_hostto the MX SSO host such assso.moneydesktop.com(production) orint-sso.moneydesktop.com(sandbox). - Content negotiation is supported through MX vendor-specific
Acceptheaders, such asapplication/vnd.moneydesktop.sso.v3+xmlorapplication/vnd.moneydesktop.sso.v3+jsonand include institution-scoped path segments as documented for each endpoint.
Required headers
| Header | Description |
|---|---|
Authorization | Bearer {token} (OAuth V2) |
correlationId | UUID used to trace and correlate requests across services for debugging and logging. |
ext_host | MX SSO upstream host (for example, sso.moneydesktop.com (production) or int-sso.moneydesktop.com (sandbox)). Required for gateway routing; stripped before forwarding to MX. |
Accept | MX vendor media type (for example, application/vnd.moneydesktop.sso.v3+xml or application/vnd.moneydesktop.sso.v3+json). Required by MX; forwarded unchanged. |
Content-Type | MX vendor media type (for example, application/vnd.moneydesktop.sso.v3+xml or application/vnd.moneydesktop.sso.v3+json). Required by MX for POST request; forwarded unchanged. |
Error codes
Candescent API Gateway
| Code | Message | HTTP Status Code |
|---|---|---|
| CMN_90000 | Internal server error | 500 |
| CMN_90001 | Client not authorized to access this resource | 401 |
| CMN_90001 | Quota limit violation | 500 |
| CMN_90002 | Spike limit violation | 500 |
| CMN_90008 | Header correlationId is invalid | 400 |
| CMN_90010 | Header correlationId is required | 400 |
| CMN_90010 | Header ext_host is required | 400 |
| CMN_90011 | Invalid or unsupported ext_host | 400 |
| CMN_90018 | Invalid token | 400 |
MX SSO APIs
For detailed descriptions and error semantics, refer to the MX SSO APIs documentation.
Endpoints
Passthrough Read
Transparent passthrough for **GET** requests to the [MX SSO APIs](https://docs.mx.com/api-reference/sso/v3/).
Passthrough Create
Transparent passthrough for **POST** requests to the [MX SSO APIs](https://docs.mx.com/api-reference/sso/v3/).
Passthrough Delete
Transparent passthrough for **DELETE** requests to the [MX SSO APIs](https://docs.mx.com/api-reference/sso/v3/).