Authentication and Authorization
The Yodlee APIs are HTTP-based RESTful APIs. We use JSON Web Tokens (JWTs) for authentication and authorization. API requests and response bodies are delivered in JSON format.
Our authentication JWT follows the protocol in open standard RFC 7519. One web token, known as the application token, represents you (the developer). A second web token, known as the user token, represents the end-user you are working with.
You will present either an application token or a user token to authenticate each API call. You use an application token to make a call that doesn't involve a registered user. You use a user token to indicate which user's data should be processed in the call. Full details appear later on this page.
JWTs are signed using an RSA public/private key pair. In the sandbox environment, Yodlee provides your private key, holds the public key on your behalf, and uses it to create an issuer id. Your private key and your issuer id can be seen on your API Dashboard page. Your issuer id acts as an API key. You will use your issuer id to create a JSON web token that will be passed to Yodlee as a bearer token in an Authorization header for the RESTful APIs. Web tokens expire after 30 minutes.
Sample Request with JWT as a Bearer token in the Authorization header
GET /ysl/accounts? HTTP/1.1
Host: sandbox.api.yodlee.com
Content-Type: application/json
Api-Version: 1.1
Authorization: Bearer eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiIyYjMwZjY2Mi0xN2E1LTRlYjQtOGI1Ny00NWM2YmVmM2Q0YmMiLCJpYXQiOjE1NTAyNjY5ODEsImV4cCI6MTU1MDI2Nzg4MSwic3ViIjoic2JNZW01YzU0OWIxOGVlNDczMSJ9.KNRcrqzocGQyeR1U-wm0p3oDtEuGUZR09XP6FKjtrxbgJI_75JzmeEyAY1DclULe4_3mVEWPR0IagLt5_UvGHs1Ztx94WRnLxBadGyfzuute5kyRG1Zugj_8Yq2YMeyke8wGYHIgLVHdNozc2LPqzeYE-swD5wCrM8daGxSW7SI9jTEW9vzemHKCDVRgMIWTt12eCZKuYJHmD5IXT3RNLHUs4Z3PjISgNZxYomCWSb9MskcI-kQ5UcWiyY6BM_03kS8YPcY_wan-Fus-JzBTbOQVb3H0VtCBAj4n89K0WXMgPbQnv-USigZ6IyZdvORn3mTIEyn8EUy0-mzxXRMIBg
cache-control: no-cache
In the sandbox environment, Yodlee provides a private key and the issuer id (API key). You can find these on your API dashboard page when you are logged in to your Yodlee developer account.
When you move to the live (production) environment, you will need to generate an RSA key pair in the PKCS#8 format, using a key size of 2048 bits. You will provide your RSA public key to Yodlee by uploading it from your API Dashboard page. Keep your RSA private key confidential and safe, and never, ever move it to a mobile device.
You can find sites that generate RSA key pairs by doing a web search for “generate RSA key pair”. One such site, also helpful in testing, is http://travistidwell.com/jsencrypt/demo/. Once you have your key pair, you will use your private key to sign the JWT tokens. Use the “RS512” algorithm to sign your tokens. More information about JWT, in general, is at https://jwt.io/introduction/. More information about creating tokens is lower down this page.
Sandbox API Dashboard
Types of JSON Web Tokens (JWTs)
There are two types of JWTs used in the Yodlee API. Both types of tokens need to be created within your application code and passed to Yodlee via APIs.
- Application Token - Used to access resources that are not specific to a user like the list of providers that Yodlee offers or to create a new user.
- User Token - Used to access resources that are specific to the user like adding and retrieving account/transaction data on behalf of the user. This will be the most common type of token and will be used extensively in your implementation.
Creating an Application JWT
You will need the Issuer Id and Private Key from the API Dashboard. The following example uses node.js. You will need to npm install jsonwebtoken
into your environment.
'use strict';
const path = require('path');
const fs = require('fs');
var jwt = require('jsonwebtoken');
var privateKey = fs.readFileSync("./devSandbox.key","utf8"); //Location of the file with your private key
var payload = {};
var currentTime = Math.floor(Date.now() / 1000);
var signOptions = {
algorithm: "RS512" //Yodlee requires RS512 algorithm when encoding JWT
};
payload.iss = "adf50bf3-8b0f-479d-962d-4031ebadac9a"; // The Issuer Id from the API Dashboard
payload.iat = currentTime; //Epoch time when token is issued in seconds
payload.exp = currentTime + 1800; //Epoch time when token is set to expire. Must be 1800 seconds
var token = jwt.sign(payload, privateKey, signOptions);
console.log("Printing token: "+ token);
The resulting JWT will look like this and will be passed in the Authorization header of the API request.
eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI5OGNjNGE4YS0yZDg5LTRkMDItOTBkYS03MjFlZDBkNGVkYjUiLCJpYXQiOjE1NDU5MzM4NTAsImV4cCI6MTU0NTkzNDc1MH0.HV5H_uwds0snTUxgbFKaB2mvz7j5W4-UBSc7RI7ZfcW7oEluVnr-taZxgU1aU-2xEAeUEtmyKx3DlxmgA8MXEmpgqgr3CzybZF3IvutEULNTmZNIdwxDSBkEh8-mSOL56GLIYLdhbjDqDqfXbF21acIoxQPtJu9j63JjrSIG45aAosFHg-LmbpHpsLscXtTRvZ7spTquV-5hTrE8aaYr1DUYyMult0NhQwLamufeEVACudmWBVR4HRfZTUZFFRLFXqnzE60Tvy8S72XMA6vv-1_s5LJoxfdonIbNvhgHMRwqOodkLkc1cyc8flGeCIR892sCYx4cQldpEdV9bLH_YA
Test Your Application Token via Postman:
- Download the latest version of Postman from https://www.getpostman.com/ and open Postman.
- Select the GET method.
- Enter https://sandbox.api.yodlee.com/ysl/providers in the request URL.
- On the Authorization tab, select the Bearer Token and enter your JWT from the previous step.
- Format:
'Bearer (your-jwt-token)
- Format:
- On the Headers tab, enter the following
Api-Version: 1.1
Content-Type: application/json
- Click Send.
- View the response. You will receive a list of Yodlee supported providers.
Creating a User JWT
The process to create a user JWT is the same as above with the exception that the payload of a user JWT requires a “sub” (subject) parameter. The “sub” parameter will contain the unique id of a user. In the Sandbox environment, Yodlee provides five pre-registered users with test data already available in the “View Test Users” button. After generating a user JWT for Sandbox, you can retrieve account data with the GET /accounts API.
'use strict';
const path = require('path');
const fs = require('fs');
var jwt = require('jsonwebtoken');
var privateKey = fs.readFileSync("./devSandbox.key","utf8");
var payload = {};
var currentTime = Math.floor(Date.now() / 1000);
var signOptions = {
algorithm: "RS512"
};
payload.iss = "adf50bf3-8b0f-479d-962d-4031ebadac9a";
payload.iat = currentTime;
payload.exp = currentTime + 1800;
payload.sub = "sbMem5c3418773ef071";
var token = jwt.sign(payload, privateKey, signOptions);
console.log("Printing token: "+ token);
Test Your User JWT via Postman:
- Download the latest version of Postman from https://www.getpostman.com/ and open Postman.
- Select the GET method.
- Enter https://sandbox.api.yodlee.com/ysl/accounts in the request URL.
- On the Authorization tab, select the Bearer Token and enter your JWT from the previous step.
- Format:
'Bearer (your-jwt-token)
- Format:
- On the Headers tab, enter the following
Api-Version: 1.1
Content-Type: application/json
- Click Send.
- View the response. You will receive a list of accounts associated with the user.
Yodlee Environments
Yodlee provides the following environments to registered developers. If not already registered, please go here to create a developer account.
- Sandbox – available to all registered developers for access to the APIs using preconfigured test users and test data only.
- Development – available to registered developers with a 90-day free trial via the Launch plan. Continued access is available via the Grow plan for a small monthly fee. This is a live environment with access to all supported sites for up to 100 activities using aggregation and account verification.
- Production – available to registered developers with a 90-day free trial via the Launch plan. Continued access is available via the Grow plan for a small monthly fee. This a live environment with access to all supported sites for up to 100 activities using aggregation and account verification. Server-to-server integration with the Yodlee API production environment requires whitelisting your server IP address.
Development and production environment access are both granted at the time when the Launch plan is approved. For more information about available pricing plans, please go to https://developer.yodlee.com/pricing.
Sandbox Environment
The sandbox environment is available by default as you register at the Developer Portal. In the sandbox, Yodlee provides a preconfigured issuer id with an RSA Private Key. A JSON web token can be created using the default RSA Private Key and issuer id.
Sandbox users registered before January 7, 2019
If you registered for the sandbox before January 7, 2019, you are using our deprecated cobrand and user credential-based authentication mechanism. Learn more about how to use cobrand and user credential based authentication.
Create a Generic Token for Sandbox
A generic token will give you access to resources that do not require user context.
The header of the JWT will contain the algorithm and token type. Yodlee requires an RS512 algorithm. Please refer to https://tools.ietf.org/html/rfc7519 for information.
{
"alg": "RS512",
"typ": "JWT"
}
The payload of the JWT will contain the following fields:
{
"iss": "98cc4a8a-2d89-4d02-90da-721ed0d4edb5",
"iat": 1545932950,
"exp": 1545934750
}
- iss = Issuer Id
- iat = The epoch time the token is issued.
- exp = The epoch time the token expires. You should set it to 30 minutes or 1800 seconds from iat.
The Header and Payload will be signed using your private key. The resulting token will look like this:
eyJhbGciOiJSUzUxMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI5OGNjNGE4YS0yZDg5LTRkMDItOTBkYS03MjFlZDBkNGVkYjUiLCJpYXQiOjE1NDU5MzM4NTAsImV4cCI6MTU0NTkzNDc1MH0.HV5H_uwds0snTUxgbFKaB2mvz7j5W4-UBSc7RI7ZfcW7oEluVnr-taZxgU1aU-2xEAeUEtmyKx3DlxmgA8MXEmpgqgr3CzybZF3IvutEULNTmZNIdwxDSBkEh8-mSOL56GLIYLdhbjDqDqfXbF21acIoxQPtJu9j63JjrSIG45aAosFHg-LmbpHpsLscXtTRvZ7spTquV-5hTrE8aaYr1DUYyMult0NhQwLamufeEVACudmWBVR4HRfZTUZFFRLFXqnzE60Tvy8S72XMA6vv-1_s5LJoxfdonIbNvhgHMRwqOodkLkc1cyc8flGeCIR892sCYx4cQldpEdV9bLH_YA
This application token is needed to access a list of providers, to create a new user in the Yodlee system, and other non-user specific APIs. For user-specific activities, you will need to create a user-specific token.
Create a User-specific Token
In the sandbox, Yodlee provides 5 test users for testing purposes. Clicking View Test Data will display the loginName for the test users.
A user-specific token is created by modifying the payload and including a "sub" parameter. Please use one of the provided test users to create the token.
The payload of the user-specific token will contain the following fields:
{
"iss":"a24a0851-fafe-48a4-a108-17a48cf4b459",
"iat":1545426441,
"exp":1545428241,
"sub":"sbMem5c758c82bb1d12"
}
- iss = Issuer Id
- iat = The epoch time when the token is issued.
- exp = The epoch time when the token expires. You should set it to 30 minutes or 1800 seconds from iat.
- sub = The unique loginName used to register the user.
This token will give you access to user-specific resources like get accounts, get transactions, etc. You can also invoke FastLink using this token.
Development Environment
Please request development environment access from the API Dashboard of your Yodlee developer account. Once development access has been granted, you will be able to manage your Issuer Id from the API Dashboard.
RSA Private and Public Keys
Generate an RSA Private and Public key pair in an unencrypted 2048 bit PKCS#8 encoded format and store your keys in a safe place.
Generate Issuer Id
To generate your Issuer Id, upload your RSA Public Key to the Yodlee servers via the Manage Auth Keys on the API Dashboard. It will take about 2-3 minutes for your Issuer Id to be generated. Refresh the page and your Issuer Id will be displayed next to your uploaded Public Key.
Now you can generate the new token using these new keys.
Create a User in the Yodlee Platform:
- Open Postman.
- Select the POST method.
- Enter https://development.api.yodlee.com/ysl/user/register in the request URL.
- On the Authorization tab, select the Bearer Token and enter your JWT from the previous step.
- Use a generic token and not the user-specific token
- Format:
'Bearer (your-jwt-token)
- On the Headers tab, enter the following
Api-Version: 1.1
Content-Type: application/json
- On the Body tab, select Raw and JSON(application/json)
- Enter the following JSON in the space provided. Only loginName and email are required fields. The loginName must be unique and email can be a dummy value.
{ "user":{ "loginName":"<Your unique ID for a user>", "email":"abc@abc.com", "name":{ "first":"firstname", "last":"lastname" }, "address":{ "address1":"address1", "state":"state", "city":"city", "zip":"zipcode", "country":"USA" }, "preferences":{ "currency":"USD", "timeZone":"PST", "dateFormat":"MM/dd/yyyy", "locale":"en_US" } } }
- Click Send.
- You will have the same user object returned in the response indicating the user is registered.
Create a User-specific Token
A user-specific token is created by modifying the payload and including a sub-parameter.
The payload of the user-specific token will contain the following fields:
{
"iss":"a24a0851-fafe-48a4-a108-17a48cf4b459",
"iat":1545426407383,
"exp":1545426443383,
"sub":" <your unique ID for a user>"
}
Once you have a user-specific token, you can access additional resources like Yodlee FastLink and other APIs that are user-specific.
Link an Account Using FastLink
FastLink is a responsive application that helps end-users link their accounts to your application. It facilitates linking user accounts and offers intuitive searches for financial institutions, credentials management, multifactor authentication implementation, and error handling. It can also be white-labeled to suit your business needs. By using FastLink you can avoid creating complex user flows of ever-changing login mechanism of different financial institutions. Once FastLink is launched, the application remains active for 120 minutes and in case of inactivity for 30 minutes.
FastLink for Web
To use FastLink copy and paste the following code in the html of your application. Create a user-specific token and launch FastLink by calling the fastlink.open()
API from your application.
<script type='text/javascript' src='https://cdn.yodlee.com/fastlink/v1/initialize.js'></script>
<body>
...
<div id="container-fastlink">
<div style="text-align: center;">
<input type="submit" id="btn-fastlink" value="Link an Account">
</div>
</div>
...
<script>
(function (window) {
//Open FastLink
var fastlinkBtn = document.getElementById('btn-fastlink');
fastlinkBtn.addEventListener('click', function () {
window.fastlink.open({
fastLinkURL: '<fastlink-launch-url>',
jwtToken: 'Bearer <your-jwt-token>',
params: '<optParams>',
onSuccess: function (data) {
console.log(data);
},
onError: function (data) {
console.log(data);
},
onExit: function (data) {
console.log(data);
},
onEvent: function (data) {
console.log(data);
}
}, 'container-fastlink');
}, false);
}(window));
</script>
</body>
The fastlink.open()
API needs the following parameters:
Parameter Name | Description |
---|---|
fastLinkURL |
The FastLink application URL. |
jwtToken |
The user-specific JSON Web Token (JWT) generated by following the instructions provided in here. |
params (optional) |
The extra parameters to configure the FastLink account aggregation or the verification flow in the application. For details refer to Advanced Integration using FastLink. |
Callback |
The FastLink application will invoke either of the following callback functions to update its status back to host application:
|
Close FastLink
Close the FastLink application by calling the close()
method:
fastlink.close();
For more things you can do with FastLink, look at advanced FastLink integration.
Link Accounts via API
If you prefer to build your own UI, we have APIs that you can use. This also mean you implement your own credentials management, multifactor authentication, and error handing, etc for all the financial institutions. Please see APIs to link an account.
Next: Retrieve Account Details, webhooks, testing and IP white-listing