commit 5c31c9d5e59026c83886364dc64e5d011e6e5487
parent d223de3768571b89b7f7a780eeb1fced07beebe1
Author: Henrique Chan Carvalho Machado <henriqueccmachado@tecnico.ulisboa.pt>
Date: Mon, 13 Oct 2025 13:04:20 +0200
Added oauth2 gateway API specification
Diffstat:
1 file changed, 146 insertions(+), 0 deletions(-)
diff --git a/oauth2_gateway/openapi.yaml b/oauth2_gateway/openapi.yaml
@@ -0,0 +1,146 @@
+openapi: 3.0.4
+info:
+ title: Oauth2 Gateway API
+ version: '0.0.1'
+ description: |
+ The Oauth2 Gateway service orchestrates the Know-Your-Customer (KYC) verification flow
+ between the Taler Exchange and the Swiyu Verifier, acting as a resource server for the
+ final Verifiable Credential (VC) proof.
+
+servers:
+ - url: https://oauth2gw.example.com
+ description: Oauth2 Gateway server
+
+security:
+ - ExchangeAuth: []
+
+components:
+ securitySchemes:
+ ExchangeAuth:
+ type: http
+ scheme: bearer
+ description: |
+ Bearer token (Shared Secret) used for server-to-server authentication
+ between the Taler Exchange and the Oauth2 Gateway.
+
+ schemas:
+ AuthorizationRequest:
+ type: object
+ required:
+ - client_id
+ - scope
+ properties:
+ client_id:
+ type: string
+ description: The registered client identifier of the Exchange (or the operation).
+ example: 'taler-exchange-client-kyc'
+ scope:
+ type: string
+ description: |
+ A space-delimited string of desired attributes the Exchange wishes to verify,
+ defining the selective disclosure parameters.
+ example: 'swiyu:name swiyu:date_of_birth'
+ redirect_uri:
+ type: string
+ format: uri
+ description: |
+ The URI where the Exchange expects the user to be redirected after
+ initial setup (optional, as the flow is mostly asynchronous).
+ This is included for compliance with RFC 6749.
+
+ AuthorizationResponse:
+ type: object
+ required:
+ - verificationId
+ - verification_url
+ properties:
+ verificationId:
+ type: string
+ format: uuid
+ description: |
+ The unique identifier for this verification session, generated by the SwiyuVerifier.
+ This ID is used in subsequent notification and retrieval calls.
+ verification_url:
+ type: string
+ format: uri
+ description: |
+ The URL that the Browser must scan/open to start the OID4VP flow.
+ This is typically presented as a QR code.
+ example: 'swiyu://verify?request_uri=...'
+
+ VerifiableCredential:
+ type: object
+ description: The Verifiable Credential (VC) JSON object containing the verified proof.
+ properties:
+ proof:
+ type: string
+ description: The actual cryptographic proof/signed data from the SwiyuVerifier.
+ attributes:
+ type: object
+ description: Parsed key-value pairs of the verified attributes.
+ example:
+ name: 'John Doe'
+ date_of_birth: '1990-01-01'
+
+paths:
+ /kyc/authorize:
+ post:
+ summary: Initiate KYC verification via Swiyu OID4VP flow
+ description: |
+ The Exchange calls this endpoint to start a new verification session.
+ This is analogous to the OAuth 2.0 `/authorize` endpoint but immediately
+ returns the deep link/QR code for the user's wallet.
+ tags:
+ - Authorization
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/AuthorizationRequest'
+ responses:
+ '200':
+ description: Verification session successfully started and QR code returned.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/AuthorizationResponse'
+ '401':
+ description: Authentication failed (Invalid or missing Exchange Bearer token).
+ '400':
+ description: Invalid request (e.g., missing required 'scope').
+
+ /kyc/info/{verificationId}:
+ get:
+ summary: Retrieve the Verifiable Credential (VC) proof
+ description: |
+ The Exchange calls this endpoint using the `verificationId` after receiving the
+ asynchronous notification (`/oauth2gw/kyc/notify`). This is analogous to the
+ OAuth 2.0 `/info` (Userinfo) endpoint
+ and returns the protected resource (the VC).
+ tags:
+ - Resource Retrieval
+ parameters:
+ - in: path
+ name: verificationId
+ schema:
+ type: string
+ format: uuid
+ required: true
+ description: The unique ID of the completed verification session.
+ responses:
+ '200':
+ description: Proof successfully retrieved.
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VerifiableCredential'
+ '401':
+ description: Authentication failed (Invalid or missing Exchange Bearer token).
+ '404':
+ description: The `verificationId` is unknown or the verification is not yet complete.
+ '403':
+ description: Authorization failed (Token is valid but lacks scope/permissions).
+
+ # Note: The Oauth2Gateway also needs to define an internal webhook receiver
+ # for the SwiyuVerifier, but that is generally considered an internal/private endpoint.
