Define requirements for OpenAPI FAPI securityScheme type

Originally submitted by Lukasz Jaromin (Lukasz Jaromin) on 2024-01-10

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

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

@sakimura @dpostnikov
Proposed sample yaml Based on Pacific call on 6/25/2026. Need review in Atlantic Call.

OpenId-OpenAPI.yaml

`
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

@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.

@sensiblewood-ozone

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.

@sensiblewood-ozone

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.

@anoopsaxena3262

@anoopsaxena3262 , @lj-raidiam, @aaronpk : Chris has now created formal OAI pull request at OAI/sig-security#54,

Navigation Menu

Repository navigation

Define requirements for OpenAPI FAPI securityScheme type #648

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Define requirements for OpenAPI FAPI securityScheme type #648

Description

Activity

bitbucket-import-issues commented on Jul 2, 2026

bitbucket-import-issues commented on Jul 2, 2026

bitbucket-import-issues commented on Jul 2, 2026

bitbucket-import-issues commented on Jul 2, 2026

bitbucket-import-issues commented on Jul 2, 2026

bitbucket-import-issues commented on Jul 2, 2026

bitbucket-import-issues commented on Jul 2, 2026

bitbucket-import-issues commented on Jul 2, 2026

bitbucket-import-issues commented on Jul 2, 2026

bitbucket-import-issues commented on Jul 2, 2026

anoopsaxena3262 commented on Jul 10, 2026

sensiblewood-ozone commented on Jul 31, 2026

anoopsaxena3262 commented on Aug 1, 2026

lj-raidiam commented on Sep 24, 2026

cuttingclyde commented on Oct 13, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions