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            claims:
268              description: List of Credential Claims.
269              type: object
270              example: '"given_name": "Mario",
271                "family_name": "Rossi",
272                "birth_date": "1980-01-10",
273                "birth_place": "Roma",
274                "nationality": "IT",
275                "personal_administrative_number": "XX00000XX",
276                "tax_id_code": "TINIT-XXXXXXXXXXXXXXXX"'
277          required: [iss, aud, exp, iat, jti]
278    CredentialClaimsRequest:
279      required:
280        - unique_id
281      type: object
282      properties:
283        unique_id:
284          type: string
285          description: ID ANPR or Tax identification number