OAuth in Browsers - MX Documentation

Workflow Diagram

Create a Member

Now we’ll need to create an OAuth member, which you can do by setting the following: "is_oauth": true.Also, we recommend that you always include a unique id when creating any resource on the Platform API so you can easily sync between your systems and ours.To specify 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 — this will break OAuth flows. In typical browser environments, you can simply omit that configuration option, or set it to "BROWSER" explicitly.

Load the OAuth URI

Now that you have the oauth.authorization_url from the last step, load it 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 the https:// protocol to the URI string, as MX includes this.This is where the user will interact with the institution’s OAuth page and determine what data will be shared with MX and, therefore, with you.

MX's OAuth Complete Page Loads

This process involves a redirect to an MX webpage whose function is to give the end user information about the end state of the OAuth process, and to deliver important success or failure postMessages.You must capture these postMessages, which will be one of the following:

OAuth Complete Error PostMessage

Triggered when the OAuth process has completed in an error state. The oauthComplete/error message will be sent from the OAuth UI, and 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 has completed in a successful state.

JSON

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

The process is complete

The OAuth process is now in an end state (either success or error) and the OAuth window can be closed and the user can be redirected where they need to go based on your use case.

​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