OAuth in Browsers - MX Documentation

Workflow Diagram

Create a Member

To create an OAuth member, set "is_oauth": true.We recommend always including a unique id when creating any Platform API resource to simplify syncing between your systems and ours.To choose which products aggregate after a successful OAuth connection, include the data_request.products parameter in your request.Endpoint: POST /users/{user_guid}/members

curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members' \
-d '{
      "member": {
        "institution_code": "mx_bank_oauth",
        "id": "unique_id",
        "is_oauth": true
      }
    }'

{
    "member": {
        "guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
        "id": "unique_id",
        "metadata": "Additional information",
        "name": "MX Bank (Oauth)",
        "self": "/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
        "institution": {
            "code": "mx_bank_oauth",
            "guid": "INS-1572a04c-912b-59bf-5841-332c7dfafaef",
            "iso_country_code": "US",
            "name": "MX Bank (Oauth)",
            "products": [
                "account_verification",
                "identity_verification",
                "transactions"
            ],
            "self": "/institutions/INS-1572a04c-912b-59bf-5841-332c7dfafaef"
        },
        "member_status": {
            "status": "PENDING",
            "error": null,
            "self": "/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa/status"
        },
        "oauth": {
            "is_oauth": true,
            "authorization_url": "https://mxbank.mx.com/oauth/authorize?client_id=b8OikQ4Ep3NuSUrQ13DdvFuwpNx-qqoAsJDVAQCyLkQ&redirect_uri=https%3A%2F%2Fint-app.moneydesktop.com%2Foauth%2Fredirect_from&response_type=code&scope=openid&state=d745bd4ee6f0f9c184757f574bcc2df2",
            "self": "/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa/oauth/authorization_url"
        },
        "user": {
            "guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c",
            "id": "unique_user_id",
            "metadata": null,
            "self": "/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
        }
    }
}

Do not set "referral_source": "APP" in the oauth object in browser implementations — it breaks OAuth flows. In typical browser environments, omit this option or set it to "BROWSER" explicitly.

Load the OAuth URI

Load the oauth.authorization_url from the last step for the end user.Authorization URLs are one-time use. Don’t hard code an expected URI into your application. To get a new URL, use the create OAuth authorization URL endpoint (POST /users/{user_guid}/members/{member_guid}/oauth/authorization_url).Don’t prepend https:// to the URI string; MX includes it.Here, the user interacts with the institution’s OAuth page and chooses what data to share with MX and, therefore, with you.

MX's OAuth Complete Page Loads

The user is redirected to an MX webpage that shows the final state of the OAuth process and delivers success or failure postMessages.You must capture these postMessages, which are one of the following:

OAuth Complete Error PostMessage

Triggers when the OAuth process ends in an error state. The OAuth UI sends the oauthComplete/error message, which is used in API implementations.Error Reasons

Value	Definition
`CANCELLED`	The user cancelled or exited the OAuth process.
`DENIED`	The user was unable to authenticate with the provider.
`IMPEDED`	User action is required at the provider’s website.
`PROVIDER_ERROR`	An unknown error occurred at the provider.
`SERVER_ERROR`	An unknown error occurred.
`SESSION_ERROR`	The user was unable to reauthenticate using the existing session.

JSON

{
  "metadata": {
    "error_reason":"CANCELLED",
    "member_guid": "MBR-2344"
  },
  "mx": true,
  "type": "oauthComplete/error"
}

OAuth Complete Success PostMessage

Triggers when the OAuth process completes successfully.

JSON

{
  "metadata": {
    "member_guid": "MBR-2344"
  },
  "mx": true,
  "type": "oauthComplete/success"
}

The process is complete

The OAuth process has ended in success or error. You can close the OAuth window and redirect the user as your use case requires.

​Workflow Diagram

​OAuth Complete Error PostMessage

​OAuth Complete Success PostMessage

​The process is complete

Workflow Diagram

OAuth Complete Error PostMessage

OAuth Complete Success PostMessage

The process is complete