bhanditz / starling-api-web-starter-kit

Starter kit and example app for using the Starling API.

Starling Developers
Web Starter Kit

This project contains a sample web application that integrates with the Starling Bank API to retrieve a customer's transaction history. The React Redux application is based on this starter kit and is comprised of a simple REST API written in javascript using node.js with express. The

Looking for the Mobile Starter Kit instead?

Getting Started

Please also take a look at the higher-level Getting Started Guide on our site, which covers usage of our API as a whole.

Prerequisites

The only prerequisite is Node.js. The best way to install Node.js is with nvm.

Installation

From the root of the project, install dependencies as follows. Use either the yarn or npm package manager.

yarn install

Start the application

yarn start

This will serve the client application on localhost:3000 when using the default configuration.

Configuration

You must register an application on the Starling Developers site to obtain a client_id and client_secret. The client_id and client_secret should then be configured in the server/config.json file. The redirect URL registered in the developer portal must match the configured URL in this application.

The config.json file will look like this

{
  "clientId": "<application client id>",
  "clientSecret": "<application client secret>",

  "cookieSecret": "21e361d0-ff2c-4763-a084-1032f2103ce8",

  "productionApi": "https://api.starlingbank.com",
  "personalAccessToken": "<personal access token>",

  "SANDBOX_CONFIG_COMMENT": "Do not keep the store file in the app root dir or it will restart everytime it is written to!",
  "sandboxLocalTokenStore": "../starling-api-web-starter-kit-sandbox-token-store.json",
  "sandboxApi": "https://api-sandbox.starlingbank.com/",
  "sandboxAccessToken": "<sandbox access token from Starling Developers site>",
  "refreshToken": "<refresh token from Starling Developers site>",

  "oauthApi": "https://oauth.starlingbank.com",
  "oauthRedirectUri": "http://localhost:3000/api/oauth/redirect"
}

The missing bits of config are specific to your account - your application, your sandbox customer, your personal access.

You can fill in this config as suits your use-case, be it personal access, sandbox, or oauth/production.

OAuth/Production

Simply replace <application client id> and <application client secret> with the client_id and client_secret for your application.

{
  "clientId": "<application client id>",
  "clientSecret": "<application client secret>",
  
  "cookieSecret": "21e361d0-ff2c-4763-a084-1032f2103ce8",
  
  "productionApi": "https://api.starlingbank.com",
  
  "oauthApi": "https://oauth.starlingbank.com",
  "oauthRedirectUri": "http://localhost:3000/api/oauth/redirect"
}

Sandbox

For the sandbox environment setup, use the config file, config.json, correctly filling in the following fields:

{
  "clientId": "<application client id>",
  "clientSecret": "<application client secret>",
  
  "cookieSecret": "21e361d0-ff2c-4763-a084-1032f2103ce8",
 
  "SANDBOX_CONFIG_COMMENT": "Do not keep the store file in the app root dir or it will restart everytime it is written to!",
  "sandboxLocalTokenStore": "../starling-api-web-starter-kit-sandbox-token-store.json",
  "sandboxApi": "https://api-sandbox.starlingbank.com/",
  
  "sandboxAccessToken": "<sandbox access token from Starling Developers site>",
  "refreshToken": "<refresh token from Starling Developers site>"
}

Where the sandboxAccessToken and refreshToken are the sandbox customer's access and refresh tokens from the sandbox environment.

You can then start then select the sandbox from the landing page of your application.

Note: the current implementation uses LokiJS for in-memory storage of access and refesh tokens so the server can be restarted without having to replace the tokens in the `config.json`. This is temporary, as a programmatic method for retrieval of an application's sandbox customers is in the works.

Personal Access

This starter kit can also be used to access your own Starling Bank data, right out of the box. This can be achieved by entering your token into the config.json file under personalAccessToken.

{
  "cookieSecret": "21e361d0-ff2c-4763-a084-1032f2103ce8",
  "productionApi": "https://api.starlingbank.com",
  "personalAccessToken": "<personal access token>"
}

Your personal access token can be obtained from your developer account after linking it to your customer account.

Mobile Starter Kit Users

Those using the React Native mobile starter kit need to also clone this repo and follow the installation instructions above, while replacing the contents of the config.json file with that given in the mobile starter kit README.md