This page describes the end-to-end authentication flow using ESP. Each step corresponds to a specific API call. For detailed parameter reference, see the individual endpoint pages.
All server-side API calls to ESP require an API key provided by Namirial during the Setup Test Environment phase.
Include it in every request as a header:
Esp-Api-Key: YOUR_API_KEYLogin and Logout are browser-based redirects — no API key is required for those calls.
Before redirecting the user to the identity provider, your application must obtain a session key (authnKey) from ESP.
Call the Get Key endpoint, specifying the authentication level and the attribute set required:
level:1,2, or3attributes:BaseorFull
The response is a string (authnKey) that identifies the authentication session. It must be passed to the login endpoint in the next step.
Use the authnKey obtained in Step 1 to build the login URL and open it in the user's browser.
ESP redirects the user to the selected identity provider (SPID, CIE, or EIDAS) login screen. The user authenticates directly with the identity provider — your application is not involved in this step.
After a successful authentication, the identity provider sends the SAML assertion to ESP, which validates it and redirects the user back to the final URL configured during the assessment phase.
After authentication, ESP redirects the user to your final URL.
Call the Get user token endpoint, passing the sessionid and sessionkey parameters, to retrieve a JWT containing the user's attributes.
Logout is not required for Level 2 authentications.
To terminate the SPID session, call the Logout endpoint and open the resulting URL in the user's browser. The user is presented with the identity provider logout screen and then redirected to the final URL configured for logout.