openapi.yaml (10005B)
1 openapi: 3.0.4 2 info: 3 title: OAuth2 Gateway API 4 version: '0.0.1' 5 description: | 6 The OAuth2 Gateway service orchestrates the Know-Your-Customer (KYC) verification flow 7 between OAuth2 clients and the Swiyu Verifier, acting as a resource server for the 8 final Verifiable Credential (VC) proof. 9 10 servers: 11 - url: https://oauth2gw.example.com 12 description: OAuth2 Gateway server 13 14 security: 15 - ClientAuth: [] 16 17 components: 18 securitySchemes: 19 ClientAuth: 20 type: http 21 scheme: bearer 22 description: | 23 Bearer token (Shared Secret) used for server-to-server authentication 24 of the client identity when calling /setup. 25 26 BearerToken: 27 type: http 28 scheme: bearer 29 description: | 30 The access_token issued by the OAuth2 Gateway at the /token endpoint, 31 used to authenticate access to the protected resource at /info. 32 33 schemas: 34 SetupResponse: 35 type: object 36 required: 37 - nonce 38 properties: 39 nonce: 40 type: string 41 description: | 42 The nonce to be used to construct the /authorize URL. 43 example: '7f3e9d2AXb1c4f6e_5a9d8c7AISFe1A_a4d' 44 45 AuthorizeResponse: 46 type: object 47 required: 48 - verification_id 49 - verification_url 50 - state 51 properties: 52 verification_id: 53 type: string 54 format: uuid 55 description: | 56 The unique ID generated by the Swiyu Verifier for the OID4VP session, 57 used internally by the OAuth2 Gateway. 58 example: 'd8c1e4f9-2b0e-4a6c-9a3d-5f8b7c2d1e0a' 59 verification_url: 60 type: string 61 format: uri 62 description: | 63 The URL that must be opened/scanned (as a QR code) to start the OID4VP flow. 64 example: 'swiyu://verify?request_uri=https://verifier.example.com/api/v1/request/d8c1e4f9-2b0e-4a6c-9a3d-5f8b7c2d1e0a' 65 verification_deeplink: 66 type: string 67 format: uri 68 description: | 69 Optional deeplink URL for mobile wallet applications. 70 example: 'swiyu://verify?request_uri=https://verifier.example.com/api/v1/request/d8c1e4f9-2b0e-4a6c-9a3d-5f8b7c2d1e0a' 71 state: 72 type: string 73 description: | 74 The state parameter echoed back from the authorize request for CSRF protection. 75 example: 'AZS7EDH2VD10GSGG8C1SHNE375DYQKHYJAQK8VJ1117WG' 76 77 NotificationRequest: 78 type: object 79 required: 80 - verification_id 81 - timestamp 82 properties: 83 verification_id: 84 type: string 85 format: uuid 86 description: | 87 The verification session ID from the Swiyu Verifier. 88 example: 'd8c1e4f9-2b0e-4a6c-9a3d-5f8b7c2d1e0a' 89 timestamp: 90 type: string 91 format: date-time 92 description: | 93 Timestamp when the notification was sent. 94 example: '2025-12-09T10:30:00Z' 95 96 TokenRequest: 97 type: object 98 required: 99 - grant_type 100 - code 101 - client_id 102 - client_secret 103 properties: 104 grant_type: 105 type: string 106 enum: [authorization_code] 107 description: Must be 'authorization_code' for this flow. 108 code: 109 type: string 110 description: The authorization code received from the client notification webhook. 111 example: '9a4f2e7c8d1b6a3e5f9c8d7e2a1b4c6f' 112 client_id: 113 type: string 114 description: The registered client identifier. 115 example: 'client_production_01' 116 client_secret: 117 type: string 118 description: The client secret for authentication. 119 example: 'cs_8f7e6d5c4b3a2f1e9d8c7b6a5f4e3d2c' 120 121 TokenResponse: 122 type: object 123 required: 124 - access_token 125 - token_type 126 - expires_in 127 properties: 128 access_token: 129 type: string 130 description: Token used to authenticate access to the protected /info endpoint. 131 example: 'at_3d2c1b9a8f7e6d5c4b3a2f1e9d8c7b6a' 132 token_type: 133 type: string 134 enum: [Bearer] 135 description: Must be "Bearer". 136 expires_in: 137 type: integer 138 description: Amount of time that the access token is valid (in seconds). 139 example: 3600 140 141 VerifiableCredential: 142 type: object 143 description: The Verifiable Credential (VC) proof object. 144 properties: 145 data: 146 type: object 147 description: The verified attributes derived from the VC. 148 example: 149 vct: 'betaid-sdjwt' 150 age_over_18: true 151 iat: 1733741234 152 exp: 1765277234 153 154 paths: 155 /setup/{clientId}: 156 post: 157 summary: Initiate KYC verification session 158 description: | 159 The client calls this endpoint to begin a KYC process. It creates a new session and returns a `nonce`. 160 tags: 161 - Authorization Flow 162 security: 163 - ClientAuth: [] 164 parameters: 165 - in: path 166 name: clientId 167 schema: 168 type: string 169 required: true 170 description: The registered client identifier. 171 example: 'client_production_01' 172 responses: 173 '200': 174 description: Session successfully created and nonce returned. 175 content: 176 application/json: 177 schema: 178 $ref: '#/components/schemas/SetupResponse' 179 '401': 180 description: Authentication failed (Invalid or missing client secret). 181 '404': 182 description: Client not found. 183 184 /authorize/{nonce}: 185 get: 186 summary: Initiate the OID4VP verification flow 187 description: | 188 The client constructs a URL to this endpoint using the `nonce` from /setup. 189 The OAuth2 Gateway initiates the Swiyu verification and returns the verification URL. 190 tags: 191 - Authorization Flow 192 parameters: 193 - in: path 194 name: nonce 195 schema: 196 type: string 197 required: true 198 description: The nonce returned from the /setup endpoint. 199 example: '7f3e9d2a8b1c4f6e5a9d8c7b3e2f1a4d' 200 - in: query 201 name: response_type 202 schema: 203 type: string 204 enum: [code] 205 required: true 206 description: Must be 'code' for authorization code flow. 207 - in: query 208 name: client_id 209 schema: 210 type: string 211 required: true 212 description: The registered client identifier. 213 example: 'client_production_01' 214 - in: query 215 name: redirect_uri 216 schema: 217 type: string 218 format: uri 219 required: true 220 description: The client redirect URI where the user will be redirected to after verification. 221 example: 'https://client.example.com/kyc/thank-you' 222 - in: query 223 name: state 224 schema: 225 type: string 226 required: true 227 description: Opaque value used by the client to maintain state between request and callback (CSRF protection). 228 example: 'payto://iban/CH9300762011623852957' 229 - in: query 230 name: scope 231 schema: 232 type: string 233 required: true 234 description: Space-delimited string of desired attributes to verify. 235 example: 'age_over_18' 236 responses: 237 '200': 238 description: Verification URL returned. 239 content: 240 application/json: 241 schema: 242 $ref: '#/components/schemas/AuthorizeResponse' 243 '404': 244 description: Nonce not found or session expired. 245 '410': 246 description: Session expired. 247 '409': 248 description: Invalid session status. 249 250 /notification: 251 post: 252 summary: Webhook notification from Swiyu Verifier 253 description: | 254 The Swiyu Verifier calls this endpoint to notify the OAuth2 Gateway that 255 a verification session has been completed. The gateway then notifies the client 256 via GET request to the redirect_uri with the authorization code. 257 tags: 258 - Webhooks 259 requestBody: 260 required: true 261 content: 262 application/json: 263 schema: 264 $ref: '#/components/schemas/NotificationRequest' 265 responses: 266 '200': 267 description: Notification received and processed. 268 269 /token: 270 post: 271 summary: Exchange authorization code for access token 272 description: | 273 The client calls this endpoint to exchange the authorization code for an access token 274 after receiving the code via the notification webhook. 275 tags: 276 - Authorization Flow 277 requestBody: 278 required: true 279 content: 280 application/x-www-form-urlencoded: 281 schema: 282 $ref: '#/components/schemas/TokenRequest' 283 responses: 284 '200': 285 description: Access token successfully issued. 286 content: 287 application/json: 288 schema: 289 $ref: '#/components/schemas/TokenResponse' 290 '400': 291 description: Invalid request or invalid authorization code. 292 '401': 293 description: Client authentication failed. 294 295 /info: 296 get: 297 summary: Retrieve the Verifiable Credential proof 298 description: | 299 The client calls this endpoint using the access_token to retrieve the 300 Verifiable Credential proof (protected resource). 301 tags: 302 - Resource Retrieval 303 security: 304 - BearerToken: [] 305 responses: 306 '200': 307 description: Verifiable Credential proof successfully retrieved. 308 content: 309 application/json: 310 schema: 311 $ref: '#/components/schemas/VerifiableCredential' 312 '401': 313 description: Authentication failed (Invalid or missing access_token).