20.3. PDND e-Service Template

La PDND fornisce uno strumento specializzato che migliora i processi di co-progettazione delle API ottimizzando la pubblicazione e il riutilizzo dei servizi elettronici. Questa funzionalità è definita e regolamentata nel presente documento.

  • "Linee Guida sull'infrastruttura tecnologica della Piattaforma Digitale Nazionale Dati per l'interoperabilità dei sistemi informativi e delle basi di dati" (PDND).

Il template del servizio elettronico serve come modello standardizzato contenente tutti i metadati tecnici e descrittivi necessari per un servizio elettronico. I Gestori delle API, che possono essere sia Fornitori che Consumatori all'interno dell'ecosistema PDND, POSSONO creare e mantenere questi template.

Una volta che un e-service template è pubblicato, è accessibile attraverso il Catalogo Template PDND che è un repository centralizzato che facilita il riutilizzo. Questo catalogo consente a qualsiasi Partecipante PDND autorizzato di sfogliare i template disponibili e istanziare nuovi servizi elettronici basati su progetti esistenti.

20.3.1. Definizione e linee guida dell'e-service template PDND

L'infrastruttura PDND supporta la gestione del ciclo di vita dei Servizi Elettronici Template, simile a quella dei servizi elettronici tradizionali. Gli stati del ciclo di vita includono: Draft, Active, Suspended e Deprecated. Come per i servizi elettronici tradizionali, PDND applica il controllo degli accessi basato sui ruoli per governare le transizioni di stato.

20.3.1.1. Gestione dei Servizi Elettronici Template

20.3.1.1.1. Creazione del Servizio Elettronico Template

I Partecipanti sono abilitati a creare Servizi Elettronici Template tramite una procedura guidata accessibile attraverso l'interfaccia web PDND (le API saranno disponibili in futuro). Il flusso di lavoro di creazione rispecchia da vicino quello della creazione standard di servizi elettronici, con le seguenti distinzioni:

  • Un campo aggiuntivo identifica il destinatario previsto del template.

  • Il campo "Audience" è omesso.

  • Le soglie sono opzionali e servono come raccomandazioni per i Partecipanti che implementano il template.

Ai Partecipanti è vietato creare più template con lo stesso nome: i nomi dei template DEVONO essere unici per partecipante. Alla creazione, un template è inizialmente impostato sullo stato Draft. I template possono quindi essere pubblicati nel Catalogo Template, rendendoli così accessibili a tutti i Partecipanti.

20.3.1.1.2. Modifica del Servizio Elettronico Template

I Partecipanti che hanno creato un template possono modificarlo. La portata dei campi modificabili dipende dallo stato del ciclo di vita del template:

  • Se il template è in stato Draft, tutti i campi sono modificabili.

  • Per i template in altri stati, solo un sottoinsieme limitato di campi può essere modificato direttamente.

  • I campi che non possono essere modificati nei template pubblicati richiedono la creazione di una nuova versione del template per applicare le modifiche.

Il versionamento dei template funziona in modo simile a quello dei servizi elettronici, dato che le modifiche al modello possono impattare i servizi istanziati e quindi i Partecipanti che consumano quell'istanza.

I seguenti campi possono essere modificati senza attivare una nuova versione del template:

  • Name

  • Intended Recipient

  • Description

  • Voucher Time Limit

  • Documentation (escludendo la specifica OpenAPI)

  • Attributes

20.3.1.1.3. Sospensione del e-service Template

I template, come i servizi elettronici, possono essere Sospesi. Quando sospesi:

  • Il template viene rimosso dal catalogo pubblico dei template.

  • L'istanziazione di nuove istanze dal template sospeso è disabilitata.

  • Le istanze precedentemente istanziate rimangono inalterate.

  • I template possono essere riattivati in qualsiasi momento.

  • I template non possono essere eliminati.

20.3.1.1.4. Istanziazione del e-service Template

I Partecipanti POSSONO istanziare un Servizio Elettronico Template sfogliando il Catalogo Template e selezionando un template. Questo processo genera un nuovo servizio elettronico.

I vincoli di istanziazione includono:

  • Solo i template in stato Attivo sono idonei per l'istanziazione.

  • L'istanziazione è facilitata attraverso una procedura guidata nell'interfaccia web PDND.

  • A causa dell'obiettivo di standardizzazione dei template, la maggior parte dei campi è pre-compilata e immutabile durante l'istanziazione.

  • Le seguenti informazioni non possono essere modificate durante l'istanziazione:

    • Caricamento della documentazione

    • Tempo di scadenza del token

    • Nome, descrizione e attributi

Invece, i seguenti campi devono essere specificati durante l'istanziazione:

  • Audience

  • Thresholds

  • Automatic/Manual Approval Policy

Inoltre, sebbene la specifica OpenAPI sia fissa, i seguenti campi di metadati possono essere forniti in modo che PDND possa aggiornare automaticamente la specifica YAML:

  • Contatti (nome, email, URL, URL Termini e Condizioni)

  • URL del server

Ogni servizio elettronico istanziato mantiene un ciclo di vita indipendente analogo ai servizi elettronici standard.

20.3.1.2. Gestione delle Versioni

Il versioning dei template segue un processo controllato:

  • La pubblicazione di una nuova versione del template la imposta su Active.

  • La versione precedentemente Active viene automaticamente trasferita a Deprecated.

  • È consentita solo una versione Active per template in qualsiasi momento.

  • I template possono anche avere una singola versione Draft che coesiste con la versione Active.

Le istanze derivate dai template mantengono un versioning indipendente poiché i Partecipanti possono aggiornare i campi specifici dell'istanza (ad esempio, URL del server) più volte, mentre l'istanza rimane collegata alla versione del template di origine.

Di conseguenza, le versioni dei template e le versioni delle istanze sono indipendenti e non direttamente correlate.

I Partecipanti che istanziano un template possono quindi aggiornare sia l'istanza specifica o, se disponibile, aggiornare a una versione più recente del template.

20.3.1.3. Template per Fonte Autentica

La funzionalità del servizio elettronico template viene utilizzata per standardizzare la trasmissione dei dati dalle Fonti Autentiche ai Fornitori di Attestati Elettronici. Il servizio elettronico template DOVREBBE essere pubblicato all'interno della PDND dal Fornitore di Attestati Elettronici ed è accessibile attraverso il Catalogo Template PDND.

20.3.1.3.1. Parametri del Template per Fonte Autentica

Il servizio elettronico template DEVE rispettare le seguenti proprietà:

  • Name: Creazione EAA <Nome / Nome tipologia EAA> – IT-Wallet

  • Intended Recipients: IT Wallet - Fonte Autentica - <Dominio della Fonte Autentica>

  • Description: Descrizioni utili al Fornitore di Attestati Elettronici in relazione al nuovo attestato elettronico <Nome dell'Attestato Elettronico>

  • Technology: REST

  • Data variation via Signal Hub: True

  • Version changelog: Servizio elettronico Fonte Autentica tramite implementazione template

  • Voucher Time Limit: 20

  • Suggest custom threshold: False

  • Suggest manual agreement approval policy: False

  • Attributes: <Nome ufficiale dell'Ente Pubblico Fornitore di Attestati Elettronici>

20.3.1.3.2. Istanziazione del Template per Fonte Autentica

Ogni Fonte Autentica DOVREBBE istanziare il servizio elettronico template IT Wallet - Fonte Autentica nella PDND. Il processo di istanziazione risulterà in un nuovo servizio elettronico che DEVE soddisfare i seguenti requisiti:

  • Signal Hub: True

  • Politica di approvazione manuale: False

  • Soglia giornaliera chiamate API per ogni fornitore: maggiore di 10000

  • Soglia giornaliera chiamate API: maggiore di 10000

Informazioni aggiuntive richieste durante il processo di creazione sono dipendenti dal fornitore.

20.3.1.3.3. Specifica OpenAPI della Fonte Autentica PDND

Di seguito è riportata la specifica OpenAPI completa per i servizi elettronici della Fonte Autentica PDND:

  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                  Stato del Dataset. OBBLIGATORIO se additionalProperties di attributeClaims sono presenti. I dataset Issued e Expired ricadono in VALID; la scadenza è verificata
437                  tramite metadata claims (es. expiry_date, nbf/exp). INVALID indica revoca attiva da parte dell'AS.
438                  Per come questo stato influenza il ciclo di vita dell'Attestato Elettronico gestito dal
439                  Fornitore di Attestati Elettronici, vedere la sezione <a target="blank" href="https://italia.github.io/eid-wallet-it-docs/versione-corrente/it/credential-revocation.html#aggiornamento-dello-stato-da-parte-delle-fonti-autentiche">Aggiornamento dello Stato da parte delle Fonti Autentiche</a>.
440                type: string
441                enum:
442                  - VALID
443                  - INVALID
444                  - SUSPENDED
445                x-enum-description:
446                  - VALID - Il dataset è valido (include Issued e Expired; la scadenza è verificata via metadata).
447                  - INVALID - Il dataset è stato attivamente revocato dalla Fonte Autentica.
448                  - SUSPENDED - Il dataset è temporaneamente non valido (tipicamente reversibile).
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: OBBLIGATORIO se additionalProperties di attributeClaims sono presenti. 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]