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