Overview of Developer Portal

Developer Portal Services

The purpose of the Developer Portal is to help developers of client applications understand the APIs supplied by the YBS Group and to support them in building applications that use these APIs. To that end, the Developer Portal provides the following services:

Category

Service

Description

Operational

Registration

You will need to register to access protected services such as the API Sandbox and to manage your applications accessing these APIs.

Manage Client Applications

You can create any number of Client Applications that consume our APIs. Each of your Client Applications will be bound to a set of API Products that you can select when creating these applications.   These applications may be developed by different delivery teams and also used to test multiple versions of our APIs.

API Access

Upon successful registration of your Client Applications, you will receive a Consumer Key and Consumer Secret – collectively known to as Client Application Credentials – for the respective application to “consume” the selected set of API Products.

Note that all data returned from the Sandbox API are stubbed with the exception of OAuth tokens such as authorisation codes and access tokens. These are real or ‘live’ tokens that are fully compliant with the OAuth specification.

Support

API Documentation

You will find detailed technical specifications of our APIs in this section. Additionally, if you are logged in, you will be able to send test requests to the API Sandbox directly from the API documentation pages.

Developer Support

Beyond API Documentation, the Developer Portal also provides additional information to get you started on your development journey in the form of an overview of our API flows and FAQs. Should you have any suggestions or further queries, you can reach us using the Contact Us page.

Overview of YBS APIs

Our initial set of APIs is focused on PSD2 regulatory compliance. To that end, we have adopted the UK Open Banking specifications in our first Sandbox release, to enable account information access based on the Account Information Service Provider (AISP) v1.0.0 specification. For more information about future releases and alignment with UK Open Banking, please refer to the FAQ section.

More generally, our APIs are based on industry standards to improve interoperability. A key aspect of these standards is the adoption of the open authorisation model based on the OAuth 2.0 Authorisation Framework in addition to adherence to the OWASP REST API guidelines. The use of the OAuth Authorisation Code grant type ensures that the end-user’s YBS authentication credentials are never shared with a third party and are supplied only to YBS systems.

2. API Development Journey

Getting started is easy:

  1. Register as Developer – We will ask you for some basic information, after which you will need to activate your account using a link we will include in a confirmation email.

  2. Add a Client Application – After you have registered and logged in, you will be able to add Client Applications to access our APIs.

  3. Access our Sandbox APIs – We have intentionally kept our Sandbox APIs almost identical to those in production to ensure that the applications you have developed against our Sandbox will require minimal changes, if any, when releasing these ‘live’. We will call out any deviations from our production flows in our description below.

Register as Developer and Add Client Application

The diagram above shows the steps to get you and your applications registered, so that you can start building applications using the Sandbox APIs.

Access our Sandbox APIs

The Sandbox API flow above is based on the Account Information Service Provider (AISP) v1.0.0 specification defined by UK Open Banking, and represents a prototypical flow for all account information access. Both the Identity API and Account API are identical to our production APIs albeit using stubbed data (described below) and are subject to the same validation rules. The Sandbox OAuth Authorisation Server Endpoint, highlighted above, is the only exception and is used solely in the context of the Sandbox. Its purpose is to stand in for the Authorisation Server, typically a website that a human-user would interact with to authenticate and authorise the access request.

In the Sandbox, the Endpoint will respond with an Authorisation Code when supplied with valid input parameters. That is, authorisation is implicit and guaranteed for all valid input. This enables you to fully automate the end-to-end flow without the need for managing additional credentials to authenticate or additional human intervention to manually authorise the access request. That said, the redirection query parameters in Step 3 are identical to those that you are expected to supply in the production OAuth redirection and are subject to the same validation rules here.

There are only three functional deviations from production in the Sandbox.

Step

Deviation from Production

Rationale and Value

Create Account Request (Step 2)

The request payload will be validated but the Sandbox will not use any of the values in the request for subsequent data access operations.

Furthermore, the response for valid input parameters is hard-coded to always return a fixed Account Request Identifier(also known as IntentID). However, you can use any valid Account Request Identifier from the Stubbed Dataset in the following step to authorise the request (Step 3).

The Sandbox does not maintain any state across calls and uses stubbed data solely. That said, this step will enable you to validate the request payload you have supplied to ensure it is compliant with the AISP specification.

Authorise AISP Request (Step 3)

Unlike production, this is not a website that a human-user would typically authenticate and manually authorise the access request. This is an HTTP endpoint that always responds with an Authorisation Code when supplied with valid input parameters.

This enables you to fully automate the end-to-end flow without the need for managing additional credentials to authenticate on the Authorisation Server or additional human intervention to manually authorise the access request.

Identity API and Account API (Steps 1, 2, 4, 5)

Only one-way TLS authorisation is supported which deviates from the Open Banking requirement to implement two-way (mutual) TLS authorisation.

Obviates the need for you, the developer, to obtain certificates issued by a Certificate Authority to use the Sandbox.

3. Sandbox Stubbed Dataset

The stubbed dataset is relevant primarily from Step 3 onwards in the Sandbox API flow above wherein a valid Pseudo Account Request Identifier is expected in addition to the standard OAuth parameters such as Client ID (also called Consumer ID). The specified Pseudo Account Request Identifier enables you to obtain an Authorisation Code to subsequently access the account information associated with the pseudo (stubbed) identifier as if the respective customer authorised the access request. All other supplied Account Request Identifiers are deemed invalid. Since the dataset is mocked, the permissions requested in Step 2 are ignored – only those in the dataset below apply. Consequently, you will receive the same response even if the requested AISP data was originally setup using a different set of permissions in Step 2. 

#

Customer Name

Building Society

Pseudo Account Request Id/IntentID

Account Access Permissions

Account Data

1

George Smith

Yorkshire

1001

  1. Read Account Basic

  2. Read Balance

Account 1

  1. Type: Savings
  2. Account #: 0000100101
  3. Balance: £110.00
  4. Nickname: “George’s savings 1”

Account 2

  1. Type: Savings
  2. Account #: 0000100102
  3. Balance: £150.00
  4. Nickname: “George’s savings 2”

Account 3

  1. Type: Savings
  2. Account #: 0000100103
  3. Balance: £190.00
  4. Nickname: “George’s savings 3”

2

Jane Williams

Chelsea

2001

  1. Read Account Detail

  2. Read Balance

Account 1

  1. Type: Savings
  2. Account #: 0000200101
  3. Balance: £225.00
  4. Nickname: “Jane’s savings 1”

 

Account 2

  1. Type: Savings
  2. Account #: 0000200102
  3. Balance: £275.00
  4. Nickname: “Jane’s savings 2”

3

Jack Hopkins

Yorkshire

3001

  1. Read Account Detail (only)

 

Account 1

  1. Type: Savings
  2. Account #: 0000300101
  3. Balance: £300.00 (note permissions)
  4. Nickname: “Jack’s savings 1”

4

Lucy Abbott

(deceased)

Chelsea

4001

  1. Read Account Detail (only)

Account 1 (note customer deceased)

  1. Type: Savings
  2. Account #: 0000400101
  3. Balance: £400.00
  4. Nickname: “Lucy’s savings 1”

4. Client Application Testing using Sandbox

The Sandbox and the associated stubbed dataset enable you to test your Client Application as follows.

#

Sandbox API Flow Step

Validation

1

Step 1 – Authenticate Client App using Identity API

Client Application Credentials (Consumer ID, Consumer Secret) assigned to your application. Set Cache-Control header in request of API call as "no-cache".

Response Example:{
  "access_token": "VNwnpWbz5wwCyY3gbmHa4ksqzN9y",
  "expires_in": "1799",
  "scope": "accounts",
  "token_type": "Bearer"
}

2

Step 2 – Create Account Request using Account API

  1. The OAuth App Access Token returned in Step 1 (valid and unexpired).
  2. Request payload against the AISP schema (mandatory fields, data types, enumerated values).
  3. Financial Identifier must match either Yorkshire or Chelsea.

Invoke CreateAccountRequest resouce to get Account Request Id.

Response Example:{
  "Data": {
    "AccountRequestId": "1001",
    "CreationDateTime": "2017-12-07T10:42:16.000+00:00",
    "ExpirationDateTime": "2018-03-07T10:42:16.000+00:00",
    "Permissions": [
      "ReadBalances",
      "ReadAccountsBasic"
    ],
    "Status": "AwaitingAuthorisation",
    "TransactionFromDateTime": "2012-05-08T00:00:00.000Z",
    "TransactionToDateTime": "2025-05-08T00:00:00.000Z"
  },
  "Links": {
    "Self": "/account-requests/1001"
  },
  "Meta": {
    "TotalPages": 1
  },
  "Risk": {}
}

3

Step 3 – Authorise AISP Request using Authorisation API

  1. Pseudo Account Request Identifier as per stubbed dataset.
  2. OAuth redirection parameters: Response Type, Client ID, Redirect URI, Scope, State. Note:The response will be a 302 redirect to the Callback URL provided during the App registration process.

Response Example:

HTTP/1.1 302 Found
Accept:application/json
Content-Type:application/json
Date:Tue, 24 Apr 2018 12:51:57 GMT
Location:http://tppapp-dev.com?code=MXPSd8uF

4

Step 4 – Exchange Auth Code for Access Token using Identity API

  1. Client Application Credentials.
  2. The Authorisation Code returned in Step 3.

Response Example:

{
  "access_token": "LirHRX3Pc7Zo9ZGd0uASLh2qj7V6",
  "expires_in": "863943",
  "token_type": "Bearer",
  "scope": "accounts"
}

5

Step 5 – Access AISP Data using Accounts API

  1. The Customer Access Token returned in Step 4 (valid and unexpired).
  2. Financial Identifier must match the building society for the stubbed dataset record.
  3. The operation must match the permissions in the stubbed dataset record.
  4. The level of detail in the response payload (Basic vs. Detail) must match that in the stubbed dataset record.
  5. Account Identifier for Get Account Information (single) and Get Account Balance (single). Note that the Account Identifier is obfuscated and must match the account identifiers returned in Get Account Information (bulk).

More generally:

  1. George Smith: Typical authorisation record with Read Account Basic permission for Yorkshire Building Society with three accounts authorised.
  2. Jane Williams: Typical authorisation record with Read Account Detail permission for Chelsea Building Society with two accounts authorised.
  3. Jack Hopkins: Atypical authorisation record with Read Account Detail permission for Yorkshire Building Society but without any Read Account Balance permission. Your Client Application can retrieve only account list. All other AISP data operations will return errors.
  4. Lucy Abbott: Authorisation record with Main Account Holder status marked Deceased after granting the access authorisation. This will result in errors being returned for all AISP data operations regardless of the permissions authorised.

Invoke GetAccounts resouce to get list of accounts,GetAccount resource to get details of an account and GetAccountBalances resource to get balances for an account.

Response Example:

{
  "Data": {
    "Account": [
      {
        "AccountId": "4OC9IiksOaT5SPR/3Ym7Cw==",
        "Currency": "GBP",
        "Nickname": "George’s savings 1"
      },
      {
        "AccountId": "3io98FhdMjc1Yv+UMD6ToA==",
        "Currency": "GBP",
        "Nickname": "George’s savings 2"
      },
      {
        "AccountId": "vtgaNkuf7+eF/GAi9HXyqA==",
        "Currency": "GBP",
        "Nickname": "George’s savings 3"
      }
    ]
  },
  "Links": {
    "Self": "/accounts"
  },
  "Meta": {
    "total-pages": 1
  }
}

All Sandbox APIs are subject to throttling limits that apply across all users of the Sandbox. This is necessary to help us provide a better Sandbox service for all developers. You will receive the HTTP error code 429 Too Many Requests in the event this is breached.

5. Glossary

Term / Acronym

Definition

Access Token

This is an OAuth token that, upon presentment, encapsulates the security identity of a subject (application or human) and provides access to protected resources.

Account API

The YBS API that implements the Open Banking AISP specification.

Account Request Identifier(or IntentID)

An Open Banking specific identifier used in the AISP specification to uniquely identify the account access request.

Authorisation Code

This is an OAuth token that is returned from an authorisation server as an intermediary token between the client application and the resource owner (typically an end-user). It encapsulates the authorisation by the resource owner to access protected resources by a client application.

Authorisation Server

The server that issues authorisation code (at the Authorisation Endpoint) and access tokens (at the Token Endpoint) after successfully authenticating the resource owner and obtaining authorisation.

Client Application (or Application)

An application making protected resource requests on behalf of the resource owner.

Client ID

See Consumer ID

Client Secret

See Consumer Secret

Consumer ID

A string that uniquely identifies the Client Application.Also known as: Client ID, API Key

Consumer Secret

A unique string that accompanies the Consumer ID to authenticate the Client Application, typically when obtaining Access Tokens at the Token Endpoint.Also known as: Client Secret

Developer Portal (API)

An interactive website that helps developers of client applications understand the API design and supports them in building applications that use these APIs.

Identity API

The YBS API provides the OAuth Token endpoint for obtaining OAuth access tokens.

JSON

“JavaScript Object Notation or JSON is an open-standard file format that uses human-readable text to transmit data objects consisting of attribute–value pairs and array data types (or any other serializable value). It is a very common data format used for asynchronous browser–server communication.” (Wikipedia)

OAuth

An open standard for delegated authorisation that provides client applications a "secure delegated access" to protected server resources on behalf of a resource owner. https://tools.ietf.org/html/rfc6749

Open Banking (UK)

“The Open Banking Implementation Entity was created by the UK’s Competition and Markets Authority to create software standards and industry guidelines that drive competition and innovation in UK retail banking.” (openbanking.org.uk)

OWASP

Open Web Application Security Project (OWASP) is a worldwide not-for-profit charitable organization focused on improving the security of software.

Sandbox API

An environment that testers can use to mimic the characteristics of the production API and create simulated responses from all APIs the application relies on.