Using JSON Web Tokens

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:

1. Download the latest version of Postman from https://www.getpostman.com/ and open Postman.
2. Select the GET method.
3. Enter https://sandbox.api.yodlee.com/ysl/providers in the request URL.
4. On the Authorization tab, select the Bearer Token and enter your JWT from the previous step.
   • Format: 'Bearer (your-jwt-token)
5. On the Headers tab, enter the following
   • Api-Version: 1.1
   • Content-Type: application/json
6. Click Send.
7. 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:

1. Download the latest version of Postman from https://www.getpostman.com/ and open Postman.
2. Select the GET method.
3. Enter https://sandbox.api.yodlee.com/ysl/accounts in the request URL.
4. On the Authorization tab, select the Bearer Token and enter your JWT from the previous step.
   • Format: 'Bearer (your-jwt-token)
5. On the Headers tab, enter the following
   • Api-Version: 1.1
   • Content-Type: application/json
6. Click Send.
7. 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:

1. Open Postman.
2. Select the POST method.
3. Enter https://development.api.yodlee.com/ysl/user/register in the request URL.
4. 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)
5. On the Headers tab, enter the following
   • Api-Version: 1.1
   • Content-Type: application/json
6. On the Body tab, select Raw and JSON(application/json)
7. 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":"",
         "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"
         }
      }
   }

8. Click Send.
9. 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":" "
}

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.

...

...

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: onSuccess - The onSuccess method is invoked when an account is successfully aggregated or verified along with its basic information. For more details, refer to the Post Messages section. onError - The onError method is invoked to report errors or failures encountered while aggregating or verifying accounts. For more details, refer to the Post Messages section. onExit - The onExit method is called to report when the FastLink application is closed by user-initiated actions. onEvent - The onEvent method is called to notify intermittent status messages to the 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