15.5. Authentic Source PDND OpenAPI Specification¶
Below is the complete Open API Specification for the Authentic Source PDND e-services:
1openapi: 3.0.1
2info:
3 title: IT Wallet API - AS web services
4 version: 0.1.0
5servers:
6 - url: https://authentic-source.example.it
7 description: Authentic Source API
8paths:
9 /v0.9.0/AttributeClaims/{attribute_type}:
10 post:
11 tags:
12 - e-Services PDND
13 summary: Get Attribute Claims
14 description: >-
15 This service provides the Credential Issuer with all attribute claims necessary for the issuance of a Digital Credential
16 operationId: attributeClaims
17 parameters:
18 - name: attribute_type
19 in: path
20 required: true
21 description: Identifier of attribute claims set
22 schema:
23 type: string
24 example: PersonIdentificationData
25 - name: Authorization
26 in: header
27 description: >-
28 JWT token obtained from <a target="blank"
29 href="https://italia.github.io/eid-wallet-it-docs/v1.0.0/en/e-service-pdnd.html#voucher-issuance">PDND
30 Interoperabilità</a>. Based on the implementation choices, it can be either Bearer or DPoP.<br/><br/><a target="blank"
31 href="https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImtpZCI6ImI4MzlmNGM3LTFlNWQtNGE4YS05ZmM2LTcyZDNiN2YwOTFlYyIsInR5cCI6ImF0K2p3dCJ9.eyJpc3MiOiJodHRwczovL2ludGVyb3AucGFnb3BhLml0Iiwic3ViIjoiODI5MTRiM2YtNjBiMi00NTI5LWI0ZDYtM2Q0ZTY3ZjBhOTMzIiwiYXVkIjoiaHR0cHM6Ly9hdXRoZW50aWMtc291cmNlLmV4YW1wbGUuaXQiLCJleHAiOjE3MzMwNDIxNTAsIm5iZiI6MTczMzA0MTk0NSwiaWF0IjoxNzMzMDQxOTIwLCJqdGkiOiJjNGY1ZDdlMi1iN2M4LTQwZjYtOWI2YS1kYzlhNGY1YWViNTciLCJjbGllbnRfaWQiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJwdXJwb3NlSWQiOiJkMmI5YTY1My1jNDk3LTQ1YzYtYjhmMS01YmRmMTI0YzlkM2EiLCJkaWdlc3QiOnsiYWxnIjoiU0hBMjU2IiwidmFsdWUiOiI5Yzc4OTRhMGE1YTkxMDU4MGI5NjdmMzg0Y2RmYmExN2IxYWI2Zjg2NjcwZTViMGRmMThhMGM0NTNiNWViMjE1In0sImNuZiI6eyJqa3QiOiI4NTJkMzE5OWJkMGUzOThlYTBjOWMyYTA3NzZjYTMzNjYyOGU4NzBhZWM3YWMwYTQxOGFkYTNlNmNlMTY0ZjhkIn19.SqKCkZyv78VfaTZzOh6iYfKdGirSrPGMvqCMZE9DFXmzhaYz5lpp-fGRjmDbj88Qrw6U_3nl5WUBUjbjxpYxAQ">EXAMPLE
32 ON JWT.IO</a>
33 required: true
34 schema:
35 type: string
36 format: Signed JWT
37 example: >-
38 DPoP
39 eyJhbGciOiJFUzI1NiIsImtpZCI6ImI4MzlmNGM3LTFlNWQtNGE4YS05ZmM2LTcyZDNiN2YwOTFlYyIsInR5cCI6ImF0K2p3dCJ9.eyJpc3MiOiJodHRwczovL2ludGVyb3AucGFnb3BhLml0Iiwic3ViIjoiODI5MTRiM2YtNjBiMi00NTI5LWI0ZDYtM2Q0ZTY3ZjBhOTMzIiwiYXVkIjoiaHR0cHM6Ly9hdXRoZW50aWMtc291cmNlLmV4YW1wbGUuaXQiLCJleHAiOjE3MzMwNDIxNTAsIm5iZiI6MTczMzA0MTk0NSwiaWF0IjoxNzMzMDQxOTIwLCJqdGkiOiJjNGY1ZDdlMi1iN2M4LTQwZjYtOWI2YS1kYzlhNGY1YWViNTciLCJjbGllbnRfaWQiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJwdXJwb3NlSWQiOiJkMmI5YTY1My1jNDk3LTQ1YzYtYjhmMS01YmRmMTI0YzlkM2EiLCJkaWdlc3QiOnsiYWxnIjoiU0hBMjU2IiwidmFsdWUiOiI5Yzc4OTRhMGE1YTkxMDU4MGI5NjdmMzg0Y2RmYmExN2IxYWI2Zjg2NjcwZTViMGRmMThhMGM0NTNiNWViMjE1In0sImNuZiI6eyJqa3QiOiI4NTJkMzE5OWJkMGUzOThlYTBjOWMyYTA3NzZjYTMzNjYyOGU4NzBhZWM3YWMwYTQxOGFkYTNlNmNlMTY0ZjhkIn19.SqKCkZyv78VfaTZzOh6iYfKdGirSrPGMvqCMZE9DFXmzhaYz5lpp-fGRjmDbj88Qrw6U_3nl5WUBUjbjxpYxAQ
40 - name: DPoP
41 in: header
42 description: >-
43 DPoP proof JWT, to comply with the REST_JWS_2021_POP security
44 pattern using the POP_DPoP implementation. See also <a target="blank"
45 href="https://datatracker.ietf.org/doc/html/rfc9449.html">RFC
46 9449</a>.<br/><br/>
47
48 <a target="blank" href="https://jwt.io/#debugger-io?token=eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6IkVDIiwia2V5X29wcyI6WyJzaWduIl0sImtpZCI6IjM5ZmE5NjBiLTc3M2YtNDllZi04YTBlLWU3NzNlOWI5N2FlOCIsImNydiI6IlAtMjU2IiwieCI6Imh1eVhJUU52OTAyb0xzcFg0X3pvbkM5NEc2eUVsbjZsc2RtLTF3TTczMm8iLCJ5IjoiSTlQREVhd1dIcWFGREd4MVprTmstMlBWNldkcGNhSDNBZk9iQlNMaWhndyJ9fQ.eyJqdGkiOiIyYzc2ZmNhMy1jYjRlLTQzMTItOGI2ZS05NzQ5NDYyZjQyMGQiLCJodG0iOiJQT1NUIiwiYXRoIjoiNDc1MmMzMmQ2YzQ4NzYzZjBmMzljZDNkYzk5ZDJlOTk3OTMyYmFmMzc1NjNiYzVhODk5NDg3YTZmODZlNWIxZCIsImh0dSI6Imh0dHBzOi8vYXV0aGVudGljLXNvdXJjZS5leGFtcGxlLml0IiwiaWF0IjoxNzYyMjYyNjE2fQ.Mdayqq66hFzMFvN131WRZ_dxyaEu7W1Qz-ksYt6-RLGD1rCixnmnmFnNOsgFT_wztGL1zJloYTMgn9Ys6lSxgQ">EXAMPLE
49 ON JWT.IO</a>
50 required: false
51 schema:
52 type: string
53 format: JWT
54 example: >-
55 eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6IkVDIiwia2V5X29wcyI6WyJzaWduIl0sImtpZCI6IjM5ZmE5NjBiLTc3M2YtNDllZi04YTBlLWU3NzNlOWI5N2FlOCIsImNydiI6IlAtMjU2IiwieCI6Imh1eVhJUU52OTAyb0xzcFg0X3pvbkM5NEc2eUVsbjZsc2RtLTF3TTczMm8iLCJ5IjoiSTlQREVhd1dIcWFGREd4MVprTmstMlBWNldkcGNhSDNBZk9iQlNMaWhndyJ9fQ.eyJqdGkiOiIyYzc2ZmNhMy1jYjRlLTQzMTItOGI2ZS05NzQ5NDYyZjQyMGQiLCJodG0iOiJQT1NUIiwiYXRoIjoiNDc1MmMzMmQ2YzQ4NzYzZjBmMzljZDNkYzk5ZDJlOTk3OTMyYmFmMzc1NjNiYzVhODk5NDg3YTZmODZlNWIxZCIsImh0dSI6Imh0dHBzOi8vYXV0aGVudGljLXNvdXJjZS5leGFtcGxlLml0IiwiaWF0IjoxNzYyMjYyNjE2fQ.Mdayqq66hFzMFvN131WRZ_dxyaEu7W1Qz-ksYt6-RLGD1rCixnmnmFnNOsgFT_wztGL1zJloYTMgn9Ys6lSxgQ
56 - name: Agid-JWT-Signature
57 in: header
58 description: >-
59 JWT containing the signature of the message headers whose integrity
60 needs to be guaranteed, to comply with the INTEGRITY_REST_02
61 security pattern (see <a target="blank"
62 href="https://italia.github.io/eid-wallet-it-docs/v1.0.0/en/e-service-pdnd.html">e-Service PDND</a>). <br/><br/>
63
64 <a target="blank" href="https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJzdWIiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImlhdCI6MTczMzM5Nzg0MCwibmJmIjoxNzMzNDAxNjI4LCJleHAiOjE3MzM0MDE0NDAsImp0aSI6ImQzZjdiMmM5LTI3NGEtNDJiNy04ZjhkLTJlOWQ4YjE3MzRiMCIsInNpZ25lZF9oZWFkZXJzIjpbeyJkaWdlc3QiOiJTSEEtMjU2PTcyZTE4YmRkZGYxM2M5MTFiNGRkNTYyZWUyMTk3OWE1YzlmMjM1YzNhMDFiZDE0MjZlODU3ZDhjMWEyODJmNDEifSx7ImNvbnRlbnQtdHlwZSI6ImFwcGxpY2F0aW9uL2pzb24ifV19.tG5-P96CCA6N1IYC-xk4GumoVkA3NFolpbBn2vQ2e9vpWQ8f5Sm2l4-1VrXfKTx-CUVz_puiwqkBhulrNKj2fA">EXAMPLE
65 ON JWT.IO</a>
66 required: true
67 schema:
68 type: string
69 format: JWT
70 example: eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJzdWIiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImlhdCI6MTczMzM5Nzg0MCwibmJmIjoxNzMzNDAxNjI4LCJleHAiOjE3MzM0MDE0NDAsImp0aSI6ImQzZjdiMmM5LTI3NGEtNDJiNy04ZjhkLTJlOWQ4YjE3MzRiMCIsInNpZ25lZF9oZWFkZXJzIjpbeyJkaWdlc3QiOiJTSEEtMjU2PTcyZTE4YmRkZGYxM2M5MTFiNGRkNTYyZWUyMTk3OWE1YzlmMjM1YzNhMDFiZDE0MjZlODU3ZDhjMWEyODJmNDEifSx7ImNvbnRlbnQtdHlwZSI6ImFwcGxpY2F0aW9uL2pzb24ifV19.tG5-P96CCA6N1IYC-xk4GumoVkA3NFolpbBn2vQ2e9vpWQ8f5Sm2l4-1VrXfKTx-CUVz_puiwqkBhulrNKj2fA
71 - name: Digest
72 in: header
73 description: >-
74 Digest of the message payload, to comply with the INTEGRITY_REST_02
75 security pattern. According to <a target="blank" href="https://www.rfc-editor.org/rfc/rfc3230.html#section-4.2">RFC
76 3230 §4.2</a>, the format MUST be the following: digest-algorithm=encoded
77 digest output.
78 required: true
79 schema:
80 type: string
81 example: SHA-256=72e18bdddf13c911b4dd562ee21979a5c9f235c3a01bd1426e857d8c1a282f41
82 - name: Agid-JWT-TrackingEvidence
83 in: header
84 description: >-
85 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
86 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"
87 href="https://italia.github.io/eid-wallet-it-docs/v1.0.0/en/e-service-pdnd.html">e-Service PDND</a>). <br/><br/>
88 <a target="blank" href="https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImV4cCI6MTczMzA1MjYwMCwibmJmIjoxNzMzMDM2NDUwLCJpYXQiOjE3MzMwMzY0MDAsImp0aSI6ImE0YjVjNmQ3LWU4ZjktYWJjZC1lZjEyLTM0NTY3ODkwMTIzNCIsImRub25jZSI6NjUyODQyNDIxMzY4NSwicHVycG9zZUlkIjoiYjJjM2Q0ZTUtZjZnNy1oOGk5LWowazEtbG1ubzEyMzQ1Njc4IiwidXNlcklEIjoiYThiN2M2ZDUtZTRmMy1nMmgxLWk5ajAta2xtbm9wcXJzdHV2IiwibG9hIjoic3Vic3RhbnRpYWwifQ.y42yfMeW2H9h0b0j0BODUml8yF20stY9q3BwoVU5BB90afBj852Q0QlInncdhjXhUjLS1V76cGBxkutDNvxRNA">EXAMPLE
89 ON JWT.IO</a>
90 required: false
91 schema:
92 type: string
93 format: JWT
94 example: eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImV4cCI6MTczMzA1MjYwMCwibmJmIjoxNzMzMDM2NDUwLCJpYXQiOjE3MzMwMzY0MDAsImp0aSI6ImE0YjVjNmQ3LWU4ZjktYWJjZC1lZjEyLTM0NTY3ODkwMTIzNCIsImRub25jZSI6NjUyODQyNDIxMzY4NSwicHVycG9zZUlkIjoiYjJjM2Q0ZTUtZjZnNy1oOGk5LWowazEtbG1ubzEyMzQ1Njc4IiwidXNlcklEIjoiYThiN2M2ZDUtZTRmMy1nMmgxLWk5ajAta2xtbm9wcXJzdHV2IiwibG9hIjoic3Vic3RhbnRpYWwifQ.y42yfMeW2H9h0b0j0BODUml8yF20stY9q3BwoVU5BB90afBj852Q0QlInncdhjXhUjLS1V76cGBxkutDNvxRNA
95 requestBody:
96 content:
97 application/json:
98 schema:
99 $ref: "#/components/schemas/CredentialClaimsRequest"
100 required: true
101 responses:
102 "200":
103 description: OK
104 content:
105 application/jwt:
106 schema:
107 $ref: "#/components/schemas/CredentialClaimsResponse"
108 example: "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjRlNTAzYjU0LWNiZDUtNDZkOC1iNzhhLTAxMTY5OTEyMmYzMCJ9.eyJpc3MiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsIm5iZiI6MTczNjg0NjY4OCwiZXhwIjoxNzM2ODQ2OTI4LCJpYXQiOjE3MzY4NDY2ODgsImF1ZCI6IjgyOTE0YjNmLTYwYjItNDUyOS1iNGQ2LTNkNGU2N2YwYTkzMyIsImp0aSI6ImM4YmQ4YTJmLWU5OTAtNDRmYS05MDEzLTFiMzUzYmZjNWEwZCJ9.4BgoaKyVOupA67tXLQeIK8QNEiYkB646_35HndTkWxS9xypF7FJqyqV24z6EJirSgn5BlT2ZrgqeDURSjJuPUg"
109 "400":
110 description: Bad Request
111 content:
112 application/json:
113 schema:
114 type: object
115 properties:
116 error:
117 type: string
118 description: The error code
119 enum: [invalid_request, invalid_dpop_proof]
120 error_description:
121 type: string
122 description: Text in human-readable form providing further details to clarify the nature of the error encountered
123 example: >-
124 The request cannot be fulfilled because it is missing
125 required parameters, contains invalid parameters, or
126 is otherwise malformed.
127 required:
128 - error
129 examples:
130 invalid_request:
131 value:
132 error: invalid_request
133 error_description: >-
134 The request cannot be fulfilled because it is missing
135 required parameters, contains invalid parameters, or is
136 otherwise malformed
137 invalid_dpop_proof:
138 value:
139 error: invalid_dpop_proof
140 error_description: >-
141 The request cannot be fulfilled because it contains an
142 invalid dpop proof
143 "401":
144 description: Unauthorized
145 headers:
146 WWW-Authenticate:
147 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.
148 schema:
149 type: string
150 example: >-
151 Bearer error="invalid_token", error_description="The access token expired"
152 "404":
153 description: Claims not found
154 content:
155 application/json:
156 schema:
157 type: object
158 properties:
159 error:
160 type: string
161 description: The error code
162 enum: [not_found]
163 error_description:
164 type: string
165 description: >-
166 Text in human-readable form providing further details to
167 clarify the nature of the error encountered
168 example: >-
169 The authentic source cannot fulfill the request because the
170 claims were not found
171 required:
172 - error
173 "500":
174 description: Internal Server Error
175 content:
176 application/json:
177 schema:
178 type: object
179 properties:
180 error:
181 type: string
182 description: The error code
183 enum: [server_error]
184 error_description:
185 type: string
186 description: >-
187 Text in human-readable form providing further details to
188 clarify the nature of the error encountered
189 required:
190 - error
191 example:
192 error: server_error
193 error_description: >-
194 The request cannot be fulfilled because the e-Service Endpoint encountered an internal problem
195 "503":
196 description: Service Unavailable
197 content:
198 application/json:
199 schema:
200 type: object
201 properties:
202 error:
203 type: string
204 description: The error code
205 enum: [temporarily_unavailable]
206 error_description:
207 type: string
208 description: >-
209 Text in human-readable form providing further details to
210 clarify the nature of the error encountered
211 required:
212 - error
213 example:
214 error: "temporarily_unavailable"
215 error_description: "The request cannot be fulfilled because the e-Service Endpoint is temporarily unavailable (e.g., due to maintainance or overload)"
216components:
217 schemas:
218 CredentialClaimsResponse:
219 properties:
220 Header:
221 type: object
222 properties:
223 alg:
224 description: A digital signature algorithm identifier.
225 type: string
226 example: RS256
227 kid:
228 description: Unique identifier of the JWK used by the Provider to sign the JWT.
229 type: string
230 example: "cdb52532-dd94-40ef-824d-9c55b10e6bc9"
231 typ:
232 description: It MUST be set to 'JWT'.
233 type: string
234 example: "JWT"
235 required: [alg, kid, typ]
236 Payload:
237 type: object
238 properties:
239 iss:
240 description: The identifier of the e-Service.
241 type: string
242 example: "https://authentic-source.example.it"
243 aud:
244 description: The identifier of the Consumer.
245 type: string
246 example: "31670092-eec0-4f95-88da-e1c7ce5e4505"
247 exp:
248 description: UNIX timestamp representing the JWT expiration time.
249 type: integer
250 example: 1736846928
251 iat:
252 description: UNIX timestamp representing the JWT issuance time.
253 type: integer
254 example: 1736846688
255 jti:
256 description: Unique identifier of the JWT to prevent replay attacks.
257 type: string
258 example: "8b971b43-e990-44fa-9013-1b353bfc5a0f"
259 nbf:
260 description: UNIX timestamp representing the JWT first validity time.
261 type: string
262 example: "1736846688"
263 lead_time:
264 description: Required if claims parameter is not present. This represents the estimated amount of time (in seconds) required before making the request of the attribute claims again.
265 type: integer
266 example: "864000"
267 userClaims:
268 description: List of User Claims.
269 type: object
270 properties:
271 given_name:
272 description: Current First Name.
273 type: string
274 example: '"Mario"'
275 family_name:
276 description: Current Family Name.
277 type: string
278 example: '"Rossi"'
279 birth_date:
280 description: Date of Birth.
281 type: string
282 example: '"1980-01-10"'
283 birth_place:
284 description: Place of Birth.
285 type: string
286 example: '"Roma"'
287 tax_id_code:
288 description: National tax identification number. REQUIRED if personal_administrative_number is absent.
289 type: string
290 example: '"TINIT-XXXXXXXXXXXXXXXX"'
291 personal_administrative_number:
292 description: National unique identifier of a natural person. REQUIRED if tax_id_code is absent.
293 type: string
294 example: '"XX00000XX"'
295 attributeClaims:
296 description: List of Datasets of Attribute.
297 type: array
298 items:
299 type: object
300 properties:
301 id:
302 description: Unique identifier of the Dataset.
303 type: string
304 example: "6F9619FF-8B86-D011-B42D-00C04FC964FF"
305 additionalProperties:
306 type: string
307 required: [id]
308 example: '[{"id": "6F9619FF-8B86-D011-B42D-00C04FC964FF", "nationality": "IT"}, {...}]'
309 required: [iss, aud, exp, iat, jti]
310 CredentialClaimsRequest:
311 required:
312 - unique_id
313 type: object
314 properties:
315 unique_id:
316 type: string
317 description: ID ANPR or Tax identification number