OAuth in Mobile Apps - MX Documentation

This is the workflow for OAuth in mobile apps:

1. Create a Member

To create an OAuth member, set the following:

"is_oauth": true.
client_redirect_url in the oauth object so we can send you UI messages with the right scheme. This can be any string; this guide uses https://mx.com.
"referral_source": "APP" in the oauth object tells MX to use your client_redirect_url to return users to your app.

You cannot include end-user credentials in the request body when creating an OAuth member, so they’re never shared with a third party. We recommend always including a unique id when creating any Platform API resource to simplify syncing between your systems and ours. 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": {
        "id": "unique_id",
        "institution_code": "mx_bank_oauth",
        "is_oauth": true,
        "metadata": "Additional information"
      },
      "oauth": {
        "client_redirect_url": "https://mx.com",
        "referral_source": "APP"
      }
    }'

{
    "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"
        }
    }
}

2. Load the OAuth URI

Load the oauth.authorization_url from the last step in an ASWebAuthenticationSession (iOS) or Auth Tab (Android).

Do not open the OAuth window in a WebView. Some financial institutions have security restrictions for certain web containers or browsers. Use ASWebAuthenticationSession for iOS, or an Auth Tab via Chrome Custom Tabs for Android. See OAuth WebView Limitations for more information.

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. When finished, the user is redirected to your oauth.client_redirect_url. MX appends the success or error status and the member GUID to this URL.

Example client_redirect_url with Appended Information

https://mx.com?status=success&member_guid=MBR-df96fd60-7122-4464-b3c2-ff11d8c74f6f

​1. Create a Member

​2. Load the OAuth URI

1. Create a Member

2. Load the OAuth URI