# Authentication flow

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.

## Overview


```mermaid
sequenceDiagram
    participant U as User
    participant App as Your Application
    participant ESP as ESP
    participant IdP as Identity Provider<br/>(SPID / CIE / EIDAS)

    App->>ESP: GET getKey
    ESP-->>App: authnKey
    App->>ESP: GET login (authnKey)
    ESP-->>U: Redirect to IdP
    U->>IdP: Authenticate
    IdP-->>ESP: Assertion
    ESP-->>App: Redirect to final URL (id + key)
    App->>ESP: GET getUser (id + key)
    ESP-->>App: JWT with user attributes
```

## Authentication

All server-side API calls to ESP require an API key provided by Namirial during the [Setup Test Environment](/products/esp/enterprise-documentation/get-started/get-started#setup-test-environment) phase.

Include it in every request as a header:


```
Esp-Api-Key: YOUR_API_KEY
```

Login and Logout are browser-based redirects — no API key is required for those calls.

## Step 1 — Get a session key

Before redirecting the user to the identity provider, your application must obtain a session key (`authnKey`) from ESP.

Call the [Get Key](/products/esp/enterprise-documentation/developer-documentation/integration-guide/getkey) endpoint, specifying the authentication level and the attribute set required:

- **`level`**: `1`, `2`, or `3`
- **`attributes`**: `Base` or `Full`


The response is a string (`authnKey`) that identifies the authentication session. It must be passed to the login endpoint in the next step.

## Step 2 — Redirect the user to the identity provider

Use the `authnKey` obtained in Step 1 to build the [login](/products/esp/enterprise-documentation/developer-documentation/integration-guide/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.

## Step 3 — Retrieve the user JWT

After authentication, ESP redirects the user to your `final` URL.

Call the [Get user token](/products/esp/enterprise-documentation/developer-documentation/integration-guide/token) endpoint, passing the `sessionid` and `sessionkey` parameters, to retrieve a JWT containing the user's attributes.

## Step 4 — Logout

Note
Logout is not required for Level 2 authentications.

To terminate the SPID session, call the [Logout](/products/esp/enterprise-documentation/developer-documentation/integration-guide/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.