20.3. PDND e-Service Template¶
The PDND provides a specialized tool that enhances API co-design processes by optimizing e-service publication and reuse. This functionality is defined in this document.
"Linee Guida sull'infrastruttura tecnologica della Piattaforma Digitale Nazionale Dati per l'interoperabilità dei sistemi informativi e delle basi di dati" (PDND).
The template e-service serves as a standardized blueprint containing all necessary technical and descriptive metadata for an e-service. API Managers, who can be either Providers or Consumers within the PDND ecosystem, MAY create and maintain these templates.
Once a template e-service is published, it is accessible through the PDND Template Catalog, a centralized repository that facilitates discovery and reuse. This catalog enables any authorized PDND Participant to browse available templates and instantiate new e-services based on existing designs.
20.3.1. PDND Template e-service definition and guidelines¶
The PDND infrastructure supports the lifecycle management of Template E-Services, similar to that of traditional e-services. The lifecycle states include: Draft, Active, Suspended, and Deprecated. As with traditional e-services, PDND enforces role-based access control to govern status transitions.
20.3.1.1. Templates e-service Management¶
20.3.1.1.1. Template E-Service Creation¶
Participants are enabled to create Templates E-Service via a guided wizard accessible through the PDND Web GUI (APIs will be available in the future). The creation workflow closely mirrors that of standard e-service creation, with the following distinctions:
An additional field identifies the intended recipient of the template.
The "Audience" field is omitted.
Thresholds are optional and serve as recommendations for Participants implementing the template.
Participants are prohibited from creating multiple templates with the same name: template names MUST be unique per participant. Upon creation, a template is initially set to the Draft state. Templates can then be published to the Template Catalog, thereby making them accessible to all Participants.
20.3.1.1.2. Template E-Service Modification¶
Participants who have created a template may edit it. The scope of editable fields depends on the template’s lifecycle state:
If the template is in Draft state, all fields are editable.
For templates in other states, only a restricted subset of fields can be modified directly.
Fields that cannot be modified in published templates require the creation of a new template version to apply changes.
Template versioning operates similarly to that of e-services, given that changes to the blueprint can impact instantiated services and then the Participants who consume that instance.
The following fields may be edited without triggering a new template version:
Name
Intended Recipient
Description
Voucher Time Limit
Documentation (excluding the OpenAPI specification)
Attributes
20.3.1.1.3. Template E-Service Suspension¶
Templates, like e-services, can be Suspended. When suspended:
The template is removed from the templates public catalog.
Instantiation of new instances from the suspended template is disabled.
Previously instantiated instances remain unaffected.
Templates may be reactivated at any time.
Templates cannot be deleted.
20.3.1.1.4. Template E-Service Instantiation¶
Participants MAY instantiate a Template E-Service by browsing the Template Catalog and selecting a template. This process generates a new e-service.
Instantiation constraints include:
Only templates in the Active state are eligible for instantiation.
The instantiation is facilitated through a guided wizard in the PDND Web GUI.
Due to the standardization objective of templates, most fields are pre-populated and immutable during instantiation.
The following information cannot be modified during instantiation:
Documentation upload
Token expiration time
Name, description, and attributes
Instead, the following fields must be specified during instantiation:
Audience
Thresholds
Automatic/Manual Approval Policy
Additionally, although the OpenAPI specification is fixed, the following metadata fields can be provided so that PDND can automatically update the YAML specification:
Contacts (name, email, URL, Terms and Conditions URL)
Server URLs
Each instantiated e-service maintains an independent lifecycle analogous to standard e-services.
20.3.1.2. Version Management¶
Template versioning follows a controlled process:
Publishing a new template version sets it to Active.
The previously Active version is automatically transitioned to Deprecated.
Only one Active version per template is allowed at any time.
Templates may also have a single Draft version coexisting with the Active version.
Instances derived from templates maintain independent versioning since Participants may update instance-specific fields (e.g., server URLs) multiple times, while the instance remains linked to the originating template version.
Consequently, template versions and instance versions are independent and not directly correlated.
Participants instantiating a template may then update either the specific instance or, if available, upgrade to a newer template version.
20.3.1.3. Authentic Source Template¶
The template e-service functionality is employed to standardize data transmission from Authentic Sources to Credential Issuers. The template e-service SHOULD be published within PDND by the Credential Issuer and is accessible through the PDND Template Catalog.
20.3.1.3.1. Authentic Source Template Parameters¶
The template e-service MUST adhere to the following specifications:
Name: IT Wallet - Authentic Source - <
Credential name>Intended Recipients: IT Wallet - Authentic Source - <
Authentic Source domain>Description: Description text useful to the Credential Issuer about the new Credential <
Credential name>Technology: REST
Data variation via Signal Hub: True
Version changelog: Authentic Source e-service via template implementation
Voucher Time Limit: 20
Suggest custom threshold: False
Suggest manual agreement approval policy: False
Attributes: <
Offcial name of the Credential Issuer Public Authority>
20.3.1.3.2. Authentic Source Template Instantiation¶
Each Authentic Source SHOULD instantiate the IT Wallet - Authentic Source template e-service in PDND. The instantiation process will result in a new e-service that MUST satisfy the following requirements:
Signal Hub: True
Manual agreement approval policy: False
Daily API calls threshold for each provider: greater than 10000
Daily API calls threshold: greater than 10000
Additional information required during the creation process is provider-dependent.
20.3.1.3.3. 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 /v1.3.1/AttributeClaims{dataset_id}:
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 - in: path
19 name: dataset_id
20 schema:
21 type: string
22 required: true
23 description: Identifier of the dataset as registered in the Authentic Source Registry
24 - name: Authorization
25 in: header
26 description: >-
27 JWT token obtained from <a target="blank"
28 href="https://italia.github.io/eid-wallet-it-docs/v1.0.0/en/e-service-pdnd.html#voucher-issuance">PDND
29 Interoperabilità</a>. Based on the implementation choices, it can be either Bearer or DPoP.<br/><br/><a target="blank"
30 href="https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImtpZCI6ImI4MzlmNGM3LTFlNWQtNGE4YS05ZmM2LTcyZDNiN2YwOTFlYyIsInR5cCI6ImF0K2p3dCJ9.eyJpc3MiOiJodHRwczovL2ludGVyb3AucGFnb3BhLml0Iiwic3ViIjoiODI5MTRiM2YtNjBiMi00NTI5LWI0ZDYtM2Q0ZTY3ZjBhOTMzIiwiYXVkIjoiaHR0cHM6Ly9hdXRoZW50aWMtc291cmNlLmV4YW1wbGUuaXQiLCJleHAiOjE3MzMwNDIxNTAsIm5iZiI6MTczMzA0MTk0NSwiaWF0IjoxNzMzMDQxOTIwLCJqdGkiOiJjNGY1ZDdlMi1iN2M4LTQwZjYtOWI2YS1kYzlhNGY1YWViNTciLCJjbGllbnRfaWQiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJwdXJwb3NlSWQiOiJkMmI5YTY1My1jNDk3LTQ1YzYtYjhmMS01YmRmMTI0YzlkM2EiLCJkaWdlc3QiOnsiYWxnIjoiU0hBMjU2IiwidmFsdWUiOiI5Yzc4OTRhMGE1YTkxMDU4MGI5NjdmMzg0Y2RmYmExN2IxYWI2Zjg2NjcwZTViMGRmMThhMGM0NTNiNWViMjE1In0sImNuZiI6eyJqa3QiOiI4NTJkMzE5OWJkMGUzOThlYTBjOWMyYTA3NzZjYTMzNjYyOGU4NzBhZWM3YWMwYTQxOGFkYTNlNmNlMTY0ZjhkIn19.SqKCkZyv78VfaTZzOh6iYfKdGirSrPGMvqCMZE9DFXmzhaYz5lpp-fGRjmDbj88Qrw6U_3nl5WUBUjbjxpYxAQ">EXAMPLE
31 ON JWT.IO</a>
32 required: true
33 schema:
34 type: string
35 format: Signed JWT
36 example: >-
37 DPoP
38 eyJhbGciOiJFUzI1NiIsImtpZCI6ImI4MzlmNGM3LTFlNWQtNGE4YS05ZmM2LTcyZDNiN2YwOTFlYyIsInR5cCI6ImF0K2p3dCJ9.eyJpc3MiOiJodHRwczovL2ludGVyb3AucGFnb3BhLml0Iiwic3ViIjoiODI5MTRiM2YtNjBiMi00NTI5LWI0ZDYtM2Q0ZTY3ZjBhOTMzIiwiYXVkIjoiaHR0cHM6Ly9hdXRoZW50aWMtc291cmNlLmV4YW1wbGUuaXQiLCJleHAiOjE3MzMwNDIxNTAsIm5iZiI6MTczMzA0MTk0NSwiaWF0IjoxNzMzMDQxOTIwLCJqdGkiOiJjNGY1ZDdlMi1iN2M4LTQwZjYtOWI2YS1kYzlhNGY1YWViNTciLCJjbGllbnRfaWQiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJwdXJwb3NlSWQiOiJkMmI5YTY1My1jNDk3LTQ1YzYtYjhmMS01YmRmMTI0YzlkM2EiLCJkaWdlc3QiOnsiYWxnIjoiU0hBMjU2IiwidmFsdWUiOiI5Yzc4OTRhMGE1YTkxMDU4MGI5NjdmMzg0Y2RmYmExN2IxYWI2Zjg2NjcwZTViMGRmMThhMGM0NTNiNWViMjE1In0sImNuZiI6eyJqa3QiOiI4NTJkMzE5OWJkMGUzOThlYTBjOWMyYTA3NzZjYTMzNjYyOGU4NzBhZWM3YWMwYTQxOGFkYTNlNmNlMTY0ZjhkIn19.SqKCkZyv78VfaTZzOh6iYfKdGirSrPGMvqCMZE9DFXmzhaYz5lpp-fGRjmDbj88Qrw6U_3nl5WUBUjbjxpYxAQ
39 - name: DPoP
40 in: header
41 description: >-
42 DPoP proof JWT, to comply with the REST_JWS_2021_POP security
43 pattern using the POP_DPoP implementation. See also <a target="blank"
44 href="https://datatracker.ietf.org/doc/html/rfc9449.html">RFC
45 9449</a>.<br/><br/>
46
47 <a target="blank" href="https://jwt.io/#debugger-io?token=eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6IkVDIiwia2V5X29wcyI6WyJzaWduIl0sImtpZCI6IjM5ZmE5NjBiLTc3M2YtNDllZi04YTBlLWU3NzNlOWI5N2FlOCIsImNydiI6IlAtMjU2IiwieCI6Imh1eVhJUU52OTAyb0xzcFg0X3pvbkM5NEc2eUVsbjZsc2RtLTF3TTczMm8iLCJ5IjoiSTlQREVhd1dIcWFGREd4MVprTmstMlBWNldkcGNhSDNBZk9iQlNMaWhndyJ9fQ.eyJqdGkiOiIyYzc2ZmNhMy1jYjRlLTQzMTItOGI2ZS05NzQ5NDYyZjQyMGQiLCJodG0iOiJQT1NUIiwiYXRoIjoiNDc1MmMzMmQ2YzQ4NzYzZjBmMzljZDNkYzk5ZDJlOTk3OTMyYmFmMzc1NjNiYzVhODk5NDg3YTZmODZlNWIxZCIsImh0dSI6Imh0dHBzOi8vYXV0aGVudGljLXNvdXJjZS5leGFtcGxlLml0IiwiaWF0IjoxNzYyMjYyNjE2fQ.Mdayqq66hFzMFvN131WRZ_dxyaEu7W1Qz-ksYt6-RLGD1rCixnmnmFnNOsgFT_wztGL1zJloYTMgn9Ys6lSxgQ">EXAMPLE
48 ON JWT.IO</a>
49 required: false
50 schema:
51 type: string
52 format: JWT
53 example: >-
54 eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6IkVDIiwia2V5X29wcyI6WyJzaWduIl0sImtpZCI6IjM5ZmE5NjBiLTc3M2YtNDllZi04YTBlLWU3NzNlOWI5N2FlOCIsImNydiI6IlAtMjU2IiwieCI6Imh1eVhJUU52OTAyb0xzcFg0X3pvbkM5NEc2eUVsbjZsc2RtLTF3TTczMm8iLCJ5IjoiSTlQREVhd1dIcWFGREd4MVprTmstMlBWNldkcGNhSDNBZk9iQlNMaWhndyJ9fQ.eyJqdGkiOiIyYzc2ZmNhMy1jYjRlLTQzMTItOGI2ZS05NzQ5NDYyZjQyMGQiLCJodG0iOiJQT1NUIiwiYXRoIjoiNDc1MmMzMmQ2YzQ4NzYzZjBmMzljZDNkYzk5ZDJlOTk3OTMyYmFmMzc1NjNiYzVhODk5NDg3YTZmODZlNWIxZCIsImh0dSI6Imh0dHBzOi8vYXV0aGVudGljLXNvdXJjZS5leGFtcGxlLml0IiwiaWF0IjoxNzYyMjYyNjE2fQ.Mdayqq66hFzMFvN131WRZ_dxyaEu7W1Qz-ksYt6-RLGD1rCixnmnmFnNOsgFT_wztGL1zJloYTMgn9Ys6lSxgQ
55 - name: Agid-JWT-Signature
56 in: header
57 description: >-
58 JWT containing the signature of the message headers whose integrity
59 needs to be guaranteed, to comply with the INTEGRITY_REST_02
60 security pattern (see <a target="blank"
61 href="https://italia.github.io/eid-wallet-it-docs/v1.0.0/en/e-service-pdnd.html">e-Service PDND</a>). <br/><br/>
62
63 <a target="blank" href="https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJzdWIiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImlhdCI6MTczMzM5Nzg0MCwibmJmIjoxNzMzNDAxNjI4LCJleHAiOjE3MzM0MDE0NDAsImp0aSI6ImQzZjdiMmM5LTI3NGEtNDJiNy04ZjhkLTJlOWQ4YjE3MzRiMCIsInNpZ25lZF9oZWFkZXJzIjpbeyJkaWdlc3QiOiJTSEEtMjU2PTcyZTE4YmRkZGYxM2M5MTFiNGRkNTYyZWUyMTk3OWE1YzlmMjM1YzNhMDFiZDE0MjZlODU3ZDhjMWEyODJmNDEifSx7ImNvbnRlbnQtdHlwZSI6ImFwcGxpY2F0aW9uL2pzb24ifV19.tG5-P96CCA6N1IYC-xk4GumoVkA3NFolpbBn2vQ2e9vpWQ8f5Sm2l4-1VrXfKTx-CUVz_puiwqkBhulrNKj2fA">EXAMPLE
64 ON JWT.IO</a>
65 required: true
66 schema:
67 type: string
68 format: JWT
69 example: eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJzdWIiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImlhdCI6MTczMzM5Nzg0MCwibmJmIjoxNzMzNDAxNjI4LCJleHAiOjE3MzM0MDE0NDAsImp0aSI6ImQzZjdiMmM5LTI3NGEtNDJiNy04ZjhkLTJlOWQ4YjE3MzRiMCIsInNpZ25lZF9oZWFkZXJzIjpbeyJkaWdlc3QiOiJTSEEtMjU2PTcyZTE4YmRkZGYxM2M5MTFiNGRkNTYyZWUyMTk3OWE1YzlmMjM1YzNhMDFiZDE0MjZlODU3ZDhjMWEyODJmNDEifSx7ImNvbnRlbnQtdHlwZSI6ImFwcGxpY2F0aW9uL2pzb24ifV19.tG5-P96CCA6N1IYC-xk4GumoVkA3NFolpbBn2vQ2e9vpWQ8f5Sm2l4-1VrXfKTx-CUVz_puiwqkBhulrNKj2fA
70 - name: Digest
71 in: header
72 description: >-
73 Digest of the message payload, to comply with the INTEGRITY_REST_02
74 security pattern. According to <a target="blank" href="https://www.rfc-editor.org/rfc/rfc3230.html#section-4.2">RFC
75 3230 §4.2</a>, the format MUST be the following: digest-algorithm=encoded
76 digest output.
77 required: true
78 schema:
79 type: string
80 example: SHA-256=72e18bdddf13c911b4dd562ee21979a5c9f235c3a01bd1426e857d8c1a282f41
81 - name: Agid-JWT-TrackingEvidence
82 in: header
83 description: >-
84 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
85 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"
86 href="https://italia.github.io/eid-wallet-it-docs/v1.0.0/en/e-service-pdnd.html">e-Service PDND</a>). <br/><br/>
87 <a target="blank" href="https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImV4cCI6MTczMzA1MjYwMCwibmJmIjoxNzMzMDM2NDUwLCJpYXQiOjE3MzMwMzY0MDAsImp0aSI6ImE0YjVjNmQ3LWU4ZjktYWJjZC1lZjEyLTM0NTY3ODkwMTIzNCIsImRub25jZSI6NjUyODQyNDIxMzY4NSwicHVycG9zZUlkIjoiYjJjM2Q0ZTUtZjZnNy1oOGk5LWowazEtbG1ubzEyMzQ1Njc4IiwidXNlcklEIjoiYThiN2M2ZDUtZTRmMy1nMmgxLWk5ajAta2xtbm9wcXJzdHV2IiwibG9hIjoic3Vic3RhbnRpYWwifQ.y42yfMeW2H9h0b0j0BODUml8yF20stY9q3BwoVU5BB90afBj852Q0QlInncdhjXhUjLS1V76cGBxkutDNvxRNA">EXAMPLE
88 ON JWT.IO</a>
89 required: false
90 schema:
91 type: string
92 format: JWT
93 example: eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImV4cCI6MTczMzA1MjYwMCwibmJmIjoxNzMzMDM2NDUwLCJpYXQiOjE3MzMwMzY0MDAsImp0aSI6ImE0YjVjNmQ3LWU4ZjktYWJjZC1lZjEyLTM0NTY3ODkwMTIzNCIsImRub25jZSI6NjUyODQyNDIxMzY4NSwicHVycG9zZUlkIjoiYjJjM2Q0ZTUtZjZnNy1oOGk5LWowazEtbG1ubzEyMzQ1Njc4IiwidXNlcklEIjoiYThiN2M2ZDUtZTRmMy1nMmgxLWk5ajAta2xtbm9wcXJzdHV2IiwibG9hIjoic3Vic3RhbnRpYWwifQ.y42yfMeW2H9h0b0j0BODUml8yF20stY9q3BwoVU5BB90afBj852Q0QlInncdhjXhUjLS1V76cGBxkutDNvxRNA
94 requestBody:
95 content:
96 application/json:
97 schema:
98 $ref: "#/components/schemas/CredentialClaimsRequest"
99 required: true
100 responses:
101 "200":
102 description: OK
103 content:
104 application/jwt:
105 schema:
106 $ref: "#/components/schemas/CredentialClaimsResponse"
107 example: "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI1NiIsImtpZCI6IjRlNTAzYjU0LWNiZDUtNDZkOC1iNzhhLTAxMTY5OTEyMmYzMCJ9.eyJpc3MiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsIm5iZiI6MTczNjg0NjY4OCwiZXhwIjoxNzM2ODQ2OTI4LCJpYXQiOjE3MzY4NDY2ODgsImF1ZCI6IjgyOTE0YjNmLTYwYjItNDUyOS1iNGQ2LTNkNGU2N2YwYTkzMyIsImp0aSI6ImM4YmQ4YTJmLWU5OTAtNDRmYS05MDEzLTFiMzUzYmZjNWEwZCJ9.4BgoaKyVOupA67tXLQeIK8QNEiYkB646_35HndTkWxS9xypF7FJqyqV24z6EJirSgn5BlT2ZrgqeDURSjJuPUg"
108 "400":
109 description: Bad Request
110 content:
111 application/json:
112 schema:
113 type: object
114 properties:
115 error:
116 type: string
117 description: The error code
118 enum: [invalid_request, invalid_dpop_proof]
119 error_description:
120 type: string
121 description: Text in human-readable form providing further details to clarify the nature of the error encountered
122 example: >-
123 The request cannot be fulfilled because it is missing
124 required parameters, contains invalid parameters, or
125 is otherwise malformed.
126 required:
127 - error
128 examples:
129 invalid_request:
130 value:
131 error: invalid_request
132 error_description: >-
133 The request cannot be fulfilled because it is missing
134 required parameters, contains invalid parameters, or is
135 otherwise malformed
136 invalid_dpop_proof:
137 value:
138 error: invalid_dpop_proof
139 error_description: >-
140 The request cannot be fulfilled because it contains an
141 invalid dpop proof
142 "401":
143 description: Unauthorized
144 headers:
145 WWW-Authenticate:
146 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.
147 schema:
148 type: string
149 example: >-
150 Bearer error="invalid_token", error_description="The access token expired"
151 "404":
152 description: Claims not found
153 content:
154 application/json:
155 schema:
156 type: object
157 properties:
158 error:
159 type: string
160 description: The error code
161 enum: [not_found]
162 error_description:
163 type: string
164 description: >-
165 Text in human-readable form providing further details to
166 clarify the nature of the error encountered
167 example: >-
168 The authentic source cannot fulfill the request because the
169 claims were not found
170 required:
171 - error
172 "500":
173 description: Internal Server Error
174 content:
175 application/json:
176 schema:
177 type: object
178 properties:
179 error:
180 type: string
181 description: The error code
182 enum: [server_error]
183 error_description:
184 type: string
185 description: >-
186 Text in human-readable form providing further details to
187 clarify the nature of the error encountered
188 required:
189 - error
190 example:
191 error: server_error
192 error_description: >-
193 The request cannot be fulfilled because the e-Service Endpoint encountered an internal problem
194 "503":
195 description: Service Unavailable
196 content:
197 application/json:
198 schema:
199 type: object
200 properties:
201 error:
202 type: string
203 description: The error code
204 enum: [temporarily_unavailable]
205 error_description:
206 type: string
207 description: >-
208 Text in human-readable form providing further details to
209 clarify the nature of the error encountered
210 required:
211 - error
212 example:
213 error: "temporarily_unavailable"
214 error_description: "The request cannot be fulfilled because the e-Service Endpoint is temporarily unavailable (e.g., due to maintainance or overload)"
215components:
216 schemas:
217 CredentialClaimsResponse:
218 properties:
219 Header:
220 type: object
221 properties:
222 alg:
223 description: A digital signature algorithm identifier.
224 type: string
225 example: RS256
226 kid:
227 description: Unique identifier of the JWK used by the Provider to sign the JWT.
228 type: string
229 example: "cdb52532-dd94-40ef-824d-9c55b10e6bc9"
230 typ:
231 description: It MUST be set to 'JWT'.
232 type: string
233 example: "JWT"
234 required: [alg, kid, typ]
235 Payload:
236 type: object
237 properties:
238 iss:
239 description: The identifier of the e-Service.
240 type: string
241 example: "https://authentic-source.example.it"
242 aud:
243 description: The identifier of the Consumer.
244 type: string
245 example: "31670092-eec0-4f95-88da-e1c7ce5e4505"
246 exp:
247 description: UNIX timestamp representing the JWT expiration time.
248 type: integer
249 example: 1736846928
250 iat:
251 description: UNIX timestamp representing the JWT issuance time.
252 type: integer
253 example: 1736846688
254 jti:
255 description: Unique identifier of the JWT to prevent replay attacks.
256 type: string
257 example: "8b971b43-e990-44fa-9013-1b353bfc5a0f"
258 nbf:
259 description: UNIX timestamp representing the JWT first validity time.
260 type: string
261 example: "1736846688"
262 interval:
263 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.
264 type: integer
265 example: "864000"
266 userClaims:
267 description: List of User Claims.
268 type: object
269 properties:
270 given_name:
271 description: Current First Name.
272 type: string
273 example: '"Mario"'
274 family_name:
275 description: Current Family Name.
276 type: string
277 example: '"Rossi"'
278 birth_date:
279 description: Date of Birth.
280 type: string
281 example: '"1980-01-10"'
282 birth_place:
283 description: Place of Birth.
284 type: string
285 example: '"Roma"'
286 tax_id_code:
287 description: National tax identification number. REQUIRED if personal_administrative_number is absent.
288 type: string
289 example: '"TINIT-XXXXXXXXXXXXXXXX"'
290 personal_administrative_number:
291 description: National unique identifier of a natural person. REQUIRED if tax_id_code is absent.
292 type: string
293 example: '"XX00000XX"'
294 attributeClaims:
295 description: List of Datasets of Attribute.
296 type: array
297 items:
298 type: object
299 properties:
300 object_id:
301 description: Unique identifier of the Dataset.
302 type: string
303 example: "6F9619FF-8B86-D011-B42D-00C04FC964FF"
304 status:
305 description: Status of the Dataset.
306 type: string
307 enum: ["VALID","INVALID", "SUSPENDED"]
308 example: "VALID"
309 last_updated:
310 description: Last time the status or attributes of the Dataset have been updated. Its format is `YYYY-MM-DDTHH:MM:SSZ`.
311 type: string
312 example:
313 additionalProperties:
314 type: string
315 required: [object_id, status, last_updated]
316 example: '[{"object_id": "6F9619FF-8B86-D011-B42D-00C04FC964FF", "nationality": "IT"}, {...}]'
317 metadataClaims:
318 description: List of Metadata Claims.
319 type: array
320 items:
321 type: object
322 properties:
323 object_id:
324 description: Unique identifier of the Dataset.
325 type: string
326 example: "6F9619FF-8B86-D011-B42D-00C04FC964FF"
327 issuance_date:
328 description: Administrative validity start date of the Dataset
329 type: string
330 example: '"2025-01-01"'
331 expiry_date:
332 description: Administrative expiry date of the Dataset.
333 type: string
334 example: '"2025-12-31"'
335 required: [object_id]
336 required: [iss, aud, exp, iat, jti]
337 CredentialClaimsRequest:
338 required:
339 - unique_id
340 type: object
341 properties:
342 unique_id:
343 type: string
344 description: ID ANPR or Tax identification number
345 object_id:
346 type: string
347 description: Unique identifier of the Credential dataset or `jti` of the Agid-JWT-Signature Credential Issuer deferred flow's request. If this parameter is present only the indicated dataset is returned