Skip to main content
Le chiavi API sono il modo in cui sistemi esterni e script si autenticano contro la REST API pubblica di Switchbord senza una sessione di login interattiva. Le chiavi sono ambito-area di lavoro — una chiave può vedere e operare solo sull’area di lavoro in cui è stata creata — e vengono mostrate per intero esattamente una volta, al momento della creazione.

​
Dove gestire le chiavi

Vai su Impostazioni → Integrazioni → Chiavi API. Creare, revocare ed eliminare chiavi richiede il ruolo owner o admin per l’area di lavoro; qualsiasi membro dell’area di lavoro può visualizzare l’elenco delle chiavi esistenti (solo per nome e prefisso — non il segreto completo).

​
Creare una chiave

  1. Fai clic su Crea chiave.
  2. Assegnale un nome descrittivo (es. “Integrazione di produzione”, “Sincronizzazione Zapier”).
  3. Scegli un ambito (vedi sotto).
  4. Facoltativamente imposta una scadenza — Mai, 30 giorni, 90 giorni o 1 anno.
  5. Fai clic su Crea chiave. La chiave completa viene mostrata una sola volta in una finestra di dialogo — copiala immediatamente. Switchbord memorizza solo un hash SHA-256 e un prefisso di 8 caratteri per la visualizzazione; il segreto originale non può essere recuperato in seguito.
Se perdi una chiave, non c’è modo di recuperarla nuovamente — revocala e creane una nuova. Non incollare mai una chiave attiva in codice lato client, un file sottoposto a commit o un messaggio di chat.

​
Formato della chiave

Le chiavi generate hanno il prefisso swb_ (alcuni strumenti di provisioning legacy e script interni generano ancora chiavi con prefisso sk_live_ per scopi di bootstrap — entrambi i formati vengono validati nello stesso modo). Il prefisso rende le chiavi facili da individuare in log e diff, e consente alla scansione automatica dei segreti di rilevare rapidamente una chiave inavvertitamente sottoposta a commit.

​
Ambiti

Ogni chiave viene creata con esattamente un ambito, che delimita ciò che può fare indipendentemente dall’endpoint chiamato: Scegli l’ambito più ristretto che svolge il compito — uno script che deve solo leggere i contatti non dovrebbe avere una chiave management.

​
Autenticazione delle richieste

Passa la chiave come token Bearer:
Switchbord risolve l’area di lavoro chiamante direttamente dalla chiave — non inviare mai un ID area di lavoro nel corpo della richiesta aspettandoti che venga considerato attendibile. A ogni richiesta, l’hash della chiave viene consultato, verificato rispetto al suo ambito e alla sua scadenza, e last_used_at viene aggiornato.

​
Revoca ed eliminazione

  • Revoca invalida immediatamente una chiave per l’autenticazione mantenendo visibile il suo record (e la cronologia d’uso) nell’elenco, contrassegnato come revocato.
  • Elimina rimuove completamente il record della chiave.
Ogni azione di creazione, revoca ed eliminazione viene scritta nel registro di audit dell’area di lavoro, così puoi sempre rispondere a “chi ha emesso questa chiave e quando”.

​
Scadenza

Le chiavi possono essere impostate per non scadere mai, oppure per scadere automaticamente dopo 30 giorni, 90 giorni o 1 anno. Una chiave scaduta fallisce l’autenticazione nello stesso modo di una revocata — le richieste restituiscono un 403 piuttosto che avere successo silenziosamente.

​
Vedi anche