From b08a2279a40cda63acfc3730cef31ce9e8f41d3b Mon Sep 17 00:00:00 2001
From: Ariel Yahav <ariel@formance.com>
Date: Wed, 19 Aug 2026 13:01:33 +0100
Subject: [PATCH 1/2] docs(openapi): describe the schema fields in the spec

The Auth spec declared its schema types without saying what any of the
fields mean, so the generated SDKs and the API reference showed bare
names and types. Add descriptions to the client, secret, and scope
schemas so the meaning travels with the spec.
---
 openapi.yaml | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)

diff --git a/openapi.yaml b/openapi.yaml
index 0f80a3b..e909631 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -253,6 +253,7 @@ components:
     Metadata:
       type: object
       nullable: true
+      description: Arbitrary key/value pairs attached to the resource
       additionalProperties:
         type: string
     ClientOptions:
@@ -260,24 +261,31 @@ components:
       properties:
         public:
           type: boolean
+          description: Whether the client is public, meaning it cannot keep a secret and uses PKCE instead
         redirectUris:
           type: array
+          description: URIs the authorization server may redirect to after a successful authorization
           items:
             type: string
         description:
           type: string
+          description: Human-readable description of the client
         name:
           type: string
+          description: Display name of the client
         trusted:
           type: boolean
+          description: Whether the client is trusted, skipping the user consent screen
         postLogoutRedirectUris:
           type: array
+          description: URIs the authorization server may redirect to after logout
           items:
             type: string
         metadata:
           $ref: '#/components/schemas/Metadata'
         scopes:
           type: array
+          description: Scopes the client is allowed to request
           items:
             type: string
       required:
@@ -287,10 +295,13 @@ components:
       properties:
         lastDigits:
           type: string
+          description: Last digits of the secret, the only part retained after creation
         name:
           type: string
+          description: Human-readable name identifying the secret
         id:
           type: string
+          description: Unique identifier of the secret
         metadata:
           $ref: '#/components/schemas/Metadata'
       required:
@@ -298,6 +309,7 @@ components:
         - lastDigits
         - name
     Client:
+      description: An OAuth2 client registered on the stack
       allOf:
         - $ref: '#/components/schemas/ClientOptions'
         - type: object
@@ -315,6 +327,7 @@ components:
       properties:
         label:
           type: string
+          description: Human-readable label for the scope
         metadata:
           $ref: '#/components/schemas/Metadata'
       required:
@@ -337,11 +350,13 @@ components:
       properties:
         name:
           type: string
+          description: Human-readable name identifying the secret
         metadata:
           $ref: '#/components/schemas/Metadata'
       required:
         - name
     Secret:
+      description: A client secret. The full value is returned only at creation and cannot be retrieved again
       allOf:
         - $ref: '#/components/schemas/SecretOptions'
         - type: object
@@ -358,15 +373,19 @@ components:
             - clear
     User:
       type: object
+      description: A user known to the stack's identity provider
       properties:
         id:
           type: string
+          description: Unique identifier of the user
           example: 3bb03708-312f-48a0-821a-e765837dc2c4
         subject:
           type: string
+          description: Subject claim identifying the user with the identity provider
           example: Jane Doe
         email:
           type: string
+          description: Email address of the user
           example: user1@orga1.com
     CreateClientRequest:
       $ref: '#/components/schemas/ClientOptions'
@@ -380,6 +399,7 @@ components:
       properties:
         data:
           type: array
+          description: The clients registered on this stack
           items:
             $ref: '#/components/schemas/Client'
     UpdateClientRequest:
@@ -408,6 +428,7 @@ components:
       properties:
         data:
           type: array
+          description: The users known to this stack
           items:
             $ref: '#/components/schemas/User'
     ServerInfo:
@@ -417,3 +438,4 @@ components:
       properties:
         version:
           type: string
+          description: Version of the auth service

From aa469c24de94cdd45e60ebc7d38771a349e7aa00 Mon Sep 17 00:00:00 2001
From: ariel-formance <ariel@formance.com>
Date: Wed, 19 Aug 2026 14:46:37 +0100
Subject: [PATCH 2/2] Update openapi.yaml

---
 openapi.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/openapi.yaml b/openapi.yaml
index e909631..55bc8e2 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -295,7 +295,7 @@ components:
       properties:
         lastDigits:
           type: string
-          description: Last digits of the secret, the only part retained after creation
+          description: Last digits of the secret. The full plaintext is hidden, and only the last digits are exposed.
         name:
           type: string
           description: Human-readable name identifying the secret