Repository navigation
Define requirements for OpenAPI FAPI securityScheme type #648
Description
Activity
Originally submitted by Nat (Nat Sakimura) on 2024-02-21
Do we just need to talk to OAI? What is the process needed? Do we need to create a new document in their format?
Originally submitted by Kosuke Koiwai (Kosuke Koiwai) on 2024-02-21
I think having FAPI in the OpenAPI spec also helps CAMARA project to adopt FAPI as their API definitions are also in OpenAPI.
[https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md(Bitbucket #11)-definition-in-openapi](https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md(Bitbucket #11)-definition-in-openapi)
Originally submitted by David Hyland (David Hyland) on 2024-03-05
Hi there - I had a look at this last year, forked the spec and drafted the sorts of changes that I felt were required, using the RAR spec examples
https://github.com/dphhyland/OpenAPI-Specification/blob/main/versions/3.1.x.md
Requires review, and in summary I made the following changes:- Up the top of the doc I added a new “authorizationDetails” Component
- New the end of the doc in the “OAuth Flow Object” section added a new “authorization_details” field and included a RAR example
- Updated the Security requirement object to allow Auhtorization Details to be listed alongside scopes
- Added an example
- Added a new Authorization Details Object section to describe the RAR payload
Was a quick experiment to see what it would take to drop RAR in … think it works and my edits could use some better examples (i.e. mixing petshop with payments is a bit jarring)
Next steps were to present to the FAPI WB (here we are) with the objective to then present to OAI …Originally submitted by Nat (Nat Sakimura) on 2026-01-21
To be discussed on the Jan 28 call.
Originally submitted by Nat (Nat Sakimura) on 2026-01-21
David Hyland if you are going to be available for the January 28 call, it would be really good as we are going to be discussing this.
Originally submitted by Takahiko Kawasaki (Takahiko Kawasaki) on 2026-01-23
Based on my experience describing the APIs of a new FAPI2-ready product under development using OpenAPI, I believe that the specification of the OpenAPI Security Scheme Object needs to be revised before adding FAPI- or RAR-related specifications. The current specification of the Security Scheme Object appears to have been defined by people who do not clearly understand the difference between a resource server and an authorization server. Building FAPI- or RAR-related specifications on top of this specification would be like building a house on sand.
Personally, I would like to see DPoP supported in the Security Scheme Object before FAPI or RAR.
Originally submitted by Christopher Robbertse (Christopher Robbertse) on 2026-01-28
Does OpenAPI’s Arazzo Specification help? (Arazzo Spec Deep Dive - Blog)
They have an example FAPI OpenAPI Document and Arazzo Document.
Originally submitted by Clyde_Cutting (Clyde Cutting) on 2026-04-20
Does OIDF have a strategy for moving open issues like this one before BitBucket Aug 20, 2026 deadline?
Originally submitted by Nat (Nat Sakimura) on 2026-04-22
Yes. We are working on it: Re: moving open issues.
Originally submitted by Anoop Saxena (Anoop Saxena) on 2026-06-29
Discussed on Pacific call - https://bitbucket.org/openid/fapi/wiki/FAPI_Meeting_Notes_2026-06-25_Pacific
@sakimura @dpostnikov
Proposed sample yaml Based on Pacific call on 6/25/2026. Need review in Atlantic Call.`
components:
securitySchemes:
OIDCAuth:
type: openIdConnect
openIdConnectUrl: https://example.com/.well-known/openid-configuration
description: "Standard OpenID Connect authentication."FAPI: type: fapi-profile description: "FAPI 2.0 security profile for open finance ecosystems." profileMetadata: name: fapi-2-security-profile version: "2.0" schema: https://openid.net/fapi/fapi2-profile-schema.json conformanceProfile: fapi2-message-signing servers: - name: Development url: https://openid.net/fapi/dev/.well-known - name: Production url: https://openid.net/fapi/prod/.well-known ecosystemProfiles: - name: brazil-fapi-2-security-profile schema: https://openbanking.org.br/.well-known/ecosystem-metadata parentProfiles: - fapi-2-security-profile - fapi-2-message-signing servers: - name: Development url: https://openbanking.org.br/dev/.well-known - name: Production url: https://openbanking.org.br/prod/.well-known - name: uk-fapi-2-security-profile schema: https://openbanking.org.uk/.well-known/ecosystem-metadata parentProfiles: - fapi-2-security-profile servers: - name: Development url: https://openbanking.org.uk/dev/.well-known - name: Production url: https://openbanking.org.uk/prod/.well-known`
@anoopsaxena3262 there has already been some considerable discussion on this, and I'm actively working on changes to the OpenAPI Specification to encompass this.
See this discussion: https://github.com/OAI/OpenAPI-Specification/discussions/5304
It would be great to collaborate on this, as there are some changes to OpenAPI that will help provide tooling makers with better representations of schema-bound objects e.g. the payload element of a JWT.
Sure @sensiblewood-ozone . Let collaborate. ( i am out of town until Aug 27th ). We reviewed the proposal OAI issue link . https://github.com/OAI/OpenAPI-Specification/discussions/5304
We should keep below scope per Pacific FAPI call meeting review.
- FAPI family profile types and versions
- Hierarchical relationships between base profiles and ecosystem extensions
- Ecosystem-specific metadata and discovery endpoints
- Conformance profile references for tooling integration
Feel free to connect and review in next Atlantic or Pacific call. I will catch up after i come back.
FYI I've left some comments on @sensiblewood-ozone draft proposal, on his fork at SensibleWood/OpenAPI-Specification#1
Anyone following this issue may want to take a look. Chris aims to submit to OAI by end of week.
Reacted by Christopher Robbertse
The current generic OpenAPI oauth2 securityScheme type is not descriptive enough to accurately convey FAPI security profile requirements.
FAPI is an API security profile and as such should have its own securityScheme type in the OpenAPI specification. It will enable open data ecosystems and other financial-grade API designers to mark APIs that require FAPI SP with the security scheme of such type. It will enable generation of accurate API documentation and clients. It will also likely increase recognition and adoption of FAPI and will make application of FAPI easier.
I envision that in scope of this task, we would generate requirements for the security scheme type and create a proposal for Open API Initiative (OAI) to include this in the specification.
It is to be considered what should be explicitly and implicitly included in the type e.g. scopes, fapi version, allowed flows, RAR authorization_details types, required headers.
Bitbucket status: open
Bitbucket origin: issue 660