Financial Services – Financial API - Part 1: Read Only API Security Profile


This document is not an OIDF International Standard. It is distributed for review and comment. It is subject to change without notice and may not be referred to as an International Standard.

Recipients of this draft are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.

The OpenID Foundation (OIDF) grants to any Contributor, developer, implementer, or other interested party a non-exclusive, royalty free, worldwide copyright license to reproduce, prepare derivative works from, distribute, perform and display, this Implementers Draft or Final Specification solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts and Final Specifications based on such documents, provided that attribution be made to the OIDF as the source of the material, but that such attribution does not indicate an endorsement by the OIDF.

The technology described in this specification was made available from contributions from various sources, including members of the OpenID Foundation and others. Although the OpenID Foundation has taken steps to help ensure that the technology is available for distribution, it takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this specification or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any independent effort to identify any such rights. The OpenID Foundation and the contributors to this specification make no (and hereby expressly disclaim any) warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to this specification, and the entire risk as to implementing this specification is assumed by the implementer. The OpenID Intellectual Property Rights policy requires contributors to offer a patent promise not to assert certain patent claims against other contributors and against implementers. The OpenID Foundation invites any interested party to bring to its attention any copyrights, patents, patent applications, or other proprietary rights that may cover technology that may be required to practice this specification.


OIDF (OpenID Foundation) is an international standardizing body comprised by over 160 participating entities (work group participants). The work of preparing international standards is carried out through OIDF work groups according to OpenID Process. Each participants interested in a subject for which a work group has been established has the right to be represented on that work group. International organizations, governmental and non-governmental, in liaison with OIDF, also take part in the work. OIDF collaborates closely with other standardizing bodies in the related fields.

OpenID Foundation standards are drafted in accordance with the rules given in the OpenID Process.

The main task of work group is to prepare Implementers Draft and Final Draft. Final Draft adopted by the Work Group through consensus are circulated publicly for the public review for 60 days and for the OIDF members for voting. Publication as an OIDF Standard requires approval by at least 50 % of the members casting a vote.

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. OIDF shall not be held responsible for identifying any or all such patent rights.

Financial API - Part 1: Read Only API Security Profile was prepared by OpenID Foundation Financial API Work Group.

Financial API consists of the following parts, under the general title Financial Services — Financial API:

This part is intended to be used with RFC6749, RFC6750, [RFC6736], and OIDC.


In many cases, Fintech services such as aggregation services uses screen scraping and stores user passwords. This model is both brittle and insecure. To cope with the brittleness, it should utilize an API model with structured data and to cope with insecurity, it should utilize a token model such as OAuth [RFC6749, RFC6750].

This working group aims to rectify the situation by developing a REST/JSON model protected by OAuth. Specifically, the FAPI WG aims to provide JSON data schemas, security and privacy recommendations and protocols to:

Both commercial and investment banking accounts as well as insurance, and credit card accounts are to be considered.

Financial Services – Financial API - Part 1: Read Only API Security Profile

1. Scope

This document specifies the method of

This document is applicable to both commercial and investment banking accounts as well as insurance, and credit card accounts are to be considered.

2. Normative references

The following referenced documents are indispensable for the application of this document. For dated references, only the edition cited applied. For undated references, the latest edition of the referenced document (including any amendments) applies.

RFC2616 - Hypertext Transfer Protocol -- HTTP/1.1

RFC4122 A Universally Unique IDentifier (UUID) URN Namespace

RFC6749 - The OAuth 2.0 Authorization Framework

RFC6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage

RFC7636 - Proof Key for Code Exchange by OAuth Public Clients

RFC5246 - The Transport Layer Security (TLS) Protocol Version 1.2

RFC7525 - Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)

RFC6125 - Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS)

O2fNA - OAuth 2.0 for Native Apps

RFC6819 - OAuth 2.0 Threat Model and Security Considerations

OIDC - OpenID Connect Core 1.0 incorporating errata set 1

OIDD - OpenID Connect Discovery 1.0 incorporating errata set 1

OIDM - OAuth 2.0 Multiple Response Type Encoding Practices

X.1254 - Entity authentication assurance framework

TLSM - Mutual X.509 Transport Layer Security (TLS) Authentication for OAuth Clients

3. Terms and definitions

For the purpose of this standard, the terms defined in RFC6749, RFC6750, RFC7636, OpenID Connect Core apply.

4. Symbols and Abbreviated terms

API – Application Programming Interface

CSRF - Cross Site Request Forgery

FAPI - Financial API

FI – Financial Institution

HTTP – Hyper Text Transfer Protocol

REST – Representational State Transfer

TLS – Transport Layer Security

5. Read Only API Security Profile

5.1 Introduction

The OIDF Financial API (FAPI) is a REST API that provides JSON data representing accounts and transactions related data. These APIs are protected by the OAuth 2.0 Authorization Framework that consists of RFC6749, RFC6750, RFC7636, and other specifications.

These API accesses have several levels of risks associated to them. Read only access is generally speaking associated with lower financial risk than the write access. As such, the characteristics required to the tokens are also different.

In the following subclauses, the method to obtain tokens are explained separately.

5.2 Read Only API Security Provisions

5.2.1 Introduction

Read Only Access typically is the lower risk scenario compared to the Write access, so the protection level can also be lower. However, since the FAPI would provide potentially sensitive information, it requires more protection level than a basic RFC6749 requires.

As a profile of The OAuth 2.0 Authorization Framework, this document mandates the following to the Read Only API of the FAPI.

5.2.2 Authorization Server

The Authorization Server

Further, if it wishes to provide the authenticated user's identifier to the client in the token response, the authorization server

5.2.3 Public Client

A Public Client

Further, if it wishes to obtain a persistent identifier of the authenticated user, it

5.2.4 Confidential Client

In addition to the provision to the Public Client, the Confidential Client

6. Accessing Protected Resources

6.1 Introduction

The FAPI endpoints are OAuth 2.0 protected resource endpoints that return financial information for the resource owner associated with the submitted access token.

6.2 Read only access provisions

6.2.1 Protected resources provisions

The resource server with the FAPI endpoints

Further, it

6.2.2 Client provisions

The client supporting this document

Further, the client

7. Security Considerations

7.1 TLS Considerations

Since confidential information is being exchanged, all interactions shall be encrypted with TLS/SSL (HTTPS) in accordance with the recommendations in RFC7525. TLS version 1.2 or later shall be used for all communications.

7.2 Message source authentication failure

Authorization request and response are not authenticated. For a higher risk scenarios, it should be taken care of. See Part 2, which uses request object to achieve the message source authentication.

7.3 Message integrity protection failure

Authorization request is not message integrity protected thus request tampering and parameter injection are possible. Where the protection is desired, it should use Part 2.

The response is integrity protected when ID Token is returned from the authorization endpoint.

7.4 Message containment failure

7.4.1 Authorization request and response

In this document, the authorization request is not encrypted. Thus, it is possible to leak the information contained if the browser was infected with virus, etc.

Authorization response can be encrypted as ID Token can be encrypted.

It is possible to leak the information through the logs if the parameters were recorded in the logs and the access to the logs are compromised. Strict access control to the logs in such cases should be enforced.

7.4.2 Token request and response

It is possible to leak the information through the logs if the parameters were recorded in the logs and the access to the logs are compromised. Strict access control to the logs in such cases should be enforced.

7.4.3 Resource request and response

Care should be taken so that the sensitive data will not be leaked through the referrer.

If the access token is a bearer token, it is possible to exercise the stolen token. Since the access token can be used against multiple URIs, the risk of it leaking is much larger than the refresh token, which is used only against the token endpoint. Thus, the lifetime of the access token should be much shorter than that of the refresh token. Refer to section 16.18 of OIDC for more discussion on the lifetimes of access tokens and refresh tokens.

8. Privacy Considerations

8.1 Privacy by design

8.2 Adhering to privacy principles

Stakeholders should follow the privacy principles of ISO/IEC 29100. In particular:

  1. Consent and Choice
  2. Purpose legitimacy and specification
  3. Collection limitation
  4. Data (access) limitation
  5. Use, retention, and data disclosure limitation:
    1. Use limitation:
    2. Retention limitation: Where the data is no longer being used, clients should delete such data from their system within 180 days except for the cases it needs to retain due to the legal restrictions;
    3. Data disclosure limitation:
  6. Accuracy and quality
  7. Openness, transparency and notice
  8. Individual participation and access
  9. Accountability
  10. Information security
  11. Privacy compliance

9. Acknowledgement

Following people contributed heavily towards this document.

10. Bibliography