OAuth in Mobile Apps - MX Documentation

This is the workflow for OAuth in mobile apps:

1. Create a Member

Now we’ll need to create an OAuth member, which you can do by setting 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, but we’ll use https://mx.com in this guide.
"referral_source": "APP" in the oauth object tells MX to use the client_redirect_url you provided so you can get back to your app.

Remember that you cannot include end-user credentials in your request body when creating an OAuth member. The idea is to never share those with a third party. 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. 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

Now that you’ve got the oauth.authorization_url from the last step, load it 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 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. Once the end user is done, they will be redirected to the URL you provided for oauth.client_redirect_url. We’ll append information to this URL about success/error as well as the member GUID.

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