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