Tabella dei contenuti
How to request a Bearer voucher for a producer's API (standard)
More information on this implementation can be found in the dedicated section.
Essentially, the end-to-end process requires five steps:
- The consumer generates the client assertion;
- The consumer requests the voucher from PDND’s authorization server;
- PDND’s authorization server performs the necessary checks. If successful, it returns a voucher;
- The consumer makes a request to the producer’s e-service, inserting the voucher issued by PDND in the Authorization header;
- The producer performs the necessary checks. If successful, it processes the consumer’s request.
It is assumed that the consumer has:
- Created an e-service type client (read tutorial).
- Generated at least one set of cryptographic material and uploaded the related public key to PDND within the client (read tutorial).
- Associated the client with the purpose for which they want to obtain or send data to the producer (read tutorial).
The first step is to build a valid client assertion. The client assertion is composed of a header and a payload containing the following fields.
Header:
| Field name | Meaning |
|---|---|
| kid | the ID of the key used to sign the assertion, available on PDND |
| alg | the algorithm used to sign the JWT (for now, always RS256) |
| typ | the type of object being sent (always JWT) |
Payload:
| Field name | Meaning |
|---|---|
| iss | the issuer, in this case the clientId |
| sub | the subject, in this case always the clientId |
| aud | the audience, available on PDND |
| jti | the JWT ID, a unique random ID assigned by whoever is creating the token, used to track the token itself. It is the caller’s responsibility to ensure that the ID of this token is unique for the client assertion |
| iat | issued at, the timestamp indicating when the token was created, expressed in UNIX epoch (numeric value, not a string) |
| exp | expiration, the timestamp indicating when the token expires, expressed in UNIX epoch (numeric value, not a string) |
| purposeId | The ID of the specific purpose for which you want to obtain a voucher, available in the back office |
As an example, here is a deserialized client assertion to highlight its contents.
Header:
1{
2 "alg": "RS256",
3 "kid": "2MJFa7aSSveFte8ULX9U-MaaygcoL5fBIJDTXBdba64",
4 "typ": "jwt"
5}
6Payload:
1{
2 "iss": "8e9f24ca-78f5-4c69-9e4f-0efbeac7bb2b",
3 "sub": "8e9f24ca-78f5-4c69-9e4f-0efbeac7bb2b",
4 "aud": "auth.interop.pagopa.it/client-assertion",
5 "jti": "23387ac1-c192-4573-8350-207a4213d4be",
6 "iat": 1616170068,
7 "exp": 1616170668,
8 "purposeId": "34f1624b-91cb-4b05-b8c0-cad208a30222"
9}
10After building a valid client assertion, it must be signed with your private key (the counterpart of the public key uploaded to the client in PDND).
For demonstration purposes, a Python script has been published showing how to perform the operation. All instructions are available in the back office, within your client.
A function is also available to check the validity of your client assertion and highlight any errors. The tool is available in the back office under Developers Tools > Debug client assertion.
The second step is to call PDND’s authorization server with the signed client assertion to obtain a voucher that can be used with the producer’s APIs.
The endpoint URL for the authorization server depends on the environment and will be clearly visible in the interface within the back office.
The endpoint must be called with the following parameters in the body:
| Field name | Meaning |
|---|---|
| client_id | again, the clientId used in the assertion |
| client_assertion | the signed client assertion from the first step |
| client_assertion_type | the client assertion format, as indicated in RFC (always urn:ietf:params:oauth:client-assertion-type:jwt-bearer) |
| grant_type | the type of flow used, as indicated in RFC (always client_credentials) |
If everything is set up correctly, PDND will respond with a valid voucher in the access_token property of the response body.
Also in the response, you will find the voucher’s validity duration in seconds (e.g., "expires_in": 600 means a voucher valid for 10 minutes, 10 × 60 seconds = 600). The voucher’s duration is chosen by the producer based on their security considerations.
The response returned by the PDND authorization server is as follows:
1{
2 "access_token": "eyJ0eXAiOiJhdCtqd3QiLC...",
3 "expires_in": 600
4}
5If we decode the access_token field, we get
Header:
1{
2 "typ": "at+jwt",
3 "alg": "RS256",
4 "kid": "{KID_CHIAVE_PDND}"
5}
6Payload:
1{
2 "iss": "interop.pagopa.it",
3 "nbf": 1747408537,
4 "iat": 1747408537,
5 "exp": 1747409537,
6 "jti": "12297ac1-c192-4573-8350-207a4213e5ac",
7 "aud": "https://eservice.pa.it/api/v1",
8 "sub": "9b361d49-33f4-4f1e-a88b-4e12661f2309",
9 "client_id": "9b361d49-33f4-4f1e-a88b-4e12661f2309",
10 "purposeId": "1b361d49-33f4-4f1e-a88b-4e12661f2300",
11 "producerId" : "0e9e2dab-2e93-4f24-ba59-38d9f11198ca",
12 "consumerId" : "69e2865e-65ab-4e48-a638-2037a9ee2ee7",
13 "eserviceId" : "b8c6d7ad-93fc-4eaf-9018-3cd8bf98163f",
14 "descriptorId": "9525a54b-9157-4b46-8976-ec66f20b7d7e"
15}
16Step 4 - Request data from the producer
The voucher must be included in the header of all subsequent calls to the producer's API. It must be placed in the Authorization header, as follows:
1Authorization: Bearer <voucher>
2Step 5 - Waiting for the producer's checks
The producer performs all necessary checks.
If everything is in order, they process the consumer’s request — returning the requested data in the case of a data-producing e-service, or accepting data from the consumer in the case of a data-receiving e-service.
For recommended checks for producers, see the dedicated section.
Hai bisogno di aiuto?
Apri un ticket utilizzando l’apposita funzione all’interno della tua Area Riservata
