Passa al contenuto principale

API Keys

Webround ti permette di creare API Key con permessi granulari per autenticare sistemi esterni — applicazioni, script, integrazioni — senza esporre le credenziali del tuo account.

Come funzionano​

Un'API Key si usa in sostituzione del Bearer Token JWT standard. Qualsiasi richiesta alle API di Webround che normalmente richiederebbe un token di autenticazione, può essere autenticata passando la tua API Key nello stesso header:

Authorization: Bearer API_KEY

Chiunque sia in possesso di una API Key ha esattamente i permessi di quella key — né di più, né di meno. Questo significa che la key è tanto potente quanto i permessi che le hai assegnato, e altrettanto pericolosa se finisce nelle mani sbagliate.

Conservazione e sicurezza​

Non rileggibile

Webround mostra la tua API Key una sola volta, al momento della creazione. Non viene mai mostrata di nuovo. Se la perdi, devi invalidarla e crearne una nuova.

Alcune regole fondamentali:

  • Non esporla mai nel frontend. Il codice JavaScript che gira nel browser è leggibile da chiunque — inspector, estensioni, script iniettati. Una API Key nel frontend è una API Key compromessa.
  • Usa sempre un secret manager. I segreti dei tuoi servizi, un vault dedicato (HashiCorp Vault, Google Cloud Secret Manager, AWS Secrets Manager, Cloudflare Secrets) sono il posto giusto. Mai in un file .env committato, mai in una variabile hardcoded nel codice.
  • Non usarla per chiamate client-side. Se hai bisogno di chiamare le API di Webround dal browser, costruisci un endpoint intermedio sul tuo server che fa la chiamata — il server conosce la key, il browser no.

Principio del minimo privilegio​

Ogni API Key dovrebbe avere solo ed esclusivamente i permessi necessari per il suo scopo.

  • Una integrazione, una key. Non riutilizzare la stessa key per sistemi diversi. Se uno di essi viene compromesso, puoi invalidare solo quella key senza impattare le altre.
  • Limita i permessi al minimo. Un'app che legge ordini non ha bisogno di poter creare prodotti o modificare clienti. Concedi solo ciò che è strettamente necessario.
  • Invalida e rigenera immediatamente se hai il minimo dubbio che una key sia stata esposta — in un log, in una risposta HTTP, in un repository Git, ovunque.

Quando usare una API Key​

Le API Key sono pensate per comunicazioni server-to-server:

  • Un'applicazione esterna che legge ordini per gestire spedizioni
  • Uno script di sincronizzazione con un ERP o un magazzino
  • Un sistema di reporting che esporta dati verso un data warehouse
  • Un'App Extension che comunica con Webround per conto del merchant

Non sono pensate per il frontend, per applicazioni mobile che non controllate, o per qualsiasi contesto in cui il codice — e quindi la key — potrebbe essere ispezionato da un utente esterno.

Prossimi Passi: Consulta la guida alle Apps per vedere un esempio concreto di come combinare API Key e autenticazione firmata per integrare un sistema esterno nel tuo admin panel Webround.