GNAP OpenAPI Security Scheme (x-gnap)

A vendor extension and formal proposal to add GNAP (RFC 9635) as a security scheme type in the OpenAPI Specification, enabling automated SDK generation for Open Payments and other GNAP-protected APIs.

Problem Statement

The OpenAPI Specification (OAS 3.1) supports five security scheme types: apiKey, http, mutualTLS, oauth2, and openIdConnect. GNAP (Grant Negotiation and Authorization Protocol, RFC 9635) is not among them.

This means that APIs using GNAP for authorization - including Open Payments, the payment initiation standard built on the Interledger Protocol - cannot express their authentication requirements in OpenAPI documents. When developers use SDK generators like Kiota, OpenAPI Generator, or Swagger Codegen, the GNAP authentication layer is silently dropped.

The result: Every Open Payments integration requires developers to hand-build GNAP flows from scratch - reading RFCs, implementing token lifecycle management, constructing HTTP Message Signature headers, and handling grant continuation state machines.

Solution

This project delivers:

1. x-gnap Vendor Extension - An immediately usable extension for OAS 3.1 that describes GNAP security requirements in a machine-readable format.
2. JSON Schema - A formal schema definition for the x-gnap extension, enabling tooling validation.
3. Annotated Open Payments Spec - The official Open Payments OpenAPI document, annotated with the x-gnap extension.
4. OAS Proposal - A formal proposal to the OpenAPI Technical Steering Committee for native GNAP support.

x-gnap Extension Structure

components:
  securitySchemes:
    gnap:
      type: apiKey  # placeholder for OAS compatibility
      in: header
      name: Authorization
      x-gnap:
        grant_endpoint: "https://auth.example.com/"
        token_formats:
          - bearer
          - pop
        key_proofs:
          - method: httpsig
            alg:
              - ed25519
              - ecdsa-p256-sha256
          - method: mtls
          - method: jwsd
        interaction:
          start:
            - redirect
            - user_code
          finish:
            - redirect
            - push
        access_rights:
          - type: incoming-payment
            actions: [create, read, read-all, list, complete]
          - type: outgoing-payment
            actions: [create, read, read-all, list]
          - type: quote
            actions: [create, read, read-all]
        continuation:
          supported: true
          poll: true
          wait: true

Project Structure

gnap-openapi-security-scheme/
  schemas/
    x-gnap-extension.json       # JSON Schema for the x-gnap extension
  specs/
    open-payments-gnap.yaml     # Annotated Open Payments OAS document
  examples/
    basic-usage.yaml            # Minimal example
    full-featured.yaml          # Complete example with all options
  docs/
    SPECIFICATION.md            # Detailed specification document
    OAS-PROPOSAL.md             # Draft proposal for OAS TSC
    GNAP-PRIMER.md              # Quick intro to GNAP for API designers
  tests/
    validate-schema.js          # Schema validation tests (25 tests)
  .github/workflows/
    ci.yml                      # CI: schema validation on Node 18/20/22
  package.json                  # Node.js project with ajv validation
  LICENSE
  README.md

Quick Start

1. Add x-gnap to your OpenAPI document

openapi: "3.1.0"
info:
  title: My GNAP-Protected API
  version: "1.0.0"

components:
  securitySchemes:
    gnap_auth:
      type: apiKey
      in: header
      name: Authorization
      x-gnap:
        grant_endpoint: "https://auth.example.com/"
        key_proofs:
          - method: httpsig
            alg: [ed25519]
        token_formats: [bearer]

security:
  - gnap_auth: []

2. Validate your extension

npm install ajv
node tests/validate-schema.js your-api.yaml

3. Generate an SDK with GNAP support

# Using Kiota with the GNAP authentication provider
kiota generate -l typescript \
  -d your-api.yaml \
  -o ./sdk \
  --auth-provider @shujaapay/kiota-gnap-provider

GNAP Concepts Mapped to OpenAPI

| GNAP Concept | x-gnap Field | Description | |---|---|---| | Grant Endpoint | grant_endpoint | URL where clients initiate grant requests | | Key Proofs | key_proofs | How clients prove key possession (httpsig, mtls, jwsd) | | Interaction | interaction | How the resource owner interacts (redirect, user_code) | | Access Rights | access_rights | Fine-grained resource permissions with wallet address scoping | | Token Format | token_formats | Bearer or proof-of-possession tokens | | Continuation | continuation | Grant update, cancel, and polling support | | Identifier | identifier | Wallet address scoping for access rights (Open Payments) | | Limits | limits | Financial constraints: debitAmount, receiveAmount, interval |

Integration with ShujaaPay

ShujaaPay is an Open Payments-compliant fintech platform built on the Interledger Protocol. The x-gnap extension powers ShujaaPay's authentication layer:

┌─────────────────────────────────────────────────────────────┐
│                    ShujaaPay Platform                        │
│                   www.shujaapay.me                           │
│                                                             │
│  ┌──────────────┐  ┌──────────────────┐  ┌──────────────┐  │
│  │   Gateway     │  │  Wallet Service  │  │   Payments   │  │
│  │  (Node.js)    │──│   (Node.js)      │──│  (Node.js)   │  │
│  └──────┬───────┘  └────────┬─────────┘  └──────────────┘  │
│         │                   │                                │
│  ┌──────┴───────────────────┴──────────────────────────┐    │
│  │            GNAP Authentication Layer                 │    │
│  │                                                      │    │
│  │  x-gnap extension  ──→  Schema validation            │    │
│  │  kiota-gnap-auth-ts ──→  SDK token management        │    │
│  │  http-signatures    ──→  RFC 9421 request signing    │    │
│  └──────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

How it works in production:

1. API Definition — ShujaaPay's OpenAPI spec uses x-gnap to describe GNAP auth requirements
2. SDK Generation — Kiota reads x-gnap and generates type-safe GNAP clients
3. Token Lifecycle — @shujaapay/kiota-gnap-auth-ts manages grant requests, token rotation, and continuation
4. Request Signing — @shujaapay/http-message-signatures signs every API call per RFC 9421
5. Wallet Scoping — Access rights use identifier to scope grants to specific wallet addresses (e.g., https://wallet.shujaapay.me/alice)

Install

# npm
npm install @shujaapay/gnap-openapi-security-scheme

# Use in your project
const schema = require('@shujaapay/gnap-openapi-security-scheme');

Relationship to Other Projects

This specification is part of the ShujaaPay GNAP Stack — open-source tooling for the Open Payments ecosystem:

| Repo | Package | Status | |------|---------|--------| | This repo — GNAP OpenAPI Security Scheme | @shujaapay/gnap-openapi-security-scheme | 🔧 In progress | | kiota-gnap-auth-ts — Kiota GNAP Provider (TypeScript) | @shujaapay/kiota-gnap-auth-ts | 🔧 In progress | | kiota-gnap-auth-python — Kiota GNAP Provider (Python) | shujaapay-kiota-gnap-auth | 🔧 In progress | | http-message-signatures — RFC 9421 library | @shujaapay/http-message-signatures | 🔧 In progress |

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Key areas where we need help:

• Review of the x-gnap schema for completeness
• Testing with different SDK generators
• Feedback on the OAS proposal draft
• Additional examples for different GNAP configurations

References

• ShujaaPay — Open Payments-compliant fintech platform
• RFC 9635 - Grant Negotiation and Authorization Protocol (GNAP)
• RFC 9421 - HTTP Message Signatures
• OpenAPI Specification 3.1
• Open Payments
• Interledger Protocol
• Microsoft Kiota

License

MIT License - see LICENSE for details.

Built by ShujaaPay — Global Payments. Local Freedom.