15.6. Wallet Provider PDND OpenAPI Specification¶
Below is the complete OpenAPI Specification for the Wallet Provider PDND e-services:
1openapi: 3.0.1
2info:
3 title: IT Wallet API - Wallet Provider web services
4 version: 0.1.0
5servers:
6 - url: https://pdnd.wallet-provider.example.org/api/v1.0
7 description: Wallet Provider API for PDND
8paths:
9 /wallet-instances:
10 patch:
11 tags:
12 - e-services PDND
13 summary: Notification of User's death.
14 description: >-
15 This service is used to notify the Wallet Provider of the need to revoke the Wallet Instance and delete the User's account due to the User's death.
16 operationId: notifyUserDeath
17 parameters:
18 - name: Authorization
19 in: header
20 description: >-
21 JWT token obtained from <a target="blank"
22 href="https://italia.github.io/eid-wallet-it-docs/v1.0.0/en/authentic-sources.html#pdnd-voucher-issuance">PDND
23 Interoperabilità</a>. Based on the implementation choices, it can be either Bearer or DPoP.<br/><br/><a target="blank"
24 href="https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImtpZCI6ImI4MzlmNGM3LTFlNWQtNGE4YS05ZmM2LTcyZDNiN2YwOTFlYyIsInR5cCI6ImF0K2p3dCJ9.eyJpc3MiOiJodHRwczovL2ludGVyb3AucGFnb3BhLml0Iiwic3ViIjoiODI5MTRiM2YtNjBiMi00NTI5LWI0ZDYtM2Q0ZTY3ZjBhOTMzIiwiYXVkIjoiaHR0cHM6Ly9wZG5kLndhbGxldC1wcm92aWRlci5leGFtcGxlLm9yZyIsImV4cCI6MTczMzA0MjE1MCwibmJmIjoxNzMzMDQxOTQ1LCJpYXQiOjE3MzMwNDE5MjAsImp0aSI6ImM0ZjVkN2UyLWI3YzgtNDBmNi05YjZhLWRjOWE0ZjVhZWI1NyIsImNsaWVudF9pZCI6IjgyOTE0YjNmLTYwYjItNDUyOS1iNGQ2LTNkNGU2N2YwYTkzMyIsInB1cnBvc2VJZCI6ImQyYjlhNjUzLWM0OTctNDVjNi1iOGYxLTViZGYxMjRjOWQzYSIsImRpZ2VzdCI6eyJhbGciOiJTSEEyNTYiLCJ2YWx1ZSI6IjljNzg5NGEwYTVhOTEwNTgwYjk2N2YzODRjZGZiYTE3YjFhYjZmODY2NzBlNWIwZGYxOGEwYzQ1M2I1ZWIyMTUifSwiY25mIjp7ImprdCI6Ijg1MmQzMTk5YmQwZTM5OGVhMGM5YzJhMDc3NmNhMzM2NjI4ZTg3MGFlYzdhYzBhNDE4YWRhM2U2Y2UxNjRmOGQifX0.hH7IH-lUXPmh7I_P4QdMa5-FLtcw71jWX90JXa-1KFx0UD5muE7bMu6tND9uj3b0PewOBEsH2pVQ-m81EwleKw">EXAMPLE
25 ON JWT.IO</a>
26 required: true
27 schema:
28 type: string
29 format: Signed JWT
30 example: >-
31 DPoP
32 eyJhbGciOiJFUzI1NiIsImtpZCI6ImI4MzlmNGM3LTFlNWQtNGE4YS05ZmM2LTcyZDNiN2YwOTFlYyIsInR5cCI6ImF0K2p3dCJ9.eyJpc3MiOiJodHRwczovL2ludGVyb3AucGFnb3BhLml0Iiwic3ViIjoiODI5MTRiM2YtNjBiMi00NTI5LWI0ZDYtM2Q0ZTY3ZjBhOTMzIiwiYXVkIjoiaHR0cHM6Ly9wZG5kLndhbGxldC1wcm92aWRlci5leGFtcGxlLm9yZyIsImV4cCI6MTczMzA0MjE1MCwibmJmIjoxNzMzMDQxOTQ1LCJpYXQiOjE3MzMwNDE5MjAsImp0aSI6ImM0ZjVkN2UyLWI3YzgtNDBmNi05YjZhLWRjOWE0ZjVhZWI1NyIsImNsaWVudF9pZCI6IjgyOTE0YjNmLTYwYjItNDUyOS1iNGQ2LTNkNGU2N2YwYTkzMyIsInB1cnBvc2VJZCI6ImQyYjlhNjUzLWM0OTctNDVjNi1iOGYxLTViZGYxMjRjOWQzYSIsImRpZ2VzdCI6eyJhbGciOiJTSEEyNTYiLCJ2YWx1ZSI6IjljNzg5NGEwYTVhOTEwNTgwYjk2N2YzODRjZGZiYTE3YjFhYjZmODY2NzBlNWIwZGYxOGEwYzQ1M2I1ZWIyMTUifSwiY25mIjp7ImprdCI6Ijg1MmQzMTk5YmQwZTM5OGVhMGM5YzJhMDc3NmNhMzM2NjI4ZTg3MGFlYzdhYzBhNDE4YWRhM2U2Y2UxNjRmOGQifX0.hH7IH-lUXPmh7I_P4QdMa5-FLtcw71jWX90JXa-1KFx0UD5muE7bMu6tND9uj3b0PewOBEsH2pVQ-m81EwleKw
33 - name: DPoP
34 in: header
35 description: >-
36 DPoP proof JWT, to comply with the REST_JWS_2021_POP security
37 pattern using the POP_DPoP implementation. See also <a target="blank"
38 href="https://datatracker.ietf.org/doc/html/rfc9449.html">RFC
39 9449</a>.<br/><br/>
40
41
42 <a target="blank" href="https://jwt.io/#debugger-io?token=eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6IkVDIiwia2V5X29wcyI6WyJzaWduIl0sImtpZCI6ImRGVTNNRDI4REpfamZzZmloUHZpMm8tQ3RqTEVVejNwT0lWMEJkTk1mZjgiLCJjcnYiOiJQLTI1NiIsIngiOiJodXlYSVFOdjkwMm9Mc3BYNF96b25DOTRHNnlFbG42bHNkbS0xd003MzJvIiwieSI6Ikk5UERFYXdXSHFhRkRHeDFaa05rLTJQVjZXZHBjYUgzQWZPYkJTTGloZ3cifX0.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIjoiUE9TVCIsImF0aCI6ImNiZGJmNmZlZWY0ODA2MjI4ZGJmNDY0Yjc1MGE5NGMyOGQ4ZTUzMDFhNzE1ZmZjM2U2Y2QyZjk0YjZlOGUxNTQiLCJodHUiOiJodHRwczovL3BkbmQud2FsbGV0LXByb3ZpZGVyLmV4YW1wbGUub3JnIiwiaWF0IjoxNzYyMjYyNjE2fQ.UOor-F5wgUgMiLsn4ODVuveSvwNIYaTqj5TSIiRvcb1M57YhWnhhoJPfzMxPpfyD9nkRwsvnN0UmajrhXleBwQ">EXAMPLE
43 ON JWT.IO</a>
44 required: false
45 schema:
46 type: string
47 format: JWT
48 example: >-
49 eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6IkVDIiwia2V5X29wcyI6WyJzaWduIl0sImtpZCI6ImRGVTNNRDI4REpfamZzZmloUHZpMm8tQ3RqTEVVejNwT0lWMEJkTk1mZjgiLCJjcnYiOiJQLTI1NiIsIngiOiJodXlYSVFOdjkwMm9Mc3BYNF96b25DOTRHNnlFbG42bHNkbS0xd003MzJvIiwieSI6Ikk5UERFYXdXSHFhRkRHeDFaa05rLTJQVjZXZHBjYUgzQWZPYkJTTGloZ3cifX0.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIjoiUE9TVCIsImF0aCI6ImNiZGJmNmZlZWY0ODA2MjI4ZGJmNDY0Yjc1MGE5NGMyOGQ4ZTUzMDFhNzE1ZmZjM2U2Y2QyZjk0YjZlOGUxNTQiLCJodHUiOiJodHRwczovL3BkbmQud2FsbGV0LXByb3ZpZGVyLmV4YW1wbGUub3JnIiwiaWF0IjoxNzYyMjYyNjE2fQ.UOor-F5wgUgMiLsn4ODVuveSvwNIYaTqj5TSIiRvcb1M57YhWnhhoJPfzMxPpfyD9nkRwsvnN0UmajrhXleBwQ
50 - name: Agid-JWT-Signature
51 in: header
52 description: >-
53 JWT containing the signature of the message headers whose integrity
54 needs to be guaranteed, to comply with the INTEGRITY_REST_02
55 security pattern (see <a target="blank"
56 href="https://italia.github.io/eid-wallet-it-docs/v1.0.0/en/e-service-pdnd.html">e-Service PDND</a>). <br/><br/>
57
58
59 <a target="blank" href="https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJzdWIiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL3BkbmQud2FsbGV0LXByb3ZpZGVyLmV4YW1wbGUub3JnIiwiaWF0IjoxNzMzMzk3ODQwLCJuYmYiOjE3MzM0MDE2MjgsImV4cCI6MTczMzQwMTQ0MCwianRpIjoiZDNmN2IyYzktMjc0YS00MmI3LThmOGQtMmU5ZDhiMTczNGIwIiwic2lnbmVkX2hlYWRlcnMiOlt7ImRpZ2VzdCI6IlNIQS0yNTY9NzJlMThiZGRkZjEzYzkxMWI0ZGQ1NjJlZTIxOTc5YTVjOWYyMzVjM2EwMWJkMTQyNmU4NTdkOGMxYTI4MmY0MSJ9LHsiY29udGVudC10eXBlIjoiYXBwbGljYXRpb24vanNvbiJ9XX0.gBX-DMP9IP9m2bxLonabBiIKDwIG2zcUweGMMGoqjtz1y85XjVVEiWOCqXtO-5bnPLmfk_Mf-pBkNEXLD9OiDw">EXAMPLE
60 ON JWT.IO</a>
61 required: true
62 schema:
63 type: string
64 format: JWT
65 example: eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJzdWIiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL3BkbmQud2FsbGV0LXByb3ZpZGVyLmV4YW1wbGUub3JnIiwiaWF0IjoxNzMzMzk3ODQwLCJuYmYiOjE3MzM0MDE2MjgsImV4cCI6MTczMzQwMTQ0MCwianRpIjoiZDNmN2IyYzktMjc0YS00MmI3LThmOGQtMmU5ZDhiMTczNGIwIiwic2lnbmVkX2hlYWRlcnMiOlt7ImRpZ2VzdCI6IlNIQS0yNTY9NzJlMThiZGRkZjEzYzkxMWI0ZGQ1NjJlZTIxOTc5YTVjOWYyMzVjM2EwMWJkMTQyNmU4NTdkOGMxYTI4MmY0MSJ9LHsiY29udGVudC10eXBlIjoiYXBwbGljYXRpb24vanNvbiJ9XX0.gBX-DMP9IP9m2bxLonabBiIKDwIG2zcUweGMMGoqjtz1y85XjVVEiWOCqXtO-5bnPLmfk_Mf-pBkNEXLD9OiDw
66 - name: Digest
67 in: header
68 description: >-
69 Digest of the message payload, to comply with the INTEGRITY_REST_02
70 security pattern. According to <a target="blank" href="https://www.rfc-editor.org/rfc/rfc3230.html#section-4.2">RFC
71 3230 §4.2</a>, the format MUST be the following: digest-algorithm=encoded
72 digest output.
73 required: true
74 schema:
75 type: string
76 example: SHA-256=72e18bdddf13c911b4dd562ee21979a5c9f235c3a01bd1426e857d8c1a282f41
77 - name: Agid-JWT-TrackingEvidence
78 in: header
79 description: >-
80 If the Voucher type is Bearer, this header represents a JWT acting as a proof of possession, to comply with the REST_JWS_2021_POP security
81 pattern using the POP_TPoP implementation. Otherwise, it is a JWT containing the data tracked in the Consumer's domain, to comply with AUDIT_REST_02 (see <a target="blank"
82 href="https://italia.github.io/eid-wallet-it-docs/v1.0.0/en/e-service-pdnd.html">e-Service PDND</a>). <br/><br/>
83 <a target="blank" href="https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL3BkbmQud2FsbGV0LXByb3ZpZGVyLmV4YW1wbGUub3JnIiwiZXhwIjoxNzMzMDUyNjAwLCJuYmYiOjE3MzMwMzY0NTAsImlhdCI6MTczMzAzNjQwMCwianRpIjoiYTRiNWM2ZDctZThmOS1hYmNkLWVmMTItMzQ1Njc4OTAxMjM0IiwiZG5vbmNlIjo2NTI4NDI0MjEzNjg1LCJwdXJwb3NlSWQiOiJiMmMzZDRlNS1mNmc3LWg4aTktajBrMS1sbW5vMTIzNDU2NzgiLCJ1c2VySUQiOiJhOGI3YzZkNS1lNGYzLWcyaDEtaTlqMC1rbG1ub3BxcnN0dXYiLCJsb2EiOiJzdWJzdGFudGlhbCJ9.LUU5BsJcqNlrXGGAuuGbuFXpwtohYfTlaQPDBHVNtcVsMaulHXqXzLgRlQFA3UbkB4do3OrQvNfPky3UC-yX6Q">EXAMPLE
84 ON JWT.IO</a>
85 required: false
86 schema:
87 type: string
88 format: JWT
89 example: eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL3BkbmQud2FsbGV0LXByb3ZpZGVyLmV4YW1wbGUub3JnIiwiZXhwIjoxNzMzMDUyNjAwLCJuYmYiOjE3MzMwMzY0NTAsImlhdCI6MTczMzAzNjQwMCwianRpIjoiYTRiNWM2ZDctZThmOS1hYmNkLWVmMTItMzQ1Njc4OTAxMjM0IiwiZG5vbmNlIjo2NTI4NDI0MjEzNjg1LCJwdXJwb3NlSWQiOiJiMmMzZDRlNS1mNmc3LWg4aTktajBrMS1sbW5vMTIzNDU2NzgiLCJ1c2VySUQiOiJhOGI3YzZkNS1lNGYzLWcyaDEtaTlqMC1rbG1ub3BxcnN0dXYiLCJsb2EiOiJzdWJzdGFudGlhbCJ9.LUU5BsJcqNlrXGGAuuGbuFXpwtohYfTlaQPDBHVNtcVsMaulHXqXzLgRlQFA3UbkB4do3OrQvNfPky3UC-yX6Q
90 requestBody:
91 content:
92 application/json:
93 schema:
94 $ref: "#/components/schemas/notifyUserDeath"
95 responses:
96 "207":
97 description: Multi-Status
98 content:
99 application/jwt:
100 schema:
101 $ref: "#/components/schemas/e-Service_Response"
102 example: "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6ImNkYjUyNTMyLWRkOTQtNDBlZi04MjRkLTljNTViMTBlNmJjOSJ9.eyJpc3MiOiJodHRwczovL3dhbGxldC1wcm92aWRlci5leGFtcGxlLm9yZy92MC45LjAvbm90aWZ5VXNlckRlYXRoIiwibmJmIjoxNzM2ODQ2Njg4LCJleHAiOjE3MzY4NDY5MjgsImlhdCI6MTczNjg0NjY4OCwiYXVkIjoiMzE2NzAwOTItZWVjMC00Zjk1LTg4ZGEtZTFjN2NlNWU0NTA1IiwianRpIjoiOGI5NzFiNDMtZTk5MC00NGZhLTkwMTMtMWIzNTNiZmM1YTBmIiwicmVzdWx0Ijp7InJldm9rZWQiOlsiV2FsbGV0SW5zdGFuY2VpZEEiLCJXYWxsZXRJbnN0YW5jZWlkQiJdLCJub3RfZm91bmRlZCI6WyJXYWxsZXRJbnN0YW5jZWlkQyJdLCJhbHJlYWR5X3Jldm9rZWQiOlsiV2FsbGV0SW5zdGFuY2VpZEQiXX0sInJlc3VsdF9kZXNjcmlwdGlvbiI6IlRoZSBzZXJ2aWNlIHBhcnRpYWxseSBwcm9jZXNzIHRoZSByZXZvY2F0aW9uIG9mIHRoZSByZXF1ZXN0ZWQgV2FsbGV0IEluc3RhbmNlcyBhcyBzb21lIGlkZW50aWZpZXJzIHdlcmUgbm90IGZvdW5kLiJ9.VKieVsh9QDiLVESOUoxH0wj2-oFwpraUpOMTIAUJBBajd674gpHKk9fOoIVyQua6qrkAWyfQ--MKWWUZ7R0oXw"
103 "400":
104 description: Bad Request
105 content:
106 application/json:
107 schema:
108 oneOf:
109 - type: object
110 properties:
111 error:
112 type: string
113 description: invalid_request
114 error_description:
115 type: string
116 description: >-
117 The request cannot be fulfilled because it is missing
118 required parameters, contains invalid parameters, or
119 is otherwise malformed.
120 required:
121 - error
122 - type: object
123 properties:
124 error:
125 type: string
126 description: invalid_dpop_proof
127 error_description:
128 type: string
129 description: >-
130 The request cannot be fulfilled because it contains an
131 invalid dpop proof.
132 required:
133 - error
134 examples:
135 invalid request:
136 value:
137 error: invalid_request
138 error_description: >-
139 The request cannot be fulfilled because it is missing
140 required parameters, contains invalid parameters, or is
141 otherwise malformed
142 invalid dpop proof:
143 value:
144 error: invalid_dpop_proof
145 error_description: >-
146 The request cannot be fulfilled because it contains an
147 invalid dpop proof
148 "401":
149 description: Unauthorized
150 headers:
151 WWW-Authenticate:
152 description: The request cannot be fulfilled because the Voucher is expired, revoked or otherwise malformed. See <a target="blank" href="https://datatracker.ietf.org/doc/html/rfc6750.html#section-3">RFC6750</a> and <a target="blank" href="https://datatracker.ietf.org/doc/html/rfc9449.html#section-7.1-11">RFC9449</a> for details.
153 schema:
154 type: string
155 "404":
156 description: Wallet Instance identifiers not found
157 content:
158 application/json:
159 schema:
160 type: object
161 properties:
162 error:
163 type: string
164 description: The error code
165 example: not_found
166 error_description:
167 type: string
168 description: >-
169 Text in human-readable form providing further details to
170 clarify the nature of the error encountered
171 example: >-
172 The Wallet Provider cannot fulfill the request because none of the
173 Wallet Instance identifiers were found
174 required:
175 - error
176 "500":
177 description: Internal Server Error
178 content:
179 application/json:
180 schema:
181 type: object
182 properties:
183 error:
184 type: string
185 description: server_error
186 error_description:
187 type: string
188 description: >-
189 The request cannot be fulfilled because the e-Service Endpoint encountered an internal problem.
190 required:
191 - error
192 example:
193 error: invalid_request
194 error_description: >-
195 The request cannot be fulfilled because the e-Service Endpoint encountered an internal problem.
196 "503":
197 description: Service Unavailable
198 content:
199 application/json:
200 schema:
201 type: object
202 properties:
203 error:
204 type: string
205 description: The error code
206 error_description:
207 type: string
208 description: >-
209 Text in human-readable form providing further details to
210 clarify the nature of the error encountered
211 required:
212 - error
213 example:
214 error: "temporarily_unavailable"
215 error_description: "The request cannot be fulfilled because the e-Service Endpoint is temporarily unavailable (e.g., due to maintainance or overload)"
216components:
217 schemas:
218 e-Service_Response:
219 properties:
220 Header:
221 type: object
222 properties:
223 alg:
224 description: A digital signature algorithm identifier.
225 type: string
226 example: RS256
227 kid:
228 description: Unique identifier of the JWK used by the Provider to sign the JWT.
229 type: string
230 example: "cdb52532-dd94-40ef-824d-9c55b10e6bc9"
231 typ:
232 description: It MUST be set to 'JWT'.
233 type: string
234 example: "JWT"
235 required: [alg, kid, typ]
236 Payload:
237 type: object
238 properties:
239 iss:
240 description: The identifier of the e-Service.
241 type: string
242 aud:
243 description: The identifier of the Consumer.
244 type: string
245 example: "31670092-eec0-4f95-88da-e1c7ce5e4505"
246 exp:
247 description: UNIX timestamp representing the JWT expiration time.
248 type: integer
249 example: 1736846928
250 iat:
251 description: UNIX timestamp representing the JWT issuance time.
252 type: integer
253 example: 1736846688
254 jti:
255 description: Unique identifier of the JWT to prevent replay attacks.
256 type: string
257 example: "8b971b43-e990-44fa-9013-1b353bfc5a0f"
258 nbf:
259 description: UNIX timestamp representing the JWT first validity time.
260 type: string
261 example: "1736846688"
262 result:
263 type: object
264 properties:
265 revoked:
266 type: array
267 items:
268 type: string
269 description: List of Wallet Instances successfully rekoved.
270 not_found:
271 type: array
272 items:
273 type: string
274 description: List of Wallet Instances not revoked as their identifier were not found at the Wallet Provider.
275 already_revoked:
276 type: array
277 items:
278 type: string
279 description: List of Wallet Instances that were already revoked by the Wallet Provider.
280 required: [revoked, not_found, already_revoked]
281 description: >-
282 JSON object specifying which Wallet Instance was successfully revoked, which was already revoked and which was not found.
283 result_description:
284 description: Response Description.
285 type: string
286 example: The service partially process the revocation of the requested Wallet Instances as some identifiers were not found.
287 required: [iss, aud, exp, iat, jti, result, result_description]
288 notifyUserDeath:
289 required:
290 - wallet_instance_id
291 type: object
292 properties:
293 wallet_instance_ids:
294 type: array
295 items:
296 type: string
297 description: >-
298 Identifiers of the Wallet Instances whose PID was revoked due to User death.