Table of contents
API Key
The API key is a (secret) key with which, by adding it to a specific request header, you can invoke the APIs (for more details refer to the section Authentication of OpenAPI).
You can view and regenerate the keys as the institution administrator.
Why are there two keys?
Each API key is comprised of a pair of keys: primary and secondary. These keys are equivalent and permit: changing them (regenerating them) without interrupting the service.
- avoiding service interruptions: you can change (regenerate) the key pair without malfunctions;
- sharing the key temporarily: in some occasions, you may want to share the API key with your colleagues. Instead of sharing the primary key (which is used in your applications), share the secondary key. Regenerate the second key when you want to revoke access for that person. Once you have regenerated the second key, the old secondary key will no longer be valid.
Best practices for managing the API keys
When you use the API keys in your applications, make sure they are protected both during storage as well as during transmission.
Only keep the API keys that you are using at the moment to minimize the attack surface.
If you rotate the API keys periodically, you can limit the impact of any compromised keys.
To avoid service interruptions, proceed as follows:
- Update the applications such that they use the secondary key
- Regenerate the primary key
- Update the applications such that they use the primary key that was just regenerated
- Regenerate the secondary key
The API keys hardcoded in the source code or archived in a repository are subject to interception and theft by criminals. In client-side environments (such as a browser or mobile applications) the client must pass the requests to its backend server, which can add the key and issue the request.
Monitoring the use of the APIs can help you detect unauthorized use.
On this page
Haven't completed onboarding yet and need help?
Write an email describing your problem or question to the address areariservata@assistenza.pagopa.it.
Tell us what you think
To report problems or give feedback, leave a comment in the GitHub space of the IO app