20.5. Specifica OpenAPI del Credential Issuer PDND

Di seguito è riportata la specifica Open API completa per i servizi elettronici del Credential Issuer PDND:

  1openapi: 3.0.1
  2info:
  3  title: IT Wallet API - Credential Issuer web services
  4  version: 0.2.0
  5  description: IT Wallet Credential Issuer e-Service exposed via PDND.
  6  termsOfService: "https://credential-issuer.example.it/tos/"
  7  contact:
  8    name: IT-Wallet <credential_issuer>
  9    url: https://github.com/italia/eid-wallet-it-docs
 10  x-api-id: CISSITW-01
 11  x-summary: IT-Wallet Credential Issuer API.
 12servers:
 13  - url: https://test.credential-issuer.example.it/v0.2.0
 14    description: Credential Issuer API test server
 15  - url: https://credential-issuer.example.it/v0.2.0
 16    description: Credential Issuer API production server
 17
 18paths:
 19  /status:
 20    get:
 21      tags:
 22        - status
 23      summary: Get Credential Issuer API status.
 24      description: Health-check endpoint that returns the operational status of the Credential Issuer API.
 25      operationId: credentialIssuerStatus
 26      responses:
 27        "200":
 28          description: Service available
 29          content:
 30            application/problem+json:
 31              schema:
 32                $ref: "#/components/schemas/ProblemDetails"
 33          headers:
 34            Cache-Control:
 35              $ref: "#/components/headers/CacheControlHeader"
 36            RateLimit-Limit:
 37              $ref: "#/components/headers/RateLimitLimitHeader"
 38            RateLimit-Remaining:
 39              $ref: "#/components/headers/RateLimitRemainingHeader"
 40            RateLimit-Reset:
 41              $ref: "#/components/headers/RateLimitResetHeader"
 42        "429":
 43          description: Too Many Requests
 44          content:
 45            application/problem+json:
 46              schema:
 47                $ref: "#/components/schemas/ProblemDetails"
 48          headers:
 49            RateLimit-Limit:
 50              $ref: "#/components/headers/RateLimitLimitHeader"
 51            RateLimit-Remaining:
 52              $ref: "#/components/headers/RateLimitRemainingHeader"
 53            RateLimit-Reset:
 54              $ref: "#/components/headers/RateLimitResetHeader"
 55        "503":
 56          description: Service Unavailable
 57          content:
 58            application/problem+json:
 59              schema:
 60                $ref: "#/components/schemas/ProblemDetails"
 61          headers:
 62            Retry-After:
 63              $ref: "#/components/headers/RetryAfterHeader"
 64
 65  /wallet-report/{api}:
 66    get:
 67      tags:
 68        - stats
 69      summary: Get Statistics
 70      description: This service returns statistical data on issued Digital Credentials
 71      operationId: walletGetReport
 72      parameters:
 73        - name: api
 74          in: path
 75          required: true
 76          schema:
 77            type: string
 78        - name: typesCredentials
 79          in: query
 80          required: false
 81          schema:
 82            type: array
 83            items:
 84              type: string
 85        - name: typeData
 86          in: query
 87          required: false
 88          schema:
 89            type: string
 90        - name: fromData
 91          in: query
 92          required: false
 93          schema:
 94            type: string
 95            format: date-time
 96        - name: toData
 97          in: query
 98          required: false
 99          schema:
100            type: string
101            format: date-time
102        - name: Digest
103          in: header
104          description: >-
105            Digest of the message payload, to comply with the INTEGRITY_REST_02
106            security pattern. According to <a target="blank" href="https://www.rfc-editor.org/rfc/rfc3230.html#section-4.2">RFC
107            3230 §4.2</a>, the format MUST be the following: digest-algorithm=encoded
108            digest output.
109          required: true
110          schema:
111            type: string
112            example: SHA-256=72e18bdddf13c911b4dd562ee21979a5c9f235c3a01bd1426e857d8c1a282f41
113        - name: Agid-JWT-TrackingEvidence
114          in: header
115          description: >-
116            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
117            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"
118            href="https://italia.github.io/eid-wallet-it-docs/versione-corrente/en/e-service-pdnd.html">e-Service PDND</a>). <br/><br/>
119            <a target="blank" href="https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImV4cCI6MTczMzA1MjYwMCwibmJmIjoxNzMzMDM2NDUwLCJpYXQiOjE3MzMwMzY0MDAsImp0aSI6ImE0YjVjNmQ3LWU4ZjktYWJjZC1lZjEyLTM0NTY3ODkwMTIzNCIsImRub25jZSI6NjUyODQyNDIxMzY4NSwicHVycG9zZUlkIjoiYjJjM2Q0ZTUtZjZnNy1oOGk5LWowazEtbG1ubzEyMzQ1Njc4IiwidXNlcklEIjoiYThiN2M2ZDUtZTRmMy1nMmgxLWk5ajAta2xtbm9wcXJzdHV2IiwibG9hIjoic3Vic3RhbnRpYWwifQ.y42yfMeW2H9h0b0j0BODUml8yF20stY9q3BwoVU5BB90afBj852Q0QlInncdhjXhUjLS1V76cGBxkutDNvxRNA">EXAMPLE
120            ON JWT.IO</a>
121          required: false
122          schema:
123            type: string
124            format: JWT
125            example: eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImV4cCI6MTczMzA1MjYwMCwibmJmIjoxNzMzMDM2NDUwLCJpYXQiOjE3MzMwMzY0MDAsImp0aSI6ImE0YjVjNmQ3LWU4ZjktYWJjZC1lZjEyLTM0NTY3ODkwMTIzNCIsImRub25jZSI6NjUyODQyNDIxMzY4NSwicHVycG9zZUlkIjoiYjJjM2Q0ZTUtZjZnNy1oOGk5LWowazEtbG1ubzEyMzQ1Njc4IiwidXNlcklEIjoiYThiN2M2ZDUtZTRmMy1nMmgxLWk5ajAta2xtbm9wcXJzdHV2IiwibG9hIjoic3Vic3RhbnRpYWwifQ.y42yfMeW2H9h0b0j0BODUml8yF20stY9q3BwoVU5BB90afBj852Q0QlInncdhjXhUjLS1V76cGBxkutDNvxRNA
126        - name: DPoP
127          in: header
128          description: Use only if the DPoP voucher has been requested from PDND.
129          schema:
130            type: string
131            format: JWT
132          required: false
133        - name: Agid-JWT-Signature
134          in: header
135          description: >-
136            JWT containing the signature of the message headers whose integrity
137            needs to be guaranteed, to comply with the INTEGRITY_REST_02
138            security pattern (see <a target="blank"
139            href="https://italia.github.io/eid-wallet-it-docs/versione-corrente/en/e-service-pdnd.html">e-Service PDND</a>). <br/><br/>
140
141            <a target="blank" href="https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJzdWIiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImlhdCI6MTczMzM5Nzg0MCwibmJmIjoxNzMzNDAxNjI4LCJleHAiOjE3MzM0MDE0NDAsImp0aSI6ImQzZjdiMmM5LTI3NGEtNDJiNy04ZjhkLTJlOWQ4YjE3MzRiMCIsInNpZ25lZF9oZWFkZXJzIjpbeyJkaWdlc3QiOiJTSEEtMjU2PTcyZTE4YmRkZGYxM2M5MTFiNGRkNTYyZWUyMTk3OWE1YzlmMjM1YzNhMDFiZDE0MjZlODU3ZDhjMWEyODJmNDEifSx7ImNvbnRlbnQtdHlwZSI6ImFwcGxpY2F0aW9uL2pzb24ifV19.tG5-P96CCA6N1IYC-xk4GumoVkA3NFolpbBn2vQ2e9vpWQ8f5Sm2l4-1VrXfKTx-CUVz_puiwqkBhulrNKj2fA">EXAMPLE
142            ON JWT.IO</a>
143          required: true
144          schema:
145            type: string
146            format: JWT
147            example: eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJzdWIiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImlhdCI6MTczMzM5Nzg0MCwibmJmIjoxNzMzNDAxNjI4LCJleHAiOjE3MzM0MDE0NDAsImp0aSI6ImQzZjdiMmM5LTI3NGEtNDJiNy04ZjhkLTJlOWQ4YjE3MzRiMCIsInNpZ25lZF9oZWFkZXJzIjpbeyJkaWdlc3QiOiJTSEEtMjU2PTcyZTE4YmRkZGYxM2M5MTFiNGRkNTYyZWUyMTk3OWE1YzlmMjM1YzNhMDFiZDE0MjZlODU3ZDhjMWEyODJmNDEifSx7ImNvbnRlbnQtdHlwZSI6ImFwcGxpY2F0aW9uL2pzb24ifV19.tG5-P96CCA6N1IYC-xk4GumoVkA3NFolpbBn2vQ2e9vpWQ8f5Sm2l4-1VrXfKTx-CUVz_puiwqkBhulrNKj2fA
148      security:
149        - BearerAuth: []
150        - DPoPAuth: []
151      responses:
152        "200":
153          description: 200 OK
154          headers:
155            Agid-JWT-Signature:
156              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
157              required: true
158              schema:
159                type: string
160            Digest:
161              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.
162              required: true
163              schema:
164                type: string
165                example: SHA-256=79a20a744336420301830600ad9bdca993593f876209a004b599b583095b0a61
166            Cache-Control:
167              $ref: "#/components/headers/CacheControlHeader"
168            RateLimit-Limit:
169              $ref: "#/components/headers/RateLimitLimitHeader"
170            RateLimit-Remaining:
171              $ref: "#/components/headers/RateLimitRemainingHeader"
172            RateLimit-Reset:
173              $ref: "#/components/headers/RateLimitResetHeader"
174          content:
175            application/json:
176              schema:
177                $ref: "#/components/schemas/ResponseReport"
178        "400":
179          description: Bad Request
180          content:
181            application/problem+json:
182              schema:
183                $ref: "#/components/schemas/ProblemDetails"
184          headers:
185            RateLimit-Limit:
186              $ref: "#/components/headers/RateLimitLimitHeader"
187            RateLimit-Remaining:
188              $ref: "#/components/headers/RateLimitRemainingHeader"
189            RateLimit-Reset:
190              $ref: "#/components/headers/RateLimitResetHeader"
191        "401":
192          description: Unauthorized
193          content:
194            application/problem+json:
195              schema:
196                $ref: "#/components/schemas/ProblemDetails"
197          headers:
198            RateLimit-Limit:
199              $ref: "#/components/headers/RateLimitLimitHeader"
200            RateLimit-Remaining:
201              $ref: "#/components/headers/RateLimitRemainingHeader"
202            RateLimit-Reset:
203              $ref: "#/components/headers/RateLimitResetHeader"
204            WWW-Authenticate:
205              $ref: "#/components/headers/WWWAuthenticateHeader"
206        "429":
207          description: Too Many Requests
208          content:
209            application/problem+json:
210              schema:
211                $ref: "#/components/schemas/ProblemDetails"
212          headers:
213            RateLimit-Limit:
214              $ref: "#/components/headers/RateLimitLimitHeader"
215            RateLimit-Remaining:
216              $ref: "#/components/headers/RateLimitRemainingHeader"
217            RateLimit-Reset:
218              $ref: "#/components/headers/RateLimitResetHeader"
219        "500":
220          description: Internal Server Error.
221          content:
222            application/problem+json:
223              schema:
224                $ref: "#/components/schemas/ProblemDetails"
225          headers:
226            Retry-After:
227              $ref: "#/components/headers/RetryAfterHeader"
228        "503":
229          description: Service Unavailable
230          content:
231            application/problem+json:
232              schema:
233                $ref: "#/components/schemas/ProblemDetails"
234          headers:
235            Retry-After:
236              $ref: "#/components/headers/RetryAfterHeader"
237
238tags:
239  - name: status
240    description: Endpoint di health check dell'API.
241  - name: stats
242    description: Statistical data on issued Digital Credentials.
243
244components:
245  securitySchemes:
246    BearerAuth:
247      type: http
248      scheme: bearer
249      bearerFormat: JWT
250      description: PDND Bearer Token
251    DPoPAuth:
252      type: apiKey
253      in: header
254      name: DPoP
255      description: DPoP proof JWT (RFC 9449).
256
257  headers:
258    CacheControlHeader:
259      schema:
260        type: string
261        enum:
262          - no-store
263      description: no-store
264    RateLimitLimitHeader:
265      schema:
266        type: integer
267        format: int32
268        minimum: 0
269      description: Maximum number of requests within the time window.
270    RateLimitRemainingHeader:
271      schema:
272        type: integer
273        format: int32
274        minimum: 0
275      description: Remaining requests within the time window.
276    RateLimitResetHeader:
277      schema:
278        type: integer
279        format: int32
280        minimum: 0
281      description: UTC epoch in seconds, corresponding to when the window for the current rate limit will reset.
282    RetryAfterHeader:
283      schema:
284        type: integer
285        format: int32
286        minimum: 0
287      description: Seconds to wait before receiving another response.
288    WWWAuthenticateHeader:
289      schema:
290        type: string
291        example: >-
292          Bearer error="invalid_token", error_description="The access token expired"
293      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.
294
295  schemas:
296    ProblemDetails:
297      type: object
298      description: RFC7807-compliant problem details object for error responses.
299      properties:
300        type:
301          type: string
302          format: uri
303          description: An absolute URI that identifies the problem type.
304        title:
305          type: string
306          description: A short, human-readable summary of the problem type.
307        status:
308          type: integer
309          format: int32
310          description: The HTTP status code generated by the origin server for this occurrence of the problem.
311        detail:
312          type: string
313          description: A human-readable explanation specific to this occurrence of the problem.
314        instance:
315          type: string
316          format: uri
317          description: An absolute URI that identifies the specific occurrence of the problem.
318      required: [title, status, detail]
319    ResponseReport:
320      type: object
321      properties:
322        countEid:
323          type: integer
324          format: int64
325        count:
326          type: integer
327          format: int64
328        countPid:
329          $ref: "#/components/schemas/TotalCountCredential"
330        countMdl:
331          $ref: "#/components/schemas/TotalCountCredential"
332        countEdc:
333          $ref: "#/components/schemas/TotalCountCredential"
334        countTeam:
335          $ref: "#/components/schemas/TotalCountCredential"
336    TotalCountCredential:
337      type: object
338      properties:
339        credEmesse:
340          type: integer
341          format: int64
342        credValide:
343          type: integer
344          format: int64
345        credInvalide:
346          type: integer
347          format: int64