20.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.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: DPoP
 74          in: header
 75          description: Use only if the DPoP voucher has been requested from PDND.
 76          schema:
 77            type: string
 78            format: JWT
 79          required: false
 80        - name: Agid-JWT-Signature
 81          in: header
 82          description: >-
 83            JWT containing the signature of the message headers whose integrity
 84            needs to be guaranteed, to comply with the INTEGRITY_REST_02
 85            security pattern (see <a target="blank"
 86            href="https://italia.github.io/eid-wallet-it-docs/versione-corrente/en/e-service-pdnd.html">e-Service PDND</a>). <br/><br/>
 87
 88            <a target="blank" href="https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJzdWIiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImlhdCI6MTczMzM5Nzg0MCwibmJmIjoxNzMzNDAxNjI4LCJleHAiOjE3MzM0MDE0NDAsImp0aSI6ImQzZjdiMmM5LTI3NGEtNDJiNy04ZjhkLTJlOWQ4YjE3MzRiMCIsInNpZ25lZF9oZWFkZXJzIjpbeyJkaWdlc3QiOiJTSEEtMjU2PTcyZTE4YmRkZGYxM2M5MTFiNGRkNTYyZWUyMTk3OWE1YzlmMjM1YzNhMDFiZDE0MjZlODU3ZDhjMWEyODJmNDEifSx7ImNvbnRlbnQtdHlwZSI6ImFwcGxpY2F0aW9uL2pzb24ifV19.tG5-P96CCA6N1IYC-xk4GumoVkA3NFolpbBn2vQ2e9vpWQ8f5Sm2l4-1VrXfKTx-CUVz_puiwqkBhulrNKj2fA">EXAMPLE
 89            ON JWT.IO</a>
 90          required: true
 91          schema:
 92            type: string
 93            format: JWT
 94            example: eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJzdWIiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImlhdCI6MTczMzM5Nzg0MCwibmJmIjoxNzMzNDAxNjI4LCJleHAiOjE3MzM0MDE0NDAsImp0aSI6ImQzZjdiMmM5LTI3NGEtNDJiNy04ZjhkLTJlOWQ4YjE3MzRiMCIsInNpZ25lZF9oZWFkZXJzIjpbeyJkaWdlc3QiOiJTSEEtMjU2PTcyZTE4YmRkZGYxM2M5MTFiNGRkNTYyZWUyMTk3OWE1YzlmMjM1YzNhMDFiZDE0MjZlODU3ZDhjMWEyODJmNDEifSx7ImNvbnRlbnQtdHlwZSI6ImFwcGxpY2F0aW9uL2pzb24ifV19.tG5-P96CCA6N1IYC-xk4GumoVkA3NFolpbBn2vQ2e9vpWQ8f5Sm2l4-1VrXfKTx-CUVz_puiwqkBhulrNKj2fA
 95        - name: Digest
 96          in: header
 97          description: >-
 98            Digest of the message payload, to comply with the INTEGRITY_REST_02
 99            security pattern. According to <a target="blank" href="https://www.rfc-editor.org/rfc/rfc3230.html#section-4.2">RFC
100            3230 §4.2</a>, the format MUST be the following: digest-algorithm=encoded
101            digest output.
102          required: true
103          schema:
104            type: string
105            example: SHA-256=72e18bdddf13c911b4dd562ee21979a5c9f235c3a01bd1426e857d8c1a282f41
106        - name: Agid-JWT-TrackingEvidence
107          in: header
108          description: >-
109            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
110            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"
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        - BearerAuth: []
121        - DPoPAuth: []
122      requestBody:
123        required: true
124        content:
125          application/merge-patch+json:
126            schema:
127              $ref: "#/components/schemas/NotifyUserDeath"
128      responses:
129        "207":
130          description: Multi-Status
131          headers:
132            Agid-JWT-Signature:
133              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
134              required: true
135              schema:
136                type: string
137            Digest:
138              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.
139              required: true
140              schema:
141                type: string
142                example: SHA-256=79a20a744336420301830600ad9bdca993593f876209a004b599b583095b0a61
143            Cache-Control:
144              $ref: "#/components/headers/CacheControlHeader"
145            RateLimit-Limit:
146              $ref: "#/components/headers/RateLimitLimitHeader"
147            RateLimit-Remaining:
148              $ref: "#/components/headers/RateLimitRemainingHeader"
149            RateLimit-Reset:
150              $ref: "#/components/headers/RateLimitResetHeader"
151          content:
152            application/json:
153              schema:
154                $ref: "#/components/schemas/EServiceResponse"
155        "400":
156          description: Bad Request
157          content:
158            application/problem+json:
159              schema:
160                $ref: "#/components/schemas/ProblemDetails"
161          headers:
162            RateLimit-Limit:
163              $ref: "#/components/headers/RateLimitLimitHeader"
164            RateLimit-Remaining:
165              $ref: "#/components/headers/RateLimitRemainingHeader"
166            RateLimit-Reset:
167              $ref: "#/components/headers/RateLimitResetHeader"
168        "401":
169          description: Unauthorized
170          content:
171            application/problem+json:
172              schema:
173                $ref: "#/components/schemas/ProblemDetails"
174          headers:
175            RateLimit-Limit:
176              $ref: "#/components/headers/RateLimitLimitHeader"
177            RateLimit-Remaining:
178              $ref: "#/components/headers/RateLimitRemainingHeader"
179            RateLimit-Reset:
180              $ref: "#/components/headers/RateLimitResetHeader"
181            WWW-Authenticate:
182              $ref: "#/components/headers/WWWAuthenticateHeader"
183        "404":
184          description: Wallet Instance identifiers not found
185          content:
186            application/problem+json:
187              schema:
188                $ref: "#/components/schemas/ProblemDetails"
189          headers:
190            RateLimit-Limit:
191              $ref: "#/components/headers/RateLimitLimitHeader"
192            RateLimit-Remaining:
193              $ref: "#/components/headers/RateLimitRemainingHeader"
194            RateLimit-Reset:
195              $ref: "#/components/headers/RateLimitResetHeader"
196        "429":
197          description: Too Many Requests
198          content:
199            application/problem+json:
200              schema:
201                $ref: "#/components/schemas/ProblemDetails"
202          headers:
203            RateLimit-Limit:
204              $ref: "#/components/headers/RateLimitLimitHeader"
205            RateLimit-Remaining:
206              $ref: "#/components/headers/RateLimitRemainingHeader"
207            RateLimit-Reset:
208              $ref: "#/components/headers/RateLimitResetHeader"
209        "500":
210          description: Internal Server Error.
211          content:
212            application/problem+json:
213              schema:
214                $ref: "#/components/schemas/ProblemDetails"
215          headers:
216            Retry-After:
217              $ref: "#/components/headers/RetryAfterHeader"
218        "503":
219          description: Service Unavailable
220          content:
221            application/problem+json:
222              schema:
223                $ref: "#/components/schemas/ProblemDetails"
224          headers:
225            Retry-After:
226              $ref: "#/components/headers/RetryAfterHeader"
227
228tags:
229  - name: status
230    description: Endpoint di health check dell'API.
231  - name: instance
232    description: Retrieve information about the user's death.
233
234components:
235  securitySchemes:
236    BearerAuth:
237      type: http
238      scheme: bearer
239      bearerFormat: JWT
240      description: PDND Bearer Token
241    DPoPAuth:
242      type: apiKey
243      in: header
244      name: DPoP
245      description: DPoP proof JWT (RFC 9449).
246
247  headers:
248    CacheControlHeader:
249      schema:
250        type: string
251        enum:
252          - no-store
253      description: no-store
254    RateLimitLimitHeader:
255      schema:
256        type: integer
257        format: int32
258        minimum: 0
259      description: Maximum number of requests within the time window.
260    RateLimitRemainingHeader:
261      schema:
262        type: integer
263        format: int32
264        minimum: 0
265      description: Remaining requests within the time window.
266    RateLimitResetHeader:
267      schema:
268        type: integer
269        format: int32
270        minimum: 0
271      description: UTC epoch in seconds, corresponding to when the window for the current rate limit will reset.
272    RetryAfterHeader:
273      schema:
274        type: integer
275        format: int32
276        minimum: 0
277      description: Seconds to wait before receiving another response.
278    WWWAuthenticateHeader:
279      schema:
280        type: string
281        example: >-
282          Bearer error="invalid_token", error_description="The access token expired"
283      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.
284
285  schemas:
286    EServiceResponse:
287      properties:
288        result:
289          type: object
290          properties:
291            revoked:
292              type: array
293              items:
294                type: string
295              description: List of Wallet Instances successfully rekoved.
296            not_found:
297              type: array
298              items:
299                type: string
300              description: List of Wallet Instances not revoked as their identifier were not found at the Wallet Provider.
301            already_revoked:
302              type: array
303              items:
304                type: string
305              description: List of Wallet Instances that were already revoked by the Wallet Provider.
306          required: [revoked, not_found, already_revoked]
307          description: >-
308            JSON object specifying which Wallet Instance was successfully revoked, which was already revoked and which was not found.
309        result_description:
310          description: Response Description.
311          type: string
312          example: The service partially process the revocation of the requested Wallet Instances as some identifiers were not found.
313          required: [result, result_description]
314    ProblemDetails:
315      type: object
316      description: RFC7807-compliant problem details object for error responses.
317      properties:
318        type:
319          type: string
320          format: uri
321          description: An absolute URI that identifies the problem type.
322        title:
323          type: string
324          description: A short, human-readable summary of the problem type.
325        status:
326          type: integer
327          format: int32
328          description: The HTTP status code generated by the origin server for this occurrence of the problem.
329        detail:
330          type: string
331          description: A human-readable explanation specific to this occurrence of the problem.
332        instance:
333          type: string
334          format: uri
335          description: An absolute URI that identifies the specific occurrence of the problem.
336      required: [title, status, detail]
337    NotifyUserDeath:
338      required:
339        - wallet_instance_ids
340      type: object
341      properties:
342        wallet_instance_ids:
343          type: array
344          items:
345            type: string
346          description: >-
347            Identifiers of the Wallet Instances whose PID was revoked due to User death.