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