Authentication Overview

In this section we are going to explain how to authenticate in Money Button using our API endpoints.

Permission Grant Flow

User permission grant diagram

The first step is to ask the user for consensus to share certain resources listed here. Every resource is restricted to a specific scope. You can check the resource documentation to see which scope do you need. Once you have selected the scope, the user can be asked to grant permission by redirecting them to our auth page:

  https://www.moneybutton.com/oauth/v1/authorize?
          response_type=code&
          client_id=<your app oauth identifier>&
          redirect_uri=<your app redirect uri>&
          scope=<your selected scope>&
          state=<client generated random string>

As you can see, this url has several query parameters:

  • response_type: At the moment the only response type supported by Money Button is code. We may support other types in the future but right now that is the only valid value.
  • client id: This is your app OAuth identifier. It's used to recognize your app.
  • redirect_uri: The endpoint where the access token have to be sent. It needs to be the same registered on your app's detail page.
  • scope: A space separated list of API scopes. For example users.balance:read users.profiles:read.
  • state: A random value generated by the client. This is a security measure. You should create a safe random value before starting the flow. At the end of the flow this value is given back. As a security measure you should check that the value returned is the same as the one sent. You can read more about the state param here.

Example:

https://www.moneybutton.com/oauth/v1/authorize?response_type=code&client_id=4df4b25fd2d966a41fb0f6f159096203&redirect_uri=http://localhost:5007/oauth-response-web&scope=auth.user_identity:read&state=somesecurerandomstring

After being directed there, the user will be asked for their consent to share the specified resources with your app:

Oauth consent screenshot

When the user clicks OK they will be redirected to the specified redirect URI.

https://myredirecturi.com?code=<access code>&state=<client generated random string>

Example:

https://myredirecturi.com?code=5f43fb324ff1bd0fadbfa2e9bcdf3da7096e1ede&&state=somesecurerandomstring

The code query parameter contains an authorization code. Basically a one use code to get a refresh token.

Requesting the refresh token.

Once you have an authorization code you can ask for a refresh token. That refresh tokens will allow you to access the resources that the user gave permission for. You can request the refresh tokens using /oauth/v1/token endpoint.

curl --request POST \
  --url 'https://www.moneybutton.com/oauth/v1/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=authorization_code \
  --data client_id=<YOUR_APP_OAUTH_IDENTIFIER> \
  --data code=<YOUR_AUTHORIZATION_CODE> \
  --data 'redirect_uri=<same redirect uri that you used to get the auth code>'

Example:

curl --request POST \
  --url 'https://www.moneybutton.com/oauth/v1/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=authorization_code \
  --data client_id=4df4b25fd2d966a41fb0f6f159096203 \
  --data code=5f43fb324ff1bd0fadbfa2e9bcdf3da7096e1ede \
  --data 'redirect_uri=https://myredirecturi.com'

The response is a JSON object that looks like this:

{
  "access_token": "<ACCESS_TOKEN>",
  "token_type": "Bearer",
  "expires_in": "<ACCESS_TOKEN_EXPIRATION_GAP>",
  "refresh_token": "<REFRESH_TOKEN>",
  "scope":"<list of granted scopes>"
}

Example:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI3IiwiYXVkIjoiNGRmNGIyNWZkMmQ5NjZhNDFmYjBmNmYxNTkwOTYyMDMiLCJleHAiOjE1NjU5NzY4MjgsInNjb3BlIjoiYXV0aC51c2VyX2lkZW50aXR5OnJlYWQifQ.kvcXQCOt0FVyaVonOF8gUSO7BZAYOudB_SleWRuOeog",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI3IiwiYXVkIjoiNGRmNGIyNWZkMmQ5NjZhNDFmYjBmNmYxNTkwOTYyMDMiLCJleHAiOjE1Njg1NjUyMjgsInNjb3BlIjoiYXV0aC51c2VyX2lkZW50aXR5OnJlYWQifQ.2qzrApJyQXi7EHJLxyQXHCk9VTMJppKoN3ZucgxP1rI",
    "scope": "auth.user_identity:read"
}

The access token is ready to be used. It expires in expires_in seconds.

curl --request GET \
  --url 'https://www.moneybutton.com/api/v1/auth/user_identity' \
  --header 'authorization: Bearer <YOUR_ACCESS_TOKEN>'

Money Button access tokens expire in 1 hour. But you can use the refresh token to get a new access token:

curl --request POST \
  --url 'https://www.moneybutton.com/oauth/v1/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=refresh_token \
  --data refresh_token=<YOUR_REFRESH_TOKEN>
  --data client_id=<YOUR_CLIENT_ID>

Again, the response is a JSON object like the following:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI3IiwiYXVkIjoiNGRmNGIyNWZkMmQ5NjZhNDFmYjBmNmYxNTkwOTYyMDMiLCJleHAiOjE1NjU5NzY5MDIsInNjb3BlIjoiYXV0aC51c2VyX2lkZW50aXR5OnJlYWQifQ.drb9iW4Vas8ccQXeH_I_QcMiEOTy7KpIM9kpo8UoVaM",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "auth.user_identity:read"
}

Application access

You can get application access creating a token using your Client identifier and your Client secret, and following the client_credentials flow. App tokens need to be requested using basic auth with client credentials:

ID=8ce101e4236efd4be4881072140b3c1b
SECRET=701e825b8f6ef16abff8a9cccfbe70cb
CREDENTIALS=`echo -n "$ID:$SECRET" | base64 -w 0`

curl --request POST \
  --url 'https://www.moneybutton.com/oauth/v1/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --header "Authorization: Basic $CREDENTIALS" \
  --data grant_type=client_credentials \
  --data scope=application_access:write

The response is like the following:

{
    "access_token": "<ACCESS_TOKEN>",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "application_access:write"
}

That access token can be used to access data belonging to the app.

← Javascript ClientOAuth →