fapi-2-implementation-advice October 2026
Tonge Standards Track [Page]
Workgroup:
fapi
Published:
Author:
D. Tonge
Moneyhub Financial Technology

FAPI 2.0 Implementation Advice

Abstract

Financial-grade API (FAPI) 2.0 Implementation Advice is a document to provide practical guidance on the implementation and usage of the FAPI 2.0 family of standards.

Foreword

The OpenID Foundation (OIDF) promotes, protects and nurtures the OpenID community and technologies. As a non-profit international standardizing body, it is comprised by over 160 participating entities (workgroup participant). The work of preparing implementer drafts and final international standards is carried out through OIDF workgroups in accordance with the OpenID Process. Participants interested in a subject for which a workgroup has been established have the right to be represented in that workgroup. 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.

Final drafts adopted by the Workgroup 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. There is a possibility that some of the elements of this document may be subject to patent rights. OIDF shall not be held responsible for identifying any or all such patent rights.

Introduction

The Financial-grade API (FAPI) 2.0 family of standards provides security profiles and specifications to enable implementers to deploy highly secure, interoperable APIs. While we have attempted to minimize the optionality in FAPI 2.0, there are still many decisions that need to be made by implementers. This document aims to provide advice for implementers based on the experience of members of the OpenID Foundation's FAPI Working Group.

Warning

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.

Notational Conventions

The keywords "shall", "shall not", "should", "should not", "may", and "can" in this document are to be interpreted as described in ISO Directive Part 2 [ISODIR2]. These keywords are not used as dictionary terms such that any occurrence of them shall be interpreted as keywords and are not to be interpreted with their natural language meanings.

▲

Table of Contents

1. Implementation Advice

1.1. FAPI 2.0 Framework

The FAPI 2.0 Framework is comprised of several documents. At the time of writing, they are:

  • FAPI 2.0 Attacker Model [attackermodel];
  • FAPI 2.0 Security Profile [FAPI2_Security_Profile];
  • FAPI 2.0 Message Signing [FAPIMessageSigning] - for non repudiation of messages;
  • FAPI Client Initiated Backchannel Authentication - for decoupled or cross device flows;
  • Grant Management for OAuth 2.0 - for ecosystems that require interoperable grant management;
  • OAuth 2.0 Rich Authorization Requests [RFC9396] - for conveying complex authorizations.

The foundation of the framework is the attacker model and security profile. All the other specifications build on the security profile.

1.2. HTTP Headers

Implementers may find the following http-headers useful:

1.2.1. x-fapi-interaction-id

This header can be used to enable Authorization Servers, Resource Servers and Clients to better track and debug any issues between them. If an ecosystem adopts x-fapi-interaction-id then the following clauses apply:

  1. clients shall send the x-fapi-interaction-id request header, the value shall be a UUID [RFC9562], e.g., x-fapi-interaction-id: c770aef3-6784-41f7-8e0e-ff5f97bddb3a;
  2. the AS or RS shall set the response header x-fapi-interaction-id to the value received from the corresponding FAPI client request header if that value is a UUID [RFC9562], or otherwise to a new UUID [RFC9562] value to track the interaction, e.g., x-fapi-interaction-id: c770aef3-6784-41f7-8e0e-ff5f97bddb3a;
  3. participants (whether Client, AS or RS) shall log the value of x-fapi-interaction-id in the log entry.

NOTE: Clients may reuse the same x-fapi-interaction-id value across related requests within a single authorization code flow, including PAR requests, token requests, and immediate API calls. This can help with tracing and troubleshooting related transactions. Due to the nature of browser redirects, the authorization request itself typically cannot include HTTP headers, so the x-fapi-interaction-id will not be present in those requests. Specific guidance on when to reuse vs. generate new interaction IDs may be defined by individual ecosystems.

1.2.2. x-fapi-end-user-present

Many ecosystems have different non-functional requirements depending on whether an end-user is present or not. The x-fapi-end-user-present header indicates whether the request is being made in the context of an interactive end-user session or as part of a background/automated process. If an ecosystem adopts this header, the following clauses apply:

  1. Clients shall send the x-fapi-end-user-present header with a value of true when the request is made with an end-user actively present in the session, and false when the request is part of a background process, batch operation, or automated task without active user participation.

  2. If the header is not present, servers should assume a default value of false (i.e., no end-user is present).

  3. The header value shall be a boolean: either true or false, e.g., x-fapi-end-user-present: true.

1.2.2.1. Purpose and Benefits

The primary benefit of the x-fapi-end-user-present header is to support ecosystem-specific requirements for different traffic patterns:

  1. Many ecosystems implement different rate limits for end-user-present vs. background operations. User-present operations may have higher per-second limits but lower daily limits, while background operations might have the opposite pattern.

  2. During high load situations, servers may prioritize user-present requests to maintain interactive performance while delaying background operations.

1.2.2.2. Implementation Considerations

  1. This header is not a security mechanism. Authorization Servers must trust that Clients are filling in this header correctly and cannot independently verify the presence of an end user.

  2. This header replaces problematic approaches from previous specifications, such as:

    • x-fapi-customer-ip-address: Potentially exposed PII and created privacy concerns
    • x-fapi-auth-date: Frequently implemented incorrectly and requires date parsing
    • Client headers pass-through: Inconsistently used and may expose PII

  3. Since Clients can set this value arbitrarily, ecosystem governance and monitoring are necessary to detect patterns of misuse, such as clients marking all API calls as user-present regardless of context.

NOTE: This header is only useful in ecosystems where recourse exists against clients that falsify its value.

1.3. DPoP vs MTLS

Sender constraining access tokens is an important security measure that provides significant protections against token theft and misuse. FAPI 2.0 allows implementers to use either DPoP or MTLS to achieve this goal. Both approaches meet the security requirements, but each has different characteristics that may make one more suitable than the other depending on your ecosystem. This section outlines considerations to guide your choice.

1.3.1. DPoP Considerations

  1. DPoP operates at the application layer rather than the transport layer;
  2. DPoP only sender constrains part of the request (the HTTP method and URL), unlike MTLS which protects the entire request;
  3. DPoP requires cryptographic operations for each request, which may have performance implications;
  4. DPoP introduces protocol complexity, including HTTP request URL normalization and optionally server-provided nonces;
  5. DPoP library support is less mature than MTLS, and there is limited ecosystem deployment experience;
  6. DPoP is the only viable option for browser-based clients (MTLS only works practically for server-to-server communication).

1.3.2. MTLS Considerations

  1. MTLS performs both client authentication and sender constraining simultaneously, simplifying implementation for clients;
  2. MTLS sender constrains the entire request, not just specific elements;
  3. MTLS amortizes the cost of asymmetric cryptographic operations by performing them during the TLS handshake and reusing the connection;
  4. Self-signed certificates can be used for sender constraining; the binding to the access token is established at the token endpoint without needing to distribute certificates via JWKS;
  5. MTLS presents integration challenges at the transport layer, especially when operating at scale;

  6. MTLS implementations may encounter interoperability issues with certificate handling, including:

    • Certificate aliases
    • IP/SAN negotiation
    • DN matching for PKI;
  7. [RFC9440] provides additional guidance for MTLS implementations.

1.3.3. Selection Guidance

Both DPoP and MTLS are valid choices for sender constraining, and each has trade-offs.

MTLS may be more suitable when:

  • Operating in closed ecosystems with existing PKI infrastructure;
  • Simplicity for client-side implementation is a priority;
  • Full request protection is desired;
  • Mature library support is required.

DPoP may be more suitable when:

  • Browser-based clients need to be supported (MTLS only works practically for server-to-server communication);
  • Transport layer integration for mutual TLS is impractical.

Implementers should not use both DPoP and MTLS simultaneously for sender constraining.

1.4. Organization-Level Certificates

Some ecosystems issue certificates to organizations rather than to individual clients, for example eIDAS certificates, and an organization can operate more than one client.

NOTE: One way to distinguish a client from the organization that operates it is for each client to register the certificates and keys it uses: the subject distinguished name of its TLS client certificate using the tls_client_auth_subject_dn client metadata parameter [RFC8705], and its signing keys at a jwks_uri [RFC7591].

1.5. JARM Downgrade

A client should reject the response if it requests a JARM [JARM] response from an authorization server that advertises JARM support in its response_modes_supported metadata but receives the authorization response parameters, such as code and state, directly instead of in a response JWT.

1.6. PKCE Downgrade

An authorization server that also serves clients that do not use PKCE [RFC7636] can be subject to the PKCE downgrade attack described in Section 4.8 of [RFC9700]. Section 4.8.2 of [RFC9700] requires such an authorization server to reject a token request that contains a code_verifier if the authorization request did not contain a code_challenge.

1.7. Native Applications

  1. Clients should use the authorization code flow with redirects when the end-user uses the client and authenticates on the same device; and
  2. clients should use CIBA [CIBA] only when the end-user authenticates on an authentication device that is separate from the consumption device.

When both the client and the authorization server provide native applications, the end-user can move between them without using a browser:

  1. clients should use claimed HTTPS redirect URIs as described in Section 7.2 of [RFC8252];
  2. authorization servers should claim their authorization endpoint URL in their native application; and
  3. clients and authorization servers should open these URLs in the other party's application if it is installed, and in a browser otherwise.

NOTE 1: On iOS, the universalLinksOnly option, and on Android 11 and later, the FLAG_ACTIVITY_REQUIRE_NON_BROWSER intent flag, open a URL only if an installed application claims it, so that the application can fall back to a browser.

NOTE 2: On Android 12 and later, an HTTPS URL that is not a verified Android App Link always opens in a browser, so the authorization endpoint URL and redirect URI need to be verified App Links. On earlier versions, the end-user can be offered another installed application that handles the same URL.

1.8. Confirming the Same End-User

When OpenID Connect is used, a client that sends the end-user through authorization again, for example to extend an existing grant, can confirm that it is the same end-user by requesting the sub claim in the ID Token with the expected value using the claims parameter, as described in Section 5.5.1 of [OIDC]. The authorization server then only returns a successful response for that end-user.

Authorization servers should support the claims parameter and keep the sub value of an end-user stable, as described in Section 5.7 of [OIDC].

1.9. Access Token Size Considerations

As key size grows and more elements are added to access tokens, it's possible for the HTTP Authorization header containing the access token plus other headers to cumulatively be larger than the allowed buffer size for HTTP requests in many web infrastructure components. It is important to watch this closely via logging and alerting to ensure that production traffic is not adversely affected and that adjustments to the allowed buffer size can be made in a timely manner.

Note: While OAuth 2.0 [RFC6749] leaves token size decisions to the authorization server, implementers should be aware that many standard web servers reject headers larger than 8KB by default.

1.9.1. Security and Performance

Large access tokens can impact both security and performance:

  1. Large tokens increase the risk of header-based DDOS attacks
  2. Larger tokens increase network latency and resource consumption
  3. Authorization servers should practice data minimization and only include necessary claims

1.10. Key Management

Proper management of cryptographic keys is critical to the security of any FAPI 2.0 deployment. The compromise of private keys used for client authentication, token signing, or message signing can lead to severe security breaches, including unauthorized access to protected resources and impersonation attacks.

While detailed guidance on key management is out of scope for the FAPI specifications, implementers should ensure they have robust policies and procedures in place covering:

  1. secure generation of cryptographic keys;
  2. secure storage and protection of private keys;
  3. key rotation and lifecycle management;
  4. procedures for responding to key compromise;
  5. access controls for key material;
  6. backup and recovery procedures.

Implementers should refer to established guidance on cryptographic key management, such as NIST Special Publication 800-57 [NIST.SP.800-57pt1r5] and the OWASP Key Management Cheat Sheet [OWASP.KeyManagement].

NOTE: Hardware Security Modules (HSMs) or similar secure key storage mechanisms are strongly recommended for production deployments, particularly for high-value use cases.

1.11. Troubleshooting Common Issues

1.11.1. Connection Issues

1.11.1.1. Large Access Tokens

Implementers should consider logging the header size in order to catch issues with large access tokens or other potentially large headers.

When access tokens are too large, implementers may encounter the following symptoms:

  1. HTTP 431 (Request Header Fields Too Large) responses from web servers
  2. Connection resets or timeouts when making requests with large tokens
  3. Inconsistent behavior where some requests succeed and others fail
  4. Log entries showing truncated or malformed Authorization headers

1.12. Authorization Server Handling of Suspicious Requests

Many Authorization Server implementations employ Web Application Firewalls (WAFs) and security rules to protect against common attacks such as XSS. This section provides guidance on balancing legitimate security concerns with the need to accept randomly generated values in parameters like state and nonce.

  1. Authorization Servers may reject authorization requests that contain suspicious parameter values which could indicate malicious intent, such as potential XSS attack vectors

  2. While Authorization Servers should evaluate requests for potential security issues, they should not implement blanket restrictions that block certain characters (e.g., "<") entirely

  3. Authorization Servers should accept any random state/nonce values that comply with the underlying specifications

  4. When rejecting suspicious requests, Authorization Servers should return or show appropriate error responses as defined in OAuth 2.0 and related specifications

  5. Clients should use URL-safe characters when generating values for state and nonce parameters

  6. If a client needs to include non-URL-safe characters in the state parameter, it should base64url encode the value, as Authorization Servers may reject values containing characters that resemble attack vectors

NOTE: What constitutes a suspicious or malicious request may vary depending on the threat model of each Authorization Server implementation. This document intentionally avoids providing an exhaustive list of patterns to block, as such a list would quickly become outdated and might provide a false sense of security.

1.13. Errors Shown to the End-User

When the authorization server cannot return an error response to the client, for example because the redirect URI is invalid (Section 4.1.2.1 of [RFC6749]), it informs the end-user instead. The message should not be factually incorrect for either the end-user or the client's developer, for example by suggesting that trying again will help when the client's request was invalid. A generic message, such as "Something went wrong", may be used.

2. Acknowledgements

This document was developed by the OpenID FAPI Working Group.

3. Informative References

[CIBA]
Fernandez Rodriguez, G., Walter, F., Nennker, A., Tonge, D., and B. Campbell, "OpenID Connect Client-Initiated Backchannel Authentication Flow - Core 1.0", , <http://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html>.
[FAPI2_Security_Profile]
Fett, D., Tonge, D., and J. Heenan, "FAPI 2.0 Security Profile", , <https://openid.net/specs/fapi-security-profile-2_0-final.html>.
[FAPIMessageSigning]
Tonge, D. and D. Fett, "FAPI 2.0 Message Signing", , <https://openid.net/specs/fapi-message-signing-2_0-final.html>.
[ISODIR2]
ISO/IEC, "ISO/IEC Directives, Part 2 - Principles and rules for the structure and drafting of ISO and IEC documents", <https://www.iso.org/sites/directives/current/part2/index.xhtml>.
[JARM]
Lodderstedt, T. and B. Campbell, "JWT Secured Authorization Response Mode for OAuth 2.0 (JARM)", , <https://openid.net/specs/oauth-v2-jarm-final.html>.
[NIST.SP.800-57pt1r5]
Barker, E., "Recommendation for Key Management: Part 1 – General", , <https://csrc.nist.gov/publications/detail/sp/800-57-part-1/rev-5/final>.
[OIDC]
Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, "OpenID Connect Core 1.0 incorporating errata set 2", , <http://openid.net/specs/openid-connect-core-1_0.html>.
[OWASP.KeyManagement]
OWASP, "Key Management Cheat Sheet", <https://cheatsheetseries.owasp.org/cheatsheets/Key_Management_Cheat_Sheet.html>.
[RFC6749]
Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, , <https://www.rfc-editor.org/info/rfc6749>.
[RFC7591]
Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, DOI 10.17487/RFC7591, , <https://www.rfc-editor.org/info/rfc7591>.
[RFC7636]
Sakimura, N., Ed., Bradley, J., and N. Agarwal, "Proof Key for Code Exchange by OAuth Public Clients", RFC 7636, DOI 10.17487/RFC7636, , <https://www.rfc-editor.org/info/rfc7636>.
[RFC8252]
Denniss, W. and J. Bradley, "OAuth 2.0 for Native Apps", BCP 212, RFC 8252, DOI 10.17487/RFC8252, , <https://www.rfc-editor.org/info/rfc8252>.
[RFC8705]
Campbell, B., Bradley, J., Sakimura, N., and T. Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens", RFC 8705, DOI 10.17487/RFC8705, , <https://www.rfc-editor.org/info/rfc8705>.
[RFC9396]
Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0 Rich Authorization Requests", RFC 9396, DOI 10.17487/RFC9396, , <https://www.rfc-editor.org/info/rfc9396>.
[RFC9562]
Davis, K., Peabody, B., and P. Leach, "Universally Unique IDentifiers (UUIDs)", RFC 9562, DOI 10.17487/RFC9562, , <https://www.rfc-editor.org/info/rfc9562>.
[RFC9700]
Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, "Best Current Practice for OAuth 2.0 Security", BCP 240, RFC 9700, DOI 10.17487/RFC9700, , <https://www.rfc-editor.org/info/rfc9700>.
[attackermodel]
Fett, D., "FAPI 2.0 Attacker Model", , <https://openid.net/specs/fapi-attacker-model-2_0-final.html>.

Appendix A. Notices

Copyright (c) 2026 The OpenID Foundation.

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, Final Specification, or Final Specification Incorporating Errata Corrections solely for the purposes of (i) developing specifications, and (ii) implementing Implementers Drafts, Final Specifications, and Final Specification Incorporating Errata Corrections 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.

Appendix B. Document History

[[ To be removed from the final specification ]]

-01

Author's Address

Dave Tonge
Moneyhub Financial Technology