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