> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Guida rapida JavaScript per l'autenticazione Didit

> Collega un'applicazione Authentication abilitata al login ospitato di Didit con PKCE, validazione del callback, verifica delle sessioni e logout.

> [!WARNING]
>
> L'autenticazione è una novità: usa questo esempio di flusso ospitato con un'applicazione che ha l'Autenticazione attiva. Il pacchetto `@didit-protocol/auth` non è ancora pubblicato; l'API del pacchetto qui sotto è un'anteprima, non una guida rapida installabile.

## Configura l'accesso ospitato

Registra l'URL di callback esatto e l'origine web per la tua applicazione sandbox. Copia la sua origine di accesso (`https://<slug>.sandbox.auth.didit.me`) dalla console, come descritto nella [panoramica](https://docs.didit.me/it/authentication/overview.md). Questo esempio usa le API crittografiche del browser e richiede HTTPS, oppure localhost in sandbox: consulta [sviluppo locale](https://docs.didit.me/it/authentication/overview.md#sviluppo-locale) per sapere cosa registrare.

L'applicazione gestisce `state` e il verifier PKCE. L'accesso ospitato gestisce le schermate di password, email, passkey, telefono, SSO e MFA quando richiesta. In questo codice non va inserita nessuna chiave API.

```javascript auth.js theme={null}
// Replace both values with your registered application configuration.
const AUTH_BASE = "https://YOUR_SLUG.sandbox.auth.didit.me/";
const REDIRECT_URI = "https://YOUR_APP_ORIGIN/auth/callback";
const PENDING = "didit.auth.pending";
let tokens = null;

function base64url(bytes) {
  return btoa(String.fromCharCode(...bytes))
    .replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
}

export async function signIn() {
  const verifier = base64url(crypto.getRandomValues(new Uint8Array(32)));
  const state = base64url(crypto.getRandomValues(new Uint8Array(32)));
  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
  sessionStorage.setItem(PENDING, JSON.stringify({ verifier, state, startedAt: Date.now() }));
  const url = new URL("sign-in", AUTH_BASE);
  url.search = new URLSearchParams({
    redirect_uri: REDIRECT_URI,
    state,
    code_challenge: base64url(new Uint8Array(digest)),
    code_challenge_method: "S256",
  }).toString();
  window.location.assign(url.href);
}

export async function handleCallback() {
  const query = new URLSearchParams(window.location.search);
  const saved = sessionStorage.getItem(PENDING);
  sessionStorage.removeItem(PENDING);
  history.replaceState(null, "", window.location.pathname);
  if (!saved) throw new Error("Start sign-in again.");
  const pending = JSON.parse(saved);
  if (query.get("state") !== pending.state || Date.now() - pending.startedAt > 600000) {
    throw new Error("Invalid or expired sign-in. Start again.");
  }
  if (query.has("error") || !query.get("code")) throw new Error("Sign-in was not completed.");
  const response = await fetch(new URL("token/", AUTH_BASE), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      grant_type: "authorization_code",
      code: query.get("code"),
      code_verifier: pending.verifier,
      redirect_uri: REDIRECT_URI,
    }),
  });
  if (!response.ok) throw new Error("Code exchange failed. Start sign-in again.");
  tokens = await response.json();
  return getSession();
}

export async function getSession() {
  if (!tokens) return null;
  const response = await fetch(new URL("session/", AUTH_BASE), {
    headers: { Authorization: `Bearer ${tokens.access_token}` },
    cache: "no-store",
  });
  if (!response.ok) {
    tokens = null;
    throw new Error("Session check failed. Sign in again.");
  }
  return response.json();
}

export async function signOut() {
  const current = tokens;
  tokens = null;
  if (!current) return;
  const response = await fetch(new URL("session/", AUTH_BASE), {
    method: "DELETE",
    headers: { Authorization: `Bearer ${current.access_token}` },
  });
  if (response.status !== 204) throw new Error("Local state cleared; server logout failed.");
}
```

Chiama `signIn()` dal tuo pulsante di accesso. Nella pagina di callback registrata, chiama `handleCallback()` una sola volta, mostra uno stato di caricamento e visualizza il suo errore se l'operazione fallisce. Usa `getSession()` per l'utente corrente e `signOut()` per il logout. Il callback rimuove il proprio codice dalla barra degli indirizzi prima di inviare una richiesta.

Questo esempio minimale conserva i token in memoria e richiede un nuovo accesso dopo il ricaricamento della pagina o la scadenza del token di accesso. Per sessioni persistenti, usa il tuo backend e cookie sicuri, oppure implementa una [rotazione dei refresh token](https://docs.didit.me/it/authentication/tokens-and-jwks.md) serializzata. Non inserire mai i refresh token negli URL o nei log. Il controllo della sessione lato frontend serve solo alla presentazione; il tuo backend deve verificare il chiamante a ogni richiesta protetta.

## Anteprima del rilascio dell'SDK di autenticazione

Il futuro nucleo `@didit-protocol/auth` espone `createDiditAuth({publishableKey})`, `signIn()`, `handleRedirectCallback()`, `getSession()`, `getToken()`, `onAuthStateChange` e `signOut()`, con `vendorData` sull'identità. È previsto che aggiunga segnali automatici del dispositivo e un punto di ingresso server con `verifyToken()`.

La chiave pubblicabile è `pk_live_` (applicazione di produzione) o `pk_test_` (applicazione sandbox), seguita dalla codifica base64url, senza padding, dell'origine della tua applicazione.
L'SDK invia le proprie chiamate API a quell'origine.
La chiave è pubblica: identifica l'applicazione e non è un segreto.

### Step-up e riautenticazione nell'anteprima

* `stepUp({ action, amount?, currency?, redirectUri? })` chiama `POST step-up/` della tua applicazione per chiedere se `action` richiede una verifica dell'identità.
  `action` può essere `payout`, `bank` o `contact`, e un payout richiede `amount`.
  Quando si applica una delle tue regole di step-up, reindirizza alla pagina di verifica restituita da Didit.
* `handleStepUpCallback(url?)` viene eseguito sulla pagina alla quale la persona torna.
  Legge `?step_up=<id>`, lo rimuove dalla barra degli indirizzi e legge l'esito con `GET step-up/{id}/`.
* `reauthenticate({ method? })` autentica di nuovo la stessa persona, nella pagina ospitata (`method: "redirect"`, predefinito) oppure con una passkey (`method: "passkey"`, solo nel dominio di accesso Didit della tua applicazione).
  Dopo aver completato la pagina ospitata, completa la riautenticazione con `handleRedirectCallback()`.
  Se la completa un'altra persona, la chiamata viene rifiutata con `step_up_user_mismatch` e la sessione originale resta attiva.

Entrambi i metodi di step-up restituiscono `{ id, status, approved, rule, method }`, dove `status` può essere `not_required`, `pending`, `approved`, `review`, `declined` o `expired`.
`redirectUri` ha come valore predefinito l'indirizzo di redirect del client e deve corrispondere esattamente a uno degli indirizzi di redirect registrati per la tua applicazione: quando è richiesto un controllo, Didit rifiuta qualsiasi altro indirizzo.
Prima che il tuo backend agisca su uno step-up, rileggilo con `GET step-up/{id}/` e il token di accesso della persona, perché un risultato riportato dal browser può essere alterato.

Un accesso headless può anche restituire `protection_required` quando le regole di protezione della tua applicazione lo segnalano.
La persona lo completa poi con il codice che Didit le ha inviato via email (`protection.verify({ code })`) oppure con una passkey (`protection.passkey()`), e `methods` elenca quali dei due può usare.

Non installare una versione ipotizzata e non scrivere codice basato su opzioni di callback ipotizzate. Verifica gli export del pacchetto pubblicato, l'emittente e la configurazione delle chiavi prima di sostituire l'esempio ospitato. I metodi basati su password, codice via email, link magico, passkey, telefono, MFA, accesso social, step-up e agenti dipenderanno dall'API supportata da quel rilascio.

## Aggiungi altri prodotti

Il tuo backend verifica il token di accesso (vedi [token e JWKS](https://docs.didit.me/it/authentication/tokens-and-jwks.md)) e legge il suo `vendor_data`. Usa quel valore come `vendor_data` quando [crei una sessione di verifica](https://docs.didit.me/it/sessions-api/create-session.md) o [generi un token di transazione](https://docs.didit.me/it/transaction-monitoring/sdk-transaction-submission.md). Un accesso riuscito non implica l'approvazione dell'utente da parte di nessuno dei due prodotti.

Prima di andare in produzione, testa registrazione, accesso di chi è già registrato, annullamento, state non corrispondente, codice riutilizzato, recupero password, MFA, scadenza e logout sulla tua applicazione sandbox attivata.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.