Autenticazione

Ogni richiesta porta una chiave API nell'header Authorization:

Authorization: Bearer lp_live_XXXXXXXX…    (chiave di area di lavoro)
Authorization: Bearer lpp_live_XXXXXXXX…   (chiave partner)

Le chiavi si creano nella dashboard, vengono mostrate una sola volta al momento della creazione e sono conservate come hash SHA-256: nessuno, nemmeno l'assistenza, può recuperare una chiave persa. Perdere una chiave significa revocarla e crearne una nuova.

Tipi di chiave

• Le chiavi di area di lavoro (lp_live_…) agiscono dentro una sola area di lavoro: link, analytics, domini, log di audit e webhook dell'area di lavoro. Vengono create dagli amministratori dell'area di lavoro in Impostazioni → Chiavi API.
• Le chiavi partner (lpp_live_…) agiscono sull'account partner: clienti, piani, domini, pagamenti, payout e webhook del partner. Vengono create dagli amministratori del partner.

Una chiave di area di lavoro che chiama /partner/* (o viceversa) riceve 403 forbidden: le famiglie di endpoint sono rigorosamente separate.

Ambiti

Gli ambiti vengono assegnati a ogni chiave al momento della creazione. Una richiesta ha bisogno di tutti gli ambiti richiesti dal suo endpoint; un ambito mancante produce 403 insufficient_scope, con il nome dell'ambito che manca.

| Ambito | Consente | |---|---| | links:read / links:write | Leggere / creare, aggiornare, archiviare ed eliminare link | | analytics:read | Riepilogo, serie temporali, ripartizioni, link principali, esportazione CSV — e la panoramica dei clic dell'intero partner | | domains:read / domains:write | Leggere / collegare e scollegare domini | | qr:read | Generare i codici QR dei link | | workspace:read | Profilo dell'area di lavoro, limiti, log di audit | | webhooks:read / webhooks:write | Leggere / gestire gli endpoint webhook | | partner:read | Profilo del partner, piano e utilizzo | | clients:read / clients:write | Leggere / creare, modificare, sospendere clienti | | plans:read / plans:write | Leggere / gestire i piani del partner | | payments:read | Mirror dei pagamenti e payout |

Questo è l'elenco completo — quindici ambiti — e una chiave può contenere solo nomi presi da qui. I codici QR sono di sola lettura via API: generarne uno richiede qr:read, e non esiste un ambito di scrittura per i QR perché non esiste alcun endpoint che li modifichi.

C'è un abbinamento che trae spesso in inganno: GET /partner/analytics/overview richiede analytics:read sulla chiave partner, non partner:read. Tutti gli endpoint di analytics usano lo stesso ambito, qualunque sia il tipo di chiave.

Assegna a ogni integrazione la sua chiave, con gli ambiti minimi che le servono: a una chiave per un widget della dashboard bastano links:read + analytics:read, mentre uno script di provisioning ha bisogno di clients:write.

Restrizioni di piano

L'accesso all'API è una funzionalità del piano (api_access):

• per le chiavi di area di lavoro devono includere l'accesso all'API sia il piano dell'area di lavoro sia il piano di piattaforma del partner;
• per le chiavi partner deve includerlo il piano di piattaforma del partner.

Un piano senza accesso all'API risponde 403 plan_restricted. Le aree di lavoro in prova, senza piano, non sono soggette a restrizioni.

Rotazione e revoca

La revoca di una chiave ha effetto immediato: la richiesta successiva riceve 401 unauthorized. Per ruotare una chiave senza interruzioni di servizio, crea prima quella nuova, poi passa l'integrazione alla nuova chiave e infine revoca quella vecchia. Ogni chiave registra last_used_at, quindi è facile individuare una vecchia chiave inutilizzata prima di revocarla.

Facoltativamente una chiave può avere una data di scadenza: le chiavi scadute si comportano esattamente come quelle revocate.

Buone pratiche

• Le chiavi sono segreti: conservale in un gestore di segreti, mai nel codice lato client, nei repository o nei log.
• Una chiave per integrazione: revocarne una non blocca le altre e il log di audit attribuisce ogni modifica alla chiave che l'ha effettuata.