OAuth in Browsers

Workflow Diagram

Step 1

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.

Standard aggregation (of account and transaction data) will start after a successful OAuth connection. This can be disabled with the skip_aggregation parameter.

Endpoint: POST /users/{user_guid}/members

Request

Response

Language:shell

_11

curl -i -X POST 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members' \

_11

-u 'client_id:api_key' \

_11

-H 'Accept: application/vnd.mx.api.v2+json' \

_11

-H 'Content-Type: application/json' \

_11

-d '{

_11

"member": {

_11

"institution_code": "mx_bank_oauth",

_11

"id": "unique_id",

_11

"is_oauth": true

_11

}

_11

}'

warning

Do not set "oauth_referral_source": "APP" 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.

Step 2

Load the OAuth URI

Now that you have the oauth_window_uri from the last step, load it for the end user.

oauth_window_uris are one-time use. Don't hard code an expected URI into your application.

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.

Step 3

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.

_10

{

_10

"metadata": {

_10

"error_reason":"CANCELLED",

_10

"member_guid": "MBR-2344"

_10

},

_10

"mx": true,

_10

"type": "oauthComplete/error"

_10

}

OAuth Complete Success PostMessage

Triggers when the OAuth process has completed in a successful state.

_10

{

_10

"metadata": {

_10

"member_guid": "MBR-2344"

_10

},

_10

"mx": true,

_10

"type": "oauthComplete/success"

_10

}

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.