Sviluppa con Praxium.

Le chiavi API sono firmate con HMAC alla creazione: la chiave contiene la propria prova di integrità nel formato praxium_v1_<tenant>_<profile>_<timestamp>_<signature>, dove la firma è derivata lato server con HMAC-SHA256 da un segreto di firma per profilo, conservato cifrato nel database — il segreto non viaggia mai in rete, viaggia solo la firma che produce. Il nome breve dell’organizzazione è legato crittograficamente alla firma, quindi una chiave emessa per l’organizzazione A non può essere riusata sull’organizzazione B senza invalidare la verifica. All’arrivo il server verifica l’integrità della chiave prima di restituire qualsiasi dato, e le chiavi falsificate o riusate ricevono un 403.

Le richieste si autenticano con il consueto Authorization: Bearer <key> su HTTPS — lo stesso schema usato da GitHub, OpenAI, Slack e Notion.

Inoltre ogni chiave appartiene a un solo profilo API, che definisce esattamente quali tipi di dati e campi può leggere. Ogni integrazione tocca solo i dati che le servono — il principio del privilegio minimo, applicato al singolo campo e non all’endpoint. La revoca e la rotazione avvengono per profilo dal portale di amministrazione.

Invia Accept-Language: nl, Accept-Language: en oppure Accept-Language: ro quando il tuo sito mostra una sola lingua. Le API usano la lingua richiesta solo se l’organizzazione l’ha attivata; altrimenti usano la sua lingua predefinita.

Ogni endpoint mantiene una sola forma di risposta documentata. I campi documentati come tradotti — nomi delle categorie FAQ, domande e risposte, etichette e valori dei campi personalizzati del team — tornano come stringhe. I campi documentati in OpenAPI come mappe di lingue mantengono quella forma.

Per i campi tradotti, una traduzione mancante ricade sul miglior testo pubblicato disponibile invece che su una stringa vuota.

Ogni consegna porta una sola intestazione X-Praxium-Signature: t=<unix_ts>,sha256=<hmac_hex>, dove l’HMAC-SHA256 è calcolato lato server su ${timestamp}.${rawBody} con il segreto del singolo webhook. Il segreto condiviso non viaggia mai in rete — viaggia solo il risultato dell’HMAC. La firma prova due cose insieme: che il corpo non è stato alterato durante il trasporto (integrità) e che la chiamata arriva davvero da Praxium e non da chi ha indovinato l’indirizzo del tuo endpoint (autenticità). Tutte le consegne viaggiano su HTTPS — Praxium rifiuta di registrare indirizzi webhook non HTTPS negli ambienti pubblicati.

Chi riceve un webhook deve verificare ogni consegna — Praxium firma e invia, ma il controllo avviene nel tuo gestore. Con @praxium/sdk non scrivi niente di tutto questo a mano: processWebhook() (indipendente dal framework) e createRevalidationHandler() (ISR di Next.js) svolgono i quattro passaggi più la protezione dai rinvii. Devi implementarlo in un altro ambiente? I quattro passaggi sono: (1) leggi il momento e la firma dall’intestazione, (2) rifiuta le consegne più vecchie della tua finestra di rinvio — 5 minuti è lo standard, (3) ricalcola l’HMAC su ${timestamp}.${rawBody} con il tuo segreto condiviso, (4) confronta con un confronto a tempo costante (per esempio crypto.timingSafeEqual su Node).

È lo stesso schema che Stripe usa per le firme dei webhook. I segreti dei singoli webhook si vedono una volta sola — nella risposta che crea il webhook e in ogni risposta di rotazione — e poi non riappaiono. Questa esposizione singola significa che sulla piattaforma non resta una superficie d’attacco durevole per il segreto: nemmeno una sessione di amministrazione compromessa potrebbe rileggerlo. Ne serve uno nuovo? Ruotalo dal portale di amministrazione — il nuovo segreto arriva nella risposta, il precedente perde subito validità e le altre iscrizioni restano intatte.