Authentication Overview
In this section we are going to explain how to authenticate in Money Button using our API endpoints.
Permission Grant Flow
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:
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.