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: EAA Creation <Name / EAA Type Name> – IT-Wallet

  • 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: <Official 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 (always required)
 10      - <b>INTEGRITY_REST_02</b>: Requests and responses are signed
 11      - <b>REST_JWS_2021_POP</b>: Proof of possession of the PDND Voucher (POP_DPoP per RFC 9449, or POP_TPoP)
 12      - <b>AUDIT_REST_02</b>: Optional. The Provider MAY require additional tracked data from the Consumer; if so, this pattern MUST be used, including together with POP_DPoP, via the optional `Agid-JWT-TrackingEvidence` header
 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  - DPoPVoucherAuth: []
 26    DPoPProof: []
 27  - BearerAuth: []
 28    TrackingEvidenceAuth: []
 29paths:
 30  /status:
 31    get:
 32      tags:
 33        - status
 34      summary: Get Authentic Source API status.
 35      description: Health-check endpoint that returns the operational status of the Authentic Source API.
 36      operationId: authenticSourceStatus
 37      responses:
 38        "200":
 39          description: Service available
 40          content:
 41            application/problem+json:
 42              schema:
 43                $ref: "#/components/schemas/ProblemDetails"
 44          headers:
 45            Cache-Control:
 46              $ref: "#/components/headers/CacheControlHeader"
 47            X-RateLimit-Limit:
 48              $ref: "#/components/headers/RateLimitLimitHeader"
 49            X-RateLimit-Remaining:
 50              $ref: "#/components/headers/RateLimitRemainingHeader"
 51            X-RateLimit-Reset:
 52              $ref: "#/components/headers/RateLimitResetHeader"
 53        "429":
 54          description: Too Many Requests
 55          content:
 56            application/problem+json:
 57              schema:
 58                $ref: "#/components/schemas/ProblemDetails"
 59          headers:
 60            # RFC 6585 defines Retry-After. X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset are not required because redundant along with Retry-After.
 61            Retry-After:
 62              $ref: "#/components/headers/RetryAfterHeader"
 63        "503":
 64          description: Service Unavailable
 65          content:
 66            application/problem+json:
 67              schema:
 68                $ref: "#/components/schemas/ProblemDetails"
 69          headers:
 70            Retry-After:
 71              $ref: "#/components/headers/RetryAfterHeader"
 72
 73  /attribute-claims/{datasetId}:
 74    post:
 75      tags:
 76        - credential
 77      summary: Get Attribute Claims
 78      description: >-
 79        This service provides the Credential Issuer with all attribute claims necessary for the issuance of a Digital Credential
 80      operationId: attributeClaims
 81      parameters:
 82        - in: path
 83          name: datasetId
 84          schema:
 85            type: string
 86          required: true
 87          description: Identifier of the dataset as registered in the Authentic Source Registry
 88        - name: Agid-JWT-Signature
 89          in: header
 90          description: >-
 91            JWT containing the signature of the message headers whose integrity
 92            needs to be guaranteed, to comply with the INTEGRITY_REST_02
 93            security pattern (see <a target="blank"
 94            href="https://italia.github.io/eid-wallet-it-docs/versione-corrente/en/e-service-pdnd.html">e-Service PDND</a>). <br/><br/>
 95
 96            <a target="blank" href="https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJzdWIiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImlhdCI6MTczMzM5Nzg0MCwibmJmIjoxNzMzNDAxNjI4LCJleHAiOjE3MzM0MDE0NDAsImp0aSI6ImQzZjdiMmM5LTI3NGEtNDJiNy04ZjhkLTJlOWQ4YjE3MzRiMCIsInNpZ25lZF9oZWFkZXJzIjpbeyJkaWdlc3QiOiJTSEEtMjU2PTcyZTE4YmRkZGYxM2M5MTFiNGRkNTYyZWUyMTk3OWE1YzlmMjM1YzNhMDFiZDE0MjZlODU3ZDhjMWEyODJmNDEifSx7ImNvbnRlbnQtdHlwZSI6ImFwcGxpY2F0aW9uL2pzb24ifV19.tG5-P96CCA6N1IYC-xk4GumoVkA3NFolpbBn2vQ2e9vpWQ8f5Sm2l4-1VrXfKTx-CUVz_puiwqkBhulrNKj2fA">EXAMPLE
 97            ON JWT.IO</a>
 98          required: true
 99          schema:
100            type: string
101            format: JWT
102            example: eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJzdWIiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImlhdCI6MTczMzM5Nzg0MCwibmJmIjoxNzMzNDAxNjI4LCJleHAiOjE3MzM0MDE0NDAsImp0aSI6ImQzZjdiMmM5LTI3NGEtNDJiNy04ZjhkLTJlOWQ4YjE3MzRiMCIsInNpZ25lZF9oZWFkZXJzIjpbeyJkaWdlc3QiOiJTSEEtMjU2PTcyZTE4YmRkZGYxM2M5MTFiNGRkNTYyZWUyMTk3OWE1YzlmMjM1YzNhMDFiZDE0MjZlODU3ZDhjMWEyODJmNDEifSx7ImNvbnRlbnQtdHlwZSI6ImFwcGxpY2F0aW9uL2pzb24ifV19.tG5-P96CCA6N1IYC-xk4GumoVkA3NFolpbBn2vQ2e9vpWQ8f5Sm2l4-1VrXfKTx-CUVz_puiwqkBhulrNKj2fA
103        - name: Digest
104          in: header
105          description: >-
106            Digest of the message payload, to comply with the INTEGRITY_REST_02
107            security pattern. According to <a target="blank" href="https://www.rfc-editor.org/rfc/rfc3230.html#section-4.2">RFC
108            3230 §4.2</a>, the format MUST be the following: digest-algorithm=encoded
109            digest output.
110          required: true
111          schema:
112            type: string
113            example: SHA-256=72e18bdddf13c911b4dd562ee21979a5c9f235c3a01bd1426e857d8c1a282f41
114        - name: Agid-JWT-TrackingEvidence
115          in: header
116          description: >-
117            TrackingEvidence JWT for AUDIT_REST_02. Optional. It MAY be sent
118            together with POP_DPoP (`Authorization: DPoP` and the `DPoP` proof)
119            when the Provider requires tracked data from the Consumer, such as
120            caller LoA, userID, IP address, or other data agreed with the
121            Provider. The DPoP proof remains the proof of possession. When the
122            Provider mandates AUDIT_REST_02, this header MUST be present.
123            For POP_TPoP the same header is required by `TrackingEvidenceAuth`
124            together with `BearerAuth`; send a single header value
125            (see <a target="blank"
126            href="https://italia.github.io/eid-wallet-it-docs/versione-corrente/en/e-service-pdnd.html">e-Service PDND</a>). <br/><br/>
127            <a target="blank" href="https://jwt.io/#debugger-io?token=eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImV4cCI6MTczMzA1MjYwMCwibmJmIjoxNzMzMDM2NDUwLCJpYXQiOjE3MzMwMzY0MDAsImp0aSI6ImE0YjVjNmQ3LWU4ZjktYWJjZC1lZjEyLTM0NTY3ODkwMTIzNCIsImRub25jZSI6NjUyODQyNDIxMzY4NSwicHVycG9zZUlkIjoiYjJjM2Q0ZTUtZjZnNy1oOGk5LWowazEtbG1ubzEyMzQ1Njc4IiwidXNlcklEIjoiYThiN2M2ZDUtZTRmMy1nMmgxLWk5ajAta2xtbm9wcXJzdHV2IiwibG9hIjoic3Vic3RhbnRpYWwifQ.y42yfMeW2H9h0b0j0BODUml8yF20stY9q3BwoVU5BB90afBj852Q0QlInncdhjXhUjLS1V76cGBxkutDNvxRNA">EXAMPLE
128            ON JWT.IO</a>
129          required: false
130          schema:
131            type: string
132            format: JWT
133            example: eyJhbGciOiJFUzI1NiIsImtpZCI6ImQ0YzNiMmExLTk4NzYtNTQzMi0xMGZlLWRjYmE5ODc2NTQzMiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI4MjkxNGIzZi02MGIyLTQ1MjktYjRkNi0zZDRlNjdmMGE5MzMiLCJhdWQiOiJodHRwczovL2F1dGhlbnRpYy1zb3VyY2UuZXhhbXBsZS5pdCIsImV4cCI6MTczMzA1MjYwMCwibmJmIjoxNzMzMDM2NDUwLCJpYXQiOjE3MzMwMzY0MDAsImp0aSI6ImE0YjVjNmQ3LWU4ZjktYWJjZC1lZjEyLTM0NTY3ODkwMTIzNCIsImRub25jZSI6NjUyODQyNDIxMzY4NSwicHVycG9zZUlkIjoiYjJjM2Q0ZTUtZjZnNy1oOGk5LWowazEtbG1ubzEyMzQ1Njc4IiwidXNlcklEIjoiYThiN2M2ZDUtZTRmMy1nMmgxLWk5ajAta2xtbm9wcXJzdHV2IiwibG9hIjoic3Vic3RhbnRpYWwifQ.y42yfMeW2H9h0b0j0BODUml8yF20stY9q3BwoVU5BB90afBj852Q0QlInncdhjXhUjLS1V76cGBxkutDNvxRNA
134      requestBody:
135        required: true
136        content:
137          application/json:
138            schema:
139              $ref: "#/components/schemas/CredentialClaimsRequest"
140      responses:
141        "200":
142          description: OK
143          headers:
144            Agid-JWT-Signature:
145              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
146              required: true
147              schema:
148                type: string
149            Digest:
150              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.
151              required: true
152              schema:
153                type: string
154                example: SHA-256=79a20a744336420301830600ad9bdca993593f876209a004b599b583095b0a61
155            Cache-Control:
156              $ref: "#/components/headers/CacheControlHeader"
157            X-RateLimit-Limit:
158              $ref: "#/components/headers/RateLimitLimitHeader"
159            X-RateLimit-Remaining:
160              $ref: "#/components/headers/RateLimitRemainingHeader"
161            X-RateLimit-Reset:
162              $ref: "#/components/headers/RateLimitResetHeader"
163          content:
164            application/json:
165              schema:
166                $ref: "#/components/schemas/CredentialClaimsResponse"
167              example:
168                interval: 864000
169                userClaims:
170                  given_name: "Mario"
171                  family_name: "Rossi"
172                  birth_date: "1980-01-10"
173                  place_of_birth:
174                    country: "IT"
175                    region: "Roma"
176                    locality: "Roma"
177                  tax_id_code: "TINIT-RSSMRA80A01H501Z"
178                  personal_administrative_number: "12345A123A"
179                attributeClaims:
180                  - object_id: "6F9619FF-8B86-D011-B42D-00C04FC964FF"
181                    status: "VALID"
182                    last_updated: "2025-01-15T10:30:00Z"
183                    institute_name: "Nome Istituto Universitario"
184                    programme_type_name: "Laurea Magistrale"
185                    degree_course_name: "Computer Science - Informatica"
186                    academic_qualification_date: "2025-06-25"
187                  - object_id: "7A0720AB-9C97-E122-C53E-11D05FD075GG"
188                    status: "VALID"
189                    last_updated: "2025-01-10T08:00:00Z"
190                    institute_name: "Nome Istituto Universitario"
191                    programme_type_name: "Laurea Triennale"
192                    degree_course_name: "Informatica"
193                    academic_qualification_date: "2022-11-27"
194                metadataClaims:
195                  - object_id: "6F9619FF-8B86-D011-B42D-00C04FC964FF"
196                    issuance_date: "2025-06-25"
197                  - object_id: "7A0720AB-9C97-E122-C53E-11D05FD075GG"
198                    issuance_date: "2022-11-27"
199        "400":
200          description: Bad Request
201          content:
202            application/problem+json:
203              schema:
204                $ref: "#/components/schemas/ProblemDetails"
205          headers:
206            X-RateLimit-Limit:
207              $ref: "#/components/headers/RateLimitLimitHeader"
208            X-RateLimit-Remaining:
209              $ref: "#/components/headers/RateLimitRemainingHeader"
210            X-RateLimit-Reset:
211              $ref: "#/components/headers/RateLimitResetHeader"
212        "401":
213          description: Unauthorized
214          content:
215            application/problem+json:
216              schema:
217                $ref: "#/components/schemas/ProblemDetails"
218          headers:
219            X-RateLimit-Limit:
220              $ref: "#/components/headers/RateLimitLimitHeader"
221            X-RateLimit-Remaining:
222              $ref: "#/components/headers/RateLimitRemainingHeader"
223            X-RateLimit-Reset:
224              $ref: "#/components/headers/RateLimitResetHeader"
225            WWW-Authenticate:
226              $ref: "#/components/headers/WWWAuthenticateHeader"
227        "404":
228          description: Claims not found
229          content:
230            application/problem+json:
231              schema:
232                $ref: "#/components/schemas/ProblemDetails"
233          headers:
234            X-RateLimit-Limit:
235              $ref: "#/components/headers/RateLimitLimitHeader"
236            X-RateLimit-Remaining:
237              $ref: "#/components/headers/RateLimitRemainingHeader"
238            X-RateLimit-Reset:
239              $ref: "#/components/headers/RateLimitResetHeader"
240        "429":
241          description: Too Many Requests
242          content:
243            application/problem+json:
244              schema:
245                $ref: "#/components/schemas/ProblemDetails"
246          headers:
247            # RFC 6585 defines Retry-After. X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset are not required because redundant along with Retry-After.
248            Retry-After:
249              $ref: "#/components/headers/RetryAfterHeader"
250        "500":
251          description: Internal Server Error.
252          content:
253            application/problem+json:
254              schema:
255                $ref: "#/components/schemas/ProblemDetails"
256          headers:
257            Retry-After:
258              $ref: "#/components/headers/RetryAfterHeader"
259        "503":
260          description: Service Unavailable
261          content:
262            application/problem+json:
263              schema:
264                $ref: "#/components/schemas/ProblemDetails"
265          headers:
266            Retry-After:
267              $ref: "#/components/headers/RetryAfterHeader"
268
269tags:
270  - name: status
271    description: Endpoint di health check dell'API.
272  - name: credential
273    description: Retrieve information about the credential.
274
275components:
276  securitySchemes:
277    DPoPVoucherAuth:
278      type: http
279      scheme: DPoP
280      description: >-
281        PDND Voucher issued with DPoP binding (POP_DPoP, RFC 9449). The
282        `Authorization` header MUST be `DPoP <voucher>` (`token_type` is `DPoP`).
283        This scheme MUST be used together with `DPoPProof`. It MUST NOT be
284        modelled as HTTP Bearer: a conformant Provider rejects
285        `Authorization: Bearer` for a DPoP-bound Voucher.
286    DPoPProof:
287      type: apiKey
288      in: header
289      name: DPoP
290      description: >-
291        DPoP proof JWT (RFC 9449). REQUIRED together with `DPoPVoucherAuth`
292        (POP_DPoP). MUST NOT be sent with `BearerAuth` (POP_TPoP), where proof
293        of possession is `Agid-JWT-TrackingEvidence`.
294    BearerAuth:
295      type: http
296      scheme: bearer
297      bearerFormat: JWT
298      description: >-
299        PDND Voucher issued as Bearer (POP_TPoP). The `Authorization` header
300        MUST be `Bearer <voucher>` (`token_type` is `Bearer`). This scheme MUST
301        be used together with `TrackingEvidenceAuth` as proof of possession.
302        This is REST_JWS_2021_POP via TrackingEvidence, not REST_JWS_2021_Bearer.
303    TrackingEvidenceAuth:
304      type: apiKey
305      in: header
306      name: Agid-JWT-TrackingEvidence
307      description: >-
308        TrackingEvidence JWT. REQUIRED together with `BearerAuth` (POP_TPoP) as
309        proof of possession of the PDND Voucher. The same header is also an
310        optional operation parameter, so it MAY be sent with the POP_DPoP pair
311        (`DPoPVoucherAuth` + `DPoPProof`) when the Provider requires
312        AUDIT_REST_02. The DPoP proof remains the proof of possession.
313        See e-Service PDND in the Technical Specifications.
314
315  headers:
316    CacheControlHeader:
317      schema:
318        type: string
319        enum:
320          - no-store
321      description: no-store
322    RateLimitLimitHeader:
323      schema:
324        type: integer
325        format: int32
326        minimum: 0
327      description: Maximum number of requests within the time window.
328    RateLimitRemainingHeader:
329      schema:
330        type: integer
331        format: int32
332        minimum: 0
333      description: Remaining requests within the time window.
334    RateLimitResetHeader:
335      schema:
336        type: integer
337        format: int32
338        minimum: 0
339      description: UTC epoch in seconds, corresponding to when the window for the current rate limit will reset.
340    RetryAfterHeader:
341      schema:
342        type: integer
343        format: int32
344        minimum: 0
345      description: Seconds to wait before receiving another response.
346    WWWAuthenticateHeader:
347      schema:
348        type: string
349        example: >-
350          Bearer error="invalid_token", error_description="The access token expired"
351      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.
352
353  schemas:
354    CredentialClaimsResponse:
355      type: object
356      properties:
357        userClaims:
358          description: List of User Claims.
359          type: object
360          properties:
361            given_name:
362              description: Current First Name.
363              type: string
364              example: "Mario"
365            family_name:
366              description: Current Family Name.
367              type: string
368              example: "Rossi"
369            birth_date:
370              description: Date of Birth.
371              type: string
372              example: "1980-01-10"
373            place_of_birth:
374              $ref: "#/components/schemas/place_of_birth"
375            tax_id_code:
376              description: National tax identification number. REQUIRED if personal_administrative_number is absent.
377              type: string
378              example: "TINIT-XXXXXXXXXXXXXXXX"
379            personal_administrative_number:
380              description: National unique identifier of a natural person. REQUIRED if tax_id_code is absent.
381              type: string
382              example: "XX00000XX"
383        attributeClaims:
384          description: List of Datasets of Attribute.
385          type: array
386          items:
387            type: object
388            properties:
389              object_id:
390                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.
391                type: string
392                example: "6F9619FF-8B86-D011-B42D-00C04FC964FF"
393              issuance_date:
394                description: Administrative validity start date of the Dataset
395                type: string
396                example: "2025-01-01"
397              expiry_date:
398                description: Administrative expiry date of the Dataset.
399                type: string
400                example: "2025-12-31"
401            additionalProperties:
402              oneOf:
403                - type: string
404                - type: integer
405                  format: int32
406                - type: integer
407                  format: int64
408                - type: number
409                  format: float
410                - type: number
411                  format: double
412                - type: boolean
413                - type: array
414                  items:
415                    $ref: '#/components/schemas/additionalPropertiesArray'
416                - type: object
417                  additionalProperties:
418                    $ref: '#/components/schemas/additionalPropertiesObject'
419            required: [object_id]
420        metadataClaims:
421          description: List of Metadata of Attribute.
422          type: array
423          items:
424            type: object
425            properties:
426              object_id:
427                description: Unique identifier of the Dataset. It MUST NOT contain personal data.
428                type: string
429                example: "6F9619FF-8B86-D011-B42D-00C04FC964FF"
430              description:
431                description: Human-Readable description of the Dataset.
432                type: string
433                example: "Example: Master's Degree in Computer Science"
434              status:
435                description: |
436                  Status of the Dataset. REQUIRED if additionalProperties of attributeClaims are present. Issued and Expired datasets fall within VALID; expiry is verified
437                  via metadata claims (e.g. expiry_date, nbf/exp). INVALID indicates active revocation by the AS.
438                  For how this status affects the Digital Credential lifecycle managed by the Credential
439                  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>.
440                type: string
441                enum:
442                  - VALID
443                  - INVALID
444                  - SUSPENDED
445                x-enum-description:
446                  - VALID - Dataset is valid (includes Issued and Expired; expiry checked via metadata).
447                  - INVALID - Dataset has been actively revoked by the Authentic Source.
448                  - SUSPENDED - Dataset is temporarily invalid (typically reversible).
449                example: "VALID"
450              status_description:
451                description: Human-Readable description of the Status.
452                type: string
453                example: "Example: Master's Degree in Computer Science"
454              last_updated:
455                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`.
456                type: string
457                example: "2025-01-15T10:30:00Z"
458              interval:
459                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.
460                type: integer
461                format: int64
462                example: 864000
463            required: [object_id, description]
464      required: [attributeClaims, metadataClaims]
465    CredentialClaimsRequest:
466      required:
467        - unique_id
468      type: object
469      properties:
470        unique_id:
471          type: string
472          description: ID ANPR or Tax identification number
473        object_id:
474          type: string
475          description: Unique identifier of the Credential dataset. If this parameter is present only the indicated dataset is returned.
476    additionalPropertiesArray:
477      type: array
478      items:
479        oneOf:
480        - type: string
481        - type: integer
482          format: int32
483        - type: integer
484          format: int64
485        - type: number
486          format: float
487        - type: number
488          format: double
489        - type: boolean
490        - type: object
491          additionalProperties:
492            $ref: '#/components/schemas/additionalPropertiesObject'
493    additionalPropertiesObject:
494      type: object
495      oneOf:
496        - type: string
497        - type: integer
498          format: int32
499        - type: integer
500          format: int64
501        - type: number
502          format: float
503        - type: number
504          format: double
505        - type: boolean
506    place_of_birth:
507      description: Place of Birth.
508      type: object
509      properties:
510        country:
511          description: "alpha-2 country code as specified in ISO 3166-1"
512          type: string
513          example: "IT"
514        region:
515          description: "Name of a state, province, district, or local area"
516          type: string
517          example: "Roma"
518        locality:
519          description: "Name of a municipality, city, town, or village"
520          type: string
521          example: "Roma"
522      anyOf:
523        - required: [country]
524        - required: [region]
525        - required: [locality]
526    ProblemDetails:
527      type: object
528      description: RFC7807-compliant problem details object for error responses.
529      properties:
530        type:
531          type: string
532          format: uri
533          description: An absolute URI that identifies the problem type.
534        title:
535          type: string
536          description: A short, human-readable summary of the problem type.
537        status:
538          type: integer
539          format: int32
540          description: The HTTP status code generated by the origin server for this occurrence of the problem.
541        detail:
542          type: string
543          description: A human-readable explanation specific to this occurrence of the problem.
544        instance:
545          type: string
546          format: uri
547          description: An absolute URI that identifies the specific occurrence of the problem.
548      required: [title, status, detail]