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.2.0
  5  description: |
  6    # IT Wallet Authentic Source e-Service exposed via PDND.
  7    ### ModI patterns to be used:
  8      - <b>ID_AUTH_CHANNEL_01</b>: Direct Trust TLS (HTTPS)
  9      - <b>ID_AUTH_REST_01</b>: Authorization via PDND token
 10      - <b>INTEGRITY_REST_02</b>: Requests and responses are signed
 11      - <b>AUDIT_REST_02</b>: Additional properties (the pattern is optional if DPoP Token is used)
 12      - <b>DPoP Token</b>: Used as an alternative to a Bearer Token (optional)
 13  termsOfService: "https://authentic-source.example.it/tos/"
 14  contact:
 15    name: IT-Wallet <credential_name> <credential_provider>
 16    url: https://github.com/italia/eid-wallet-it-docs
 17  x-api-id: ASITW-01
 18  x-summary: IT-Wallet Authentic Source API.
 19servers:
 20  - url: https://test.authentic-source.example.it/v0.2.0
 21    description: Authentic Source API test server
 22  - url: https://authentic-source.example.it/v0.2.0
 23    description: Authentic Source API production server
 24security:
 25  - BearerAuth: []
 26  - DPoPAuth: []
 27paths:
 28  /status:
 29    get:
 30      tags:
 31        - status
 32      summary: Get Authentic Source API status.
 33      description: Health-check endpoint that returns the operational status of the Authentic Source API.
 34      operationId: authenticSourceStatus
 35      parameters:
 36        - name: DPoP
 37          in: header
 38          description: Use only if the DPoP voucher has been requested from PDND.
 39          schema:
 40            type: string
 41            format: JWT
 42          required: false
 43      responses:
 44        "200":
 45          description: Service available
 46          content:
 47            application/problem+json:
 48              schema:
 49                $ref: "#/components/schemas/ProblemDetails"
 50          headers:
 51            Cache-Control:
 52              $ref: "#/components/headers/CacheControlHeader"
 53            X-RateLimit-Limit:
 54              $ref: "#/components/headers/RateLimitLimitHeader"
 55            X-RateLimit-Remaining:
 56              $ref: "#/components/headers/RateLimitRemainingHeader"
 57            X-RateLimit-Reset:
 58              $ref: "#/components/headers/RateLimitResetHeader"
 59        "429":
 60          description: Too Many Requests
 61          content:
 62            application/problem+json:
 63              schema:
 64                $ref: "#/components/schemas/ProblemDetails"
 65          headers:
 66            # RFC 6585 defines Retry-After. X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset are not required because redundant along with Retry-After.
 67            Retry-After:
 68              $ref: "#/components/headers/RetryAfterHeader"
 69        "503":
 70          description: Service Unavailable
 71          content:
 72            application/problem+json:
 73              schema:
 74                $ref: "#/components/schemas/ProblemDetails"
 75          headers:
 76            Retry-After:
 77              $ref: "#/components/headers/RetryAfterHeader"
 78
 79  /attribute-claims/{datasetId}:
 80    post:
 81      tags:
 82        - credential
 83      summary: Get Attribute Claims
 84      description: >-
 85        This service provides the Credential Issuer with all attribute claims necessary for the issuance of a Digital Credential
 86      operationId: attributeClaims
 87      parameters:
 88        - in: path
 89          name: datasetId
 90          schema:
 91            type: string
 92          required: true
 93          description: Identifier of the dataset as registered in the Authentic Source Registry
 94        - name: DPoP
 95          in: header
 96          description: Use only if the DPoP voucher has been requested from PDND.
 97          schema:
 98            type: string
 99            format: JWT
100          required: false
101        - name: Agid-JWT-Signature
102          in: header
103          description: >-
104            JWT containing the signature of the message headers whose integrity
105            needs to be guaranteed, to comply with the INTEGRITY_REST_02
106            security pattern (see <a target="blank"
107            href="https://italia.github.io/eid-wallet-it-docs/versione-corrente/en/e-service-pdnd.html">e-Service PDND</a>). <br/><br/>
108
109            <a target="blank" href="https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJzdWIiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImlhdCI6MTczMzM5Nzg0MCwibmJmIjoxNzMzNDAxNjI4LCJleHAiOjE3MzM0MDE0NDAsImp0aSI6ImQzZjdiMmM5LTI3NGEtNDJiNy04ZjhkLTJlOWQ4YjE3MzRiMCIsInNpZ25lZF9oZWFkZXJzIjpbeyJkaWdlc3QiOiJTSEEtMjU2PTcyZTE4YmRkZGYxM2M5MTFiNGRkNTYyZWUyMTk3OWE1YzlmMjM1YzNhMDFiZDE0MjZlODU3ZDhjMWEyODJmNDEifSx7ImNvbnRlbnQtdHlwZSI6ImFwcGxpY2F0aW9uL2pzb24ifV19.tG5-P96CCA6N1IYC-xk4GumoVkA3NFolpbBn2vQ2e9vpWQ8f5Sm2l4-1VrXfKTx-CUVz_puiwqkBhulrNKj2fA">EXAMPLE
110            ON JWT.IO</a>
111          required: true
112          schema:
113            type: string
114            format: JWT
115            example: eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJzdWIiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImlhdCI6MTczMzM5Nzg0MCwibmJmIjoxNzMzNDAxNjI4LCJleHAiOjE3MzM0MDE0NDAsImp0aSI6ImQzZjdiMmM5LTI3NGEtNDJiNy04ZjhkLTJlOWQ4YjE3MzRiMCIsInNpZ25lZF9oZWFkZXJzIjpbeyJkaWdlc3QiOiJTSEEtMjU2PTcyZTE4YmRkZGYxM2M5MTFiNGRkNTYyZWUyMTk3OWE1YzlmMjM1YzNhMDFiZDE0MjZlODU3ZDhjMWEyODJmNDEifSx7ImNvbnRlbnQtdHlwZSI6ImFwcGxpY2F0aW9uL2pzb24ifV19.tG5-P96CCA6N1IYC-xk4GumoVkA3NFolpbBn2vQ2e9vpWQ8f5Sm2l4-1VrXfKTx-CUVz_puiwqkBhulrNKj2fA
116        - name: Digest
117          in: header
118          description: >-
119            Digest of the message payload, to comply with the INTEGRITY_REST_02
120            security pattern. According to <a target="blank" href="https://www.rfc-editor.org/rfc/rfc3230.html#section-4.2">RFC
121            3230 §4.2</a>, the format MUST be the following: digest-algorithm=encoded
122            digest output.
123          required: true
124          schema:
125            type: string
126            example: SHA-256=72e18bdddf13c911b4dd562ee21979a5c9f235c3a01bd1426e857d8c1a282f41
127        - name: Agid-JWT-TrackingEvidence
128          in: header
129          description: >-
130            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
131            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"
132            href="https://italia.github.io/eid-wallet-it-docs/versione-corrente/en/e-service-pdnd.html">e-Service PDND</a>). <br/><br/>
133            <a target="blank" href="https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImV4cCI6MTczMzA1MjYwMCwibmJmIjoxNzMzMDM2NDUwLCJpYXQiOjE3MzMwMzY0MDAsImp0aSI6ImE0YjVjNmQ3LWU4ZjktYWJjZC1lZjEyLTM0NTY3ODkwMTIzNCIsImRub25jZSI6NjUyODQyNDIxMzY4NSwicHVycG9zZUlkIjoiYjJjM2Q0ZTUtZjZnNy1oOGk5LWowazEtbG1ubzEyMzQ1Njc4IiwidXNlcklEIjoiYThiN2M2ZDUtZTRmMy1nMmgxLWk5ajAta2xtbm9wcXJzdHV2IiwibG9hIjoic3Vic3RhbnRpYWwifQ.y42yfMeW2H9h0b0j0BODUml8yF20stY9q3BwoVU5BB90afBj852Q0QlInncdhjXhUjLS1V76cGBxkutDNvxRNA">EXAMPLE
134            ON JWT.IO</a>
135          required: false
136          schema:
137            type: string
138            format: JWT
139            example: eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImV4cCI6MTczMzA1MjYwMCwibmJmIjoxNzMzMDM2NDUwLCJpYXQiOjE3MzMwMzY0MDAsImp0aSI6ImE0YjVjNmQ3LWU4ZjktYWJjZC1lZjEyLTM0NTY3ODkwMTIzNCIsImRub25jZSI6NjUyODQyNDIxMzY4NSwicHVycG9zZUlkIjoiYjJjM2Q0ZTUtZjZnNy1oOGk5LWowazEtbG1ubzEyMzQ1Njc4IiwidXNlcklEIjoiYThiN2M2ZDUtZTRmMy1nMmgxLWk5ajAta2xtbm9wcXJzdHV2IiwibG9hIjoic3Vic3RhbnRpYWwifQ.y42yfMeW2H9h0b0j0BODUml8yF20stY9q3BwoVU5BB90afBj852Q0QlInncdhjXhUjLS1V76cGBxkutDNvxRNA
140      requestBody:
141        required: true
142        content:
143          application/json:
144            schema:
145              $ref: "#/components/schemas/CredentialClaimsRequest"
146      responses:
147        "200":
148          description: OK
149          headers:
150            Agid-JWT-Signature:
151              description: JWT containing the signature of the message headers whose integrity needs to be guaranteed, to comply with the INTEGRITY_REST_02 security pattern (see <a target="blank" href="https://italia.github.io/eid-wallet-it-docs/versione-corrente/en/e-service-pdnd.html">e-Service PDND</a>). <a target="blank" href="https://jwt.io/#debugger-io?token=ew0KICAiYWxnIjogIkVTMjU2IiwNCiAgImtpZCI6ICJhMWY1YzhkMi00YjM3LTRlOTEtYjBkMi03OWUzZjBjNGE4ZWYiLA0KICAidHlwIjogIkpXVCINCn0.ew0KICAiaXNzIjogIjEyMzRhYmNkLWVmNTYtZ2g3OC1pOWowLWtsbW5vcHFyc3R3eCIsDQogICJzdWIiOiAiMTIzNGFiY2QtZWY1Ni1naDc4LWk5ajAta2xtbm9wcXJzdHd4IiwNCiAgImF1ZCI6ICJodHRwczovL2ZydWl0b3JlLmV4YW1wbGUvZW50ZS1leGFtcGxlL3YxIiwNCiAgImlhdCI6IDE3MzMzOTc4NDAsDQogICJuYmYiOiAxNzMzNDAxNjI4LA0KICAiZXhwIjogMTczMzQwMTQ0MCwNCiAgImp0aSI6ICI4ZTEyZjRiNy05YzNhLTRmODMtOWI4ZC01MWEyYzdmNmU5ZDQiLA0KICAic2lnbmVkX2hlYWRlcnMiOiBbDQogICAgew0KICAgICAgImRpZ2VzdCI6ICJTSEEtMjU2PTc5YTIwYTc0NDMzNjQyMDMwMTgzMDYwMGFkOWJkY2E5OTM1OTNmODc2MjA5YTAwNGI1OTliNTgzMDk1YjBhNjEiDQogICAgfSwNCiAgICB7DQogICAgICAiY29udGVudC10eXBlIjogImFwcGxpY2F0aW9uL2pzb24iDQogICAgfQ0KICBdDQp9.DpuBNo2UgQhL7WLin4mpdZrbIpQq3tPvCX6HfktkxG7L5mk6a8OK1Hg0mQcZfFi3gelS-aL9kFS-6MoSy4csBg">EXAMPLE
152              required: true
153              schema:
154                type: string
155            Digest:
156              description: Digest of the message payload, to comply with the INTEGRITY_REST_02 security pattern. According to RFC 3230 Section 4.2 <a target="blank" href="https://www.rfc-editor.org/rfc/rfc3230.html#section-4.2">RFC 3230 §4.2</a>, the format MUST be the following digest-algorithm=encoded digest output.
157              required: true
158              schema:
159                type: string
160                example: SHA-256=79a20a744336420301830600ad9bdca993593f876209a004b599b583095b0a61
161            Cache-Control:
162              $ref: "#/components/headers/CacheControlHeader"
163            X-RateLimit-Limit:
164              $ref: "#/components/headers/RateLimitLimitHeader"
165            X-RateLimit-Remaining:
166              $ref: "#/components/headers/RateLimitRemainingHeader"
167            X-RateLimit-Reset:
168              $ref: "#/components/headers/RateLimitResetHeader"
169          content:
170            application/json:
171              schema:
172                $ref: "#/components/schemas/CredentialClaimsResponse"
173              example:
174                interval: 864000
175                userClaims:
176                  given_name: "Mario"
177                  family_name: "Rossi"
178                  birth_date: "1980-01-10"
179                  birth_place: "Roma"
180                  tax_id_code: "TINIT-RSSMRA80A01H501Z"
181                  personal_administrative_number: "12345A123A"
182                attributeClaims:
183                  - object_id: "6F9619FF-8B86-D011-B42D-00C04FC964FF"
184                    status: "VALID"
185                    last_updated: "2025-01-15T10:30:00Z"
186                    institute_name: "Nome Istituto Universitario"
187                    programme_type_name: "Laurea Magistrale"
188                    degree_course_name: "Computer Science - Informatica"
189                    academic_qualification_date: "2025-06-25"
190                  - object_id: "7A0720AB-9C97-E122-C53E-11D05FD075GG"
191                    status: "VALID"
192                    last_updated: "2025-01-10T08:00:00Z"
193                    institute_name: "Nome Istituto Universitario"
194                    programme_type_name: "Laurea Triennale"
195                    degree_course_name: "Informatica"
196                    academic_qualification_date: "2022-11-27"
197                metadataClaims:
198                  - object_id: "6F9619FF-8B86-D011-B42D-00C04FC964FF"
199                    issuance_date: "2025-06-25"
200                  - object_id: "7A0720AB-9C97-E122-C53E-11D05FD075GG"
201                    issuance_date: "2022-11-27"
202        "400":
203          description: Bad Request
204          content:
205            application/problem+json:
206              schema:
207                $ref: "#/components/schemas/ProblemDetails"
208          headers:
209            X-RateLimit-Limit:
210              $ref: "#/components/headers/RateLimitLimitHeader"
211            X-RateLimit-Remaining:
212              $ref: "#/components/headers/RateLimitRemainingHeader"
213            X-RateLimit-Reset:
214              $ref: "#/components/headers/RateLimitResetHeader"
215        "401":
216          description: Unauthorized
217          content:
218            application/problem+json:
219              schema:
220                $ref: "#/components/schemas/ProblemDetails"
221          headers:
222            X-RateLimit-Limit:
223              $ref: "#/components/headers/RateLimitLimitHeader"
224            X-RateLimit-Remaining:
225              $ref: "#/components/headers/RateLimitRemainingHeader"
226            X-RateLimit-Reset:
227              $ref: "#/components/headers/RateLimitResetHeader"
228            WWW-Authenticate:
229              $ref: "#/components/headers/WWWAuthenticateHeader"
230        "404":
231          description: Claims not found
232          content:
233            application/problem+json:
234              schema:
235                $ref: "#/components/schemas/ProblemDetails"
236          headers:
237            X-RateLimit-Limit:
238              $ref: "#/components/headers/RateLimitLimitHeader"
239            X-RateLimit-Remaining:
240              $ref: "#/components/headers/RateLimitRemainingHeader"
241            X-RateLimit-Reset:
242              $ref: "#/components/headers/RateLimitResetHeader"
243        "429":
244          description: Too Many Requests
245          content:
246            application/problem+json:
247              schema:
248                $ref: "#/components/schemas/ProblemDetails"
249          headers:
250            # RFC 6585 defines Retry-After. X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset are not required because redundant along with Retry-After.
251            Retry-After:
252              $ref: "#/components/headers/RetryAfterHeader"
253        "500":
254          description: Internal Server Error.
255          content:
256            application/problem+json:
257              schema:
258                $ref: "#/components/schemas/ProblemDetails"
259          headers:
260            Retry-After:
261              $ref: "#/components/headers/RetryAfterHeader"
262        "503":
263          description: Service Unavailable
264          content:
265            application/problem+json:
266              schema:
267                $ref: "#/components/schemas/ProblemDetails"
268          headers:
269            Retry-After:
270              $ref: "#/components/headers/RetryAfterHeader"
271
272tags:
273  - name: status
274    description: Endpoint di health check dell'API.
275  - name: credential
276    description: Retrieve information about the credential.
277
278components:
279  securitySchemes:
280    BearerAuth:
281      type: http
282      scheme: bearer
283      bearerFormat: JWT
284      description: PDND Bearer Token
285    DPoPAuth:
286      type: apiKey
287      in: header
288      name: DPoP
289      description: DPoP proof JWT (RFC 9449).
290
291  headers:
292    CacheControlHeader:
293      schema:
294        type: string
295        enum:
296          - no-store
297      description: no-store
298    RateLimitLimitHeader:
299      schema:
300        type: integer
301        format: int32
302        minimum: 0
303      description: Maximum number of requests within the time window.
304    RateLimitRemainingHeader:
305      schema:
306        type: integer
307        format: int32
308        minimum: 0
309      description: Remaining requests within the time window.
310    RateLimitResetHeader:
311      schema:
312        type: integer
313        format: int32
314        minimum: 0
315      description: UTC epoch in seconds, corresponding to when the window for the current rate limit will reset.
316    RetryAfterHeader:
317      schema:
318        type: integer
319        format: int32
320        minimum: 0
321      description: Seconds to wait before receiving another response.
322    WWWAuthenticateHeader:
323      schema:
324        type: string
325        example: >-
326          Bearer error="invalid_token", error_description="The access token expired"
327      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.
328
329  schemas:
330    CredentialClaimsResponse:
331      type: object
332      properties:
333        userClaims:
334          description: List of User Claims.
335          type: object
336          properties:
337            given_name:
338              description: Current First Name.
339              type: string
340              example: "Mario"
341            family_name:
342              description: Current Family Name.
343              type: string
344              example: "Rossi"
345            birth_date:
346              description: Date of Birth.
347              type: string
348              example: "1980-01-10"
349            birth_place:
350              description: Place of Birth.
351              type: string
352              example: "Roma"
353            tax_id_code:
354              description: National tax identification number. REQUIRED if personal_administrative_number is absent.
355              type: string
356              example: "TINIT-XXXXXXXXXXXXXXXX"
357            personal_administrative_number:
358              description: National unique identifier of a natural person. REQUIRED if tax_id_code is absent.
359              type: string
360              example: "XX00000XX"
361        attributeClaims:
362          description: List of Datasets of Attribute.
363          type: array
364          items:
365            type: object
366            properties:
367              object_id:
368                description: Unique identifier of the Dataset. It MUST NOT contain personal data. Required also if additionalProperties are not present. This parameter MUST be used to notify through Signal Hub data updating or availability.
369                type: string
370                example: "6F9619FF-8B86-D011-B42D-00C04FC964FF"
371              issuance_date:
372                description: Administrative validity start date of the Dataset
373                type: string
374                example: "2025-01-01"
375              expiry_date:
376                description: Administrative expiry date of the Dataset.
377                type: string
378                example: "2025-12-31"
379            additionalProperties:
380              type: string
381            required: [object_id]
382        metadataClaims:
383          description: List of Metadata of Attribute.
384          type: array
385          items:
386            type: object
387            properties:
388              object_id:
389                description: Unique identifier of the Dataset. It MUST NOT contain personal data.
390                type: string
391                example: "6F9619FF-8B86-D011-B42D-00C04FC964FF"
392              description:
393                description: Human-Readable description of the Dataset.
394                type: string
395                example: "Example: Master's Degree in Computer Science"
396              status:
397                description: |
398                  Status of the Dataset. REQUIRED if additionalProperties of attributeClaims are present. Issued and Expired datasets fall within VALID; expiry is verified
399                  via metadata claims (e.g. expiry_date, nbf/exp). INVALID indicates active revocation by the AS.
400                  For how this status affects the Digital Credential lifecycle managed by the Credential
401                  Issuer, see <a target="blank" href="https://italia.github.io/eid-wallet-it-docs/versione-corrente/en/credential-revocation.html#status-update-by-authentic-sources">Status Update by Authentic Sources</a>.
402                type: string
403                enum:
404                  - VALID
405                  - INVALID
406                  - SUSPENDED
407                x-enum-description:
408                  - VALID - Dataset is valid (includes Issued and Expired; expiry checked via metadata).
409                  - INVALID - Dataset has been actively revoked by the Authentic Source.
410                  - SUSPENDED - Dataset is temporarily invalid (typically reversible).
411                example: "VALID"
412              status_description:
413                description: Human-Readable description of the Status.
414                type: string
415                example: "Example: Master's Degree in Computer Science"
416              last_updated:
417                description: REQUIRED if additionalProperties of attributeClaims are present. Last time the status or attributes of the Dataset have been updated. Its format is `YYYY-MM-DDTHH:MM:SSZ`.
418                type: string
419                example: "2025-01-15T10:30:00Z"
420              interval:
421                description: Required if userClaims and additionalProperties of AttributeClaim parameters are not present. This represents the estimated amount of time (in seconds) required before making the request of the attribute claims again.
422                type: integer
423                format: int64
424                example: 864000
425            required: [object_id, description]
426      required: [attributeClaims, metadataClaims]
427    CredentialClaimsRequest:
428      required:
429        - unique_id
430      type: object
431      properties:
432        unique_id:
433          type: string
434          description: ID ANPR or Tax identification number
435        object_id:
436          type: string
437          description: Unique identifier of the Credential dataset. If this parameter is present only the indicated dataset is returned.
438    ProblemDetails:
439      type: object
440      description: RFC7807-compliant problem details object for error responses.
441      properties:
442        type:
443          type: string
444          format: uri
445          description: An absolute URI that identifies the problem type.
446        title:
447          type: string
448          description: A short, human-readable summary of the problem type.
449        status:
450          type: integer
451          format: int32
452          description: The HTTP status code generated by the origin server for this occurrence of the problem.
453        detail:
454          type: string
455          description: A human-readable explanation specific to this occurrence of the problem.
456        instance:
457          type: string
458          format: uri
459          description: An absolute URI that identifies the specific occurrence of the problem.
460      required: [title, status, detail]