20.5. Specifica OpenAPI del Fornitore di Wallet PDND

Di seguito è riportata la specifica OpenAPI completa per i servizi elettronici PDND del Fornitore di Wallet:

  1openapi: 3.0.1
  2info:
  3  title: IT Wallet API - Wallet Provider web services
  4  version: 0.2.0
  5  description: IT Wallet Provider e-Service exposed via PDND.
  6  termsOfService: "https://authentic-source.example.it/tos/"
  7  contact:
  8    name: IT-Wallet <wallet_provider>
  9    url: https://github.com/italia/eid-wallet-it-docs
 10  x-api-id: WPITW-01
 11  x-summary: IT Wallet Wallet Provider API.
 12servers:
 13  - url: https://test.wallet-provider.example.it/v0.2.0
 14    description: Wallet Provider API test server
 15  - url: https://wallet-provider.example.it/v0.2.0
 16    description: Wallet Provider API production server
 17paths:
 18  /status:
 19    get:
 20      tags:
 21        - status
 22      summary: Get Wallet Provider API status.
 23      description: Health-check endpoint that returns the operational status of the Wallet Provider API.
 24      operationId: walletProviderStatus
 25      responses:
 26        "200":
 27          description: Service available
 28          content:
 29            application/problem+json:
 30              schema:
 31                $ref: "#/components/schemas/ProblemDetails"
 32          headers:
 33            Cache-Control:
 34              $ref: "#/components/headers/CacheControlHeader"
 35            RateLimit-Limit:
 36              $ref: "#/components/headers/RateLimitLimitHeader"
 37            RateLimit-Remaining:
 38              $ref: "#/components/headers/RateLimitRemainingHeader"
 39            RateLimit-Reset:
 40              $ref: "#/components/headers/RateLimitResetHeader"
 41        "429":
 42          description: Too Many Requests
 43          content:
 44            application/problem+json:
 45              schema:
 46                $ref: "#/components/schemas/ProblemDetails"
 47          headers:
 48            RateLimit-Limit:
 49              $ref: "#/components/headers/RateLimitLimitHeader"
 50            RateLimit-Remaining:
 51              $ref: "#/components/headers/RateLimitRemainingHeader"
 52            RateLimit-Reset:
 53              $ref: "#/components/headers/RateLimitResetHeader"
 54        "503":
 55          description: Service Unavailable
 56          content:
 57            application/problem+json:
 58              schema:
 59                $ref: "#/components/schemas/ProblemDetails"
 60          headers:
 61            Retry-After:
 62              $ref: "#/components/headers/RetryAfterHeader"
 63
 64  /wallet-instances:
 65    patch:
 66      tags:
 67        - instance
 68      summary: Notification of User's death.
 69      description: >-
 70        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.
 71      operationId: notifyUserDeath
 72      parameters:
 73        - name: Agid-JWT-Signature
 74          in: header
 75          description: >-
 76            JWT containing the signature of the message headers whose integrity
 77            needs to be guaranteed, to comply with the INTEGRITY_REST_02
 78            security pattern (see <a target="blank"
 79            href="https://italia.github.io/eid-wallet-it-docs/versione-corrente/en/e-service-pdnd.html">e-Service PDND</a>). <br/><br/>
 80
 81            <a target="blank" href="https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJzdWIiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImlhdCI6MTczMzM5Nzg0MCwibmJmIjoxNzMzNDAxNjI4LCJleHAiOjE3MzM0MDE0NDAsImp0aSI6ImQzZjdiMmM5LTI3NGEtNDJiNy04ZjhkLTJlOWQ4YjE3MzRiMCIsInNpZ25lZF9oZWFkZXJzIjpbeyJkaWdlc3QiOiJTSEEtMjU2PTcyZTE4YmRkZGYxM2M5MTFiNGRkNTYyZWUyMTk3OWE1YzlmMjM1YzNhMDFiZDE0MjZlODU3ZDhjMWEyODJmNDEifSx7ImNvbnRlbnQtdHlwZSI6ImFwcGxpY2F0aW9uL2pzb24ifV19.tG5-P96CCA6N1IYC-xk4GumoVkA3NFolpbBn2vQ2e9vpWQ8f5Sm2l4-1VrXfKTx-CUVz_puiwqkBhulrNKj2fA">EXAMPLE
 82            ON JWT.IO</a>
 83          required: true
 84          schema:
 85            type: string
 86            format: JWT
 87            example: eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJzdWIiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImlhdCI6MTczMzM5Nzg0MCwibmJmIjoxNzMzNDAxNjI4LCJleHAiOjE3MzM0MDE0NDAsImp0aSI6ImQzZjdiMmM5LTI3NGEtNDJiNy04ZjhkLTJlOWQ4YjE3MzRiMCIsInNpZ25lZF9oZWFkZXJzIjpbeyJkaWdlc3QiOiJTSEEtMjU2PTcyZTE4YmRkZGYxM2M5MTFiNGRkNTYyZWUyMTk3OWE1YzlmMjM1YzNhMDFiZDE0MjZlODU3ZDhjMWEyODJmNDEifSx7ImNvbnRlbnQtdHlwZSI6ImFwcGxpY2F0aW9uL2pzb24ifV19.tG5-P96CCA6N1IYC-xk4GumoVkA3NFolpbBn2vQ2e9vpWQ8f5Sm2l4-1VrXfKTx-CUVz_puiwqkBhulrNKj2fA
 88        - name: Digest
 89          in: header
 90          description: >-
 91            Digest of the message payload, to comply with the INTEGRITY_REST_02
 92            security pattern. According to <a target="blank" href="https://www.rfc-editor.org/rfc/rfc3230.html#section-4.2">RFC
 93            3230 §4.2</a>, the format MUST be the following: digest-algorithm=encoded
 94            digest output.
 95          required: true
 96          schema:
 97            type: string
 98            example: SHA-256=72e18bdddf13c911b4dd562ee21979a5c9f235c3a01bd1426e857d8c1a282f41
 99        - name: Agid-JWT-TrackingEvidence
100          in: header
101          description: >-
102            TrackingEvidence JWT for AUDIT_REST_02. Optional. It MAY be sent
103            together with POP_DPoP (`Authorization: DPoP` and the `DPoP` proof)
104            when the Provider requires tracked data from the Consumer, such as
105            caller LoA, userID, IP address, or other data agreed with the
106            Provider. The DPoP proof remains the proof of possession. When the
107            Provider mandates AUDIT_REST_02, this header MUST be present.
108            For POP_TPoP the same header is required by `TrackingEvidenceAuth`
109            together with `BearerAuth`; send a single header value
110            (see <a target="blank"
111            href="https://italia.github.io/eid-wallet-it-docs/versione-corrente/en/e-service-pdnd.html">e-Service PDND</a>). <br/><br/>
112            <a target="blank" href="https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImV4cCI6MTczMzA1MjYwMCwibmJmIjoxNzMzMDM2NDUwLCJpYXQiOjE3MzMwMzY0MDAsImp0aSI6ImE0YjVjNmQ3LWU4ZjktYWJjZC1lZjEyLTM0NTY3ODkwMTIzNCIsImRub25jZSI6NjUyODQyNDIxMzY4NSwicHVycG9zZUlkIjoiYjJjM2Q0ZTUtZjZnNy1oOGk5LWowazEtbG1ubzEyMzQ1Njc4IiwidXNlcklEIjoiYThiN2M2ZDUtZTRmMy1nMmgxLWk5ajAta2xtbm9wcXJzdHV2IiwibG9hIjoic3Vic3RhbnRpYWwifQ.y42yfMeW2H9h0b0j0BODUml8yF20stY9q3BwoVU5BB90afBj852Q0QlInncdhjXhUjLS1V76cGBxkutDNvxRNA">EXAMPLE
113            ON JWT.IO</a>
114          required: false
115          schema:
116            type: string
117            format: JWT
118            example: eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImV4cCI6MTczMzA1MjYwMCwibmJmIjoxNzMzMDM2NDUwLCJpYXQiOjE3MzMwMzY0MDAsImp0aSI6ImE0YjVjNmQ3LWU4ZjktYWJjZC1lZjEyLTM0NTY3ODkwMTIzNCIsImRub25jZSI6NjUyODQyNDIxMzY4NSwicHVycG9zZUlkIjoiYjJjM2Q0ZTUtZjZnNy1oOGk5LWowazEtbG1ubzEyMzQ1Njc4IiwidXNlcklEIjoiYThiN2M2ZDUtZTRmMy1nMmgxLWk5ajAta2xtbm9wcXJzdHV2IiwibG9hIjoic3Vic3RhbnRpYWwifQ.y42yfMeW2H9h0b0j0BODUml8yF20stY9q3BwoVU5BB90afBj852Q0QlInncdhjXhUjLS1V76cGBxkutDNvxRNA
119      security:
120        - DPoPVoucherAuth: []
121          DPoPProof: []
122        - BearerAuth: []
123          TrackingEvidenceAuth: []
124      requestBody:
125        required: true
126        content:
127          application/merge-patch+json:
128            schema:
129              $ref: "#/components/schemas/NotifyUserDeath"
130      responses:
131        "207":
132          description: Multi-Status
133          headers:
134            Agid-JWT-Signature:
135              description: JWT containing the signature of the message headers whose integrity needs to be guaranteed, to comply with the INTEGRITY_REST_02 security pattern (see <a target="blank" href="https://italia.github.io/eid-wallet-it-docs/versione-corrente/en/e-service-pdnd.html">e-Service PDND</a>). <a target="blank" href="https://jwt.io/#debugger-io?token=ew0KICAiYWxnIjogIkVTMjU2IiwNCiAgImtpZCI6ICJhMWY1YzhkMi00YjM3LTRlOTEtYjBkMi03OWUzZjBjNGE4ZWYiLA0KICAidHlwIjogIkpXVCINCn0.ew0KICAiaXNzIjogIjEyMzRhYmNkLWVmNTYtZ2g3OC1pOWowLWtsbW5vcHFyc3R3eCIsDQogICJzdWIiOiAiMTIzNGFiY2QtZWY1Ni1naDc4LWk5ajAta2xtbm9wcXJzdHd4IiwNCiAgImF1ZCI6ICJodHRwczovL2ZydWl0b3JlLmV4YW1wbGUvZW50ZS1leGFtcGxlL3YxIiwNCiAgImlhdCI6IDE3MzMzOTc4NDAsDQogICJuYmYiOiAxNzMzNDAxNjI4LA0KICAiZXhwIjogMTczMzQwMTQ0MCwNCiAgImp0aSI6ICI4ZTEyZjRiNy05YzNhLTRmODMtOWI4ZC01MWEyYzdmNmU5ZDQiLA0KICAic2lnbmVkX2hlYWRlcnMiOiBbDQogICAgew0KICAgICAgImRpZ2VzdCI6ICJTSEEtMjU2PTc5YTIwYTc0NDMzNjQyMDMwMTgzMDYwMGFkOWJkY2E5OTM1OTNmODc2MjA5YTAwNGI1OTliNTgzMDk1YjBhNjEiDQogICAgfSwNCiAgICB7DQogICAgICAiY29udGVudC10eXBlIjogImFwcGxpY2F0aW9uL2pzb24iDQogICAgfQ0KICBdDQp9.DpuBNo2UgQhL7WLin4mpdZrbIpQq3tPvCX6HfktkxG7L5mk6a8OK1Hg0mQcZfFi3gelS-aL9kFS-6MoSy4csBg">EXAMPLE
136              required: true
137              schema:
138                type: string
139            Digest:
140              description: Digest of the message payload, to comply with the INTEGRITY_REST_02 security pattern. According to RFC 3230 Section 4.2 <a target="blank" href="https://www.rfc-editor.org/rfc/rfc3230.html#section-4.2">RFC 3230 §4.2</a>, the format MUST be the following digest-algorithm=encoded digest output.
141              required: true
142              schema:
143                type: string
144                example: SHA-256=79a20a744336420301830600ad9bdca993593f876209a004b599b583095b0a61
145            Cache-Control:
146              $ref: "#/components/headers/CacheControlHeader"
147            RateLimit-Limit:
148              $ref: "#/components/headers/RateLimitLimitHeader"
149            RateLimit-Remaining:
150              $ref: "#/components/headers/RateLimitRemainingHeader"
151            RateLimit-Reset:
152              $ref: "#/components/headers/RateLimitResetHeader"
153          content:
154            application/json:
155              schema:
156                $ref: "#/components/schemas/EServiceResponse"
157        "400":
158          description: Bad Request
159          content:
160            application/problem+json:
161              schema:
162                $ref: "#/components/schemas/ProblemDetails"
163          headers:
164            RateLimit-Limit:
165              $ref: "#/components/headers/RateLimitLimitHeader"
166            RateLimit-Remaining:
167              $ref: "#/components/headers/RateLimitRemainingHeader"
168            RateLimit-Reset:
169              $ref: "#/components/headers/RateLimitResetHeader"
170        "401":
171          description: Unauthorized
172          content:
173            application/problem+json:
174              schema:
175                $ref: "#/components/schemas/ProblemDetails"
176          headers:
177            RateLimit-Limit:
178              $ref: "#/components/headers/RateLimitLimitHeader"
179            RateLimit-Remaining:
180              $ref: "#/components/headers/RateLimitRemainingHeader"
181            RateLimit-Reset:
182              $ref: "#/components/headers/RateLimitResetHeader"
183            WWW-Authenticate:
184              $ref: "#/components/headers/WWWAuthenticateHeader"
185        "404":
186          description: Wallet Instance identifiers not found
187          content:
188            application/problem+json:
189              schema:
190                $ref: "#/components/schemas/ProblemDetails"
191          headers:
192            RateLimit-Limit:
193              $ref: "#/components/headers/RateLimitLimitHeader"
194            RateLimit-Remaining:
195              $ref: "#/components/headers/RateLimitRemainingHeader"
196            RateLimit-Reset:
197              $ref: "#/components/headers/RateLimitResetHeader"
198        "429":
199          description: Too Many Requests
200          content:
201            application/problem+json:
202              schema:
203                $ref: "#/components/schemas/ProblemDetails"
204          headers:
205            RateLimit-Limit:
206              $ref: "#/components/headers/RateLimitLimitHeader"
207            RateLimit-Remaining:
208              $ref: "#/components/headers/RateLimitRemainingHeader"
209            RateLimit-Reset:
210              $ref: "#/components/headers/RateLimitResetHeader"
211        "500":
212          description: Internal Server Error.
213          content:
214            application/problem+json:
215              schema:
216                $ref: "#/components/schemas/ProblemDetails"
217          headers:
218            Retry-After:
219              $ref: "#/components/headers/RetryAfterHeader"
220        "503":
221          description: Service Unavailable
222          content:
223            application/problem+json:
224              schema:
225                $ref: "#/components/schemas/ProblemDetails"
226          headers:
227            Retry-After:
228              $ref: "#/components/headers/RetryAfterHeader"
229
230tags:
231  - name: status
232    description: Endpoint di health check dell'API.
233  - name: instance
234    description: Retrieve information about the user's death.
235
236components:
237  securitySchemes:
238    DPoPVoucherAuth:
239      type: http
240      scheme: DPoP
241      description: >-
242        PDND Voucher issued with DPoP binding (POP_DPoP, RFC 9449). The
243        `Authorization` header MUST be `DPoP <voucher>` (`token_type` is `DPoP`).
244        This scheme MUST be used together with `DPoPProof`. It MUST NOT be
245        modelled as HTTP Bearer: a conformant Provider rejects
246        `Authorization: Bearer` for a DPoP-bound Voucher.
247    DPoPProof:
248      type: apiKey
249      in: header
250      name: DPoP
251      description: >-
252        DPoP proof JWT (RFC 9449). REQUIRED together with `DPoPVoucherAuth`
253        (POP_DPoP). MUST NOT be sent with `BearerAuth` (POP_TPoP), where proof
254        of possession is `Agid-JWT-TrackingEvidence`.
255    BearerAuth:
256      type: http
257      scheme: bearer
258      bearerFormat: JWT
259      description: >-
260        PDND Voucher issued as Bearer (POP_TPoP). The `Authorization` header
261        MUST be `Bearer <voucher>` (`token_type` is `Bearer`). This scheme MUST
262        be used together with `TrackingEvidenceAuth` as proof of possession.
263        This is REST_JWS_2021_POP via TrackingEvidence, not REST_JWS_2021_Bearer.
264    TrackingEvidenceAuth:
265      type: apiKey
266      in: header
267      name: Agid-JWT-TrackingEvidence
268      description: >-
269        TrackingEvidence JWT. REQUIRED together with `BearerAuth` (POP_TPoP) as
270        proof of possession of the PDND Voucher. The same header is also an
271        optional operation parameter, so it MAY be sent with the POP_DPoP pair
272        (`DPoPVoucherAuth` + `DPoPProof`) when the Provider requires
273        AUDIT_REST_02. The DPoP proof remains the proof of possession.
274        See e-Service PDND in the Technical Specifications.
275
276  headers:
277    CacheControlHeader:
278      schema:
279        type: string
280        enum:
281          - no-store
282      description: no-store
283    RateLimitLimitHeader:
284      schema:
285        type: integer
286        format: int32
287        minimum: 0
288      description: Maximum number of requests within the time window.
289    RateLimitRemainingHeader:
290      schema:
291        type: integer
292        format: int32
293        minimum: 0
294      description: Remaining requests within the time window.
295    RateLimitResetHeader:
296      schema:
297        type: integer
298        format: int32
299        minimum: 0
300      description: UTC epoch in seconds, corresponding to when the window for the current rate limit will reset.
301    RetryAfterHeader:
302      schema:
303        type: integer
304        format: int32
305        minimum: 0
306      description: Seconds to wait before receiving another response.
307    WWWAuthenticateHeader:
308      schema:
309        type: string
310        example: >-
311          Bearer error="invalid_token", error_description="The access token expired"
312      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.
313
314  schemas:
315    EServiceResponse:
316      properties:
317        result:
318          type: object
319          properties:
320            revoked:
321              type: array
322              items:
323                type: string
324              description: List of Wallet Instances successfully rekoved.
325            not_found:
326              type: array
327              items:
328                type: string
329              description: List of Wallet Instances not revoked as their identifier were not found at the Wallet Provider.
330            already_revoked:
331              type: array
332              items:
333                type: string
334              description: List of Wallet Instances that were already revoked by the Wallet Provider.
335          required: [revoked, not_found, already_revoked]
336          description: >-
337            JSON object specifying which Wallet Instance was successfully revoked, which was already revoked and which was not found.
338        result_description:
339          description: Response Description.
340          type: string
341          example: The service partially process the revocation of the requested Wallet Instances as some identifiers were not found.
342          required: [result, result_description]
343    ProblemDetails:
344      type: object
345      description: RFC7807-compliant problem details object for error responses.
346      properties:
347        type:
348          type: string
349          format: uri
350          description: An absolute URI that identifies the problem type.
351        title:
352          type: string
353          description: A short, human-readable summary of the problem type.
354        status:
355          type: integer
356          format: int32
357          description: The HTTP status code generated by the origin server for this occurrence of the problem.
358        detail:
359          type: string
360          description: A human-readable explanation specific to this occurrence of the problem.
361        instance:
362          type: string
363          format: uri
364          description: An absolute URI that identifies the specific occurrence of the problem.
365      required: [title, status, detail]
366    NotifyUserDeath:
367      required:
368        - wallet_instance_ids
369      type: object
370      properties:
371        wallet_instance_ids:
372          type: array
373          items:
374            type: string
375          description: >-
376            Identifiers of the Wallet Instances whose PID was revoked due to User death.