Vai al contenuto

Come generare e gestire le chiavi API in modo sicuro

🤖 Spiega con l'intelligenza artificiale

Le chiavi API sono le credenziali digitali che consentono al tuo software personalizzato o alle applicazioni di terze parti di comunicare in modo sicuro con l’ecosistema 4Geeks. Che tu stia automatizzando i pagamenti tramite 4Geeks Payments, sincronizzando i dati dei candidati da 4Geeks Talent o integrando le cartelle cliniche con 4Geeks Health, una chiave API sicura è il tuo punto di partenza.

Questa guida fornisce una procedura dettagliata su come generare, gestire e proteggere le tue chiavi API utilizzando la 4Geeks Console. Seguendo questi passaggi, ti assicuri che le tue integrazioni rimangano solide mantenendo al sicuro i dati della tua organizzazione.

Prerequisiti

Prima di iniziare a generare le chiavi, assicurati di soddisfare i seguenti requisiti:

  • Accesso all’account: Devi avere un account attivo sulla 4Geeks Console.
  • Autorizzazioni utente: Hai bisogno di diritti di accesso “Admin” o “Developer”. Gli utenti generici di solito non hanno l’autorizzazione per visualizzare o creare chiavi API.
  • Configurazione di sicurezza: Si consiglia vivamente di avere l’autenticazione a due fattori (2FA) abilitata sul tuo account prima di eseguire azioni ad alta sicurezza come la generazione di chiavi.

Istruzioni passo-passo

Segui questi passaggi per creare una nuova chiave API.

Passaggio 1: Accedi alle impostazioni sviluppatore

  1. Accedi alla tua 4Geeks Console.
  2. Nella barra laterale di navigazione principale, individua e clicca su Settings.
  3. Dal menu a discesa o dalle impostazioni, seleziona API & Developers.

Passaggio 2: Genera una nuova chiave

  1. Nella sezione API Keys, vedrai un elenco di chiavi esistenti (se presenti). Clicca sul pulsante + Generate New Key.
  2. Nomina la tua chiave: Inserisci un nome descrittivo nel campo “Label”.
    • Suggerimento: Usa una convenzione di denominazione che identifichi lo scopo della chiave e il servizio che la utilizza (ad es. Zapier-Integration-Payroll o Internal-App-Health).
  3. Imposta scadenza (Opzionale): Per una maggiore sicurezza, puoi impostare una data di scadenza. Se questa chiave è per un progetto temporaneo, seleziona una data; altrimenti, lasciala come “Never Expire”.

Passaggio 3: Definisci le autorizzazioni (Scopes)

Per aderire al principio del privilegio minimo, concedi solo le autorizzazioni necessarie per l’attività specifica.

  1. Rivedi l’elenco dei prodotti disponibili (ad es. 4Geeks Asset, 4Geeks Perks).
  2. Attiva le autorizzazioni specifiche Read o Write richieste.
    • Esempio: Se la chiave è per un visualizzatore di dashboard, concedi l’accesso Read-Only a 4Geeks Asset. Non concedere l’accesso Write a 4Geeks Payroll a meno che l’integrazione non richieda esplicitamente la modifica dei dati salariali.
  3. Clicca su Create Key.

Passaggio 4: Copia e memorizza la tua chiave

Passaggio cruciale: Una volta generata la chiave, una modale visualizzerà la chiave segreta API completa.

  1. Clicca sull’icona Copy per copiare la stringa negli appunti.
  2. Incolla immediatamente questa chiave nel tuo vault sicuro, gestore di password o file delle variabili d’ambiente (.env).
  3. Nota: Per motivi di sicurezza, 4Geeks non mostrerà mai più questa chiave completa. Se la perdi, dovrai generarne una nuova e aggiornare le tue integrazioni.

Casi d’uso comuni

Comprendere come applicare queste chiavi può aiutare a semplificare le operazioni nell’intera suite 4Geeks.

Scenario 1: Automatizzazione dei flussi di lavoro di onboarding

Situazione: Il tuo team HR utilizza un portale interno personalizzato e vuole attivare automaticamente le attività di onboarding quando viene approvata una nuova assunzione. Applicazione: Generi una chiave API con accesso “Write” a 4Geeks Talent. Quando un candidato viene contrassegnato come “Assunto” nel tuo sistema interno, la chiave API autentica una richiesta a 4Geeks Talent per avviare la sequenza di onboarding.

Scenario 2: Sincronizzazione dell’inventario per l’E-Commerce

Situazione: Utilizzi 4Geeks Asset per il monitoraggio dell’inventario ma utilizzi uno strumento di terze parti per le vendite front-end. Applicazione: Creando una chiave API “Read-Only” per la tua piattaforma di vendita, questa può interrogare 4Geeks Asset ogni 15 minuti per recuperare i livelli di scorte in tempo reale, assicurandoti di non vendere mai troppo un prodotto.

Risoluzione dei problemi

Se le tue integrazioni falliscono, controlla questi problemi comuni associati alle chiavi API.

Problema 1: Errore HTTP 401 Unauthorized

  • Causa: La chiave API è mancante, errata o è stata eliminata.
  • Soluzione: Controlla il codice dell’applicazione per assicurarti che la chiave venga passata correttamente nell’Intestazione (di solito Authorization: Bearer YOUR_API_KEY). Se il codice è corretto, verifica nella 4Geeks Console che lo stato della chiave sia “Active”.

Problema 2: Errore HTTP 403 Forbidden

  • Causa: La chiave funziona, ma non ha l’autorizzazione per accedere alla risorsa specifica.
  • Soluzione: Probabilmente hai limitato lo Scope durante il Passaggio 3. Ad esempio, se stai cercando di utilizzare gli endpoint 4Geeks AI Agents ma hai abilitato solo le autorizzazioni per 4Geeks Perks, la richiesta fallirà. Genera una nuova chiave con gli scope corretti.

Problema 3: Compromissione della chiave

  • Causa: Uno sviluppatore ha accidentalmente eseguito il commit della chiave API in un repository GitHub pubblico.
  • Soluzione: Tratta questo come un’emergenza di sicurezza. Accedi immediatamente alla console, trova la chiave compromessa e clicca su Revoke/Delete. Genera una nuova chiave e aggiorna le tue variabili d’ambiente.

Best Practice per la sicurezza

  • Ruota le chiavi: Cambia le tue chiavi API periodicamente (ad es. ogni 90 giorni) per ridurre il rischio di credenziali compromesse.
  • Usa variabili d’ambiente: Non codificare mai le chiavi API direttamente nel codice sorgente dell’applicazione.
  • Limita gli scope: Non generare mai una chiave “Super Admin” con accesso a tutto a meno che non sia assolutamente necessario. Se una chiave è necessaria solo per 4Geeks Payroll, non darle accesso ai dati 4Geeks Health.

Conclusione

La gestione sicura delle chiavi API è il fondamento di un’infrastruttura tecnica stabile e sicura. Configurando correttamente le autorizzazioni e gestendo le tue credenziali con cura, puoi sbloccare tutto il potenziale dell’automazione all’interno dell’ecosistema 4Geeks.

Pronto a costruire la tua prima integrazione? Visita la 4Geeks Console per iniziare.

Risorse aggiuntive