> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Chiavi API

> Genera e gestisci chiavi API con prefisso swb_ per l'accesso programmatico alla REST API pubblica di Switchbord.

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.

<Warning>
  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.
</Warning>

## 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:

| Ambito       | Concede                                                                                                    |
| ------------ | ---------------------------------------------------------------------------------------------------------- |
| `data_read`  | Lettura di contatti, conversazioni e modelli.                                                              |
| `data_write` | Creazione e aggiornamento di record — invio messaggi, pianificazione campagne, scrittura di dati contatto. |
| `management` | Accesso completo alle chiavi API e alle impostazioni, oltre alle operazioni sui dati.                      |
| `webhook`    | Invio di eventi attivati da webhook.                                                                       |

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:

```http theme={null}
Authorization: Bearer swb_...
```

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

* [API Reference — Introduzione](/it/api-reference/introduction) — la superficie della REST API pubblica, l'URL di base e gli endpoint principali v1.
* [Endpoint API dei modelli](/it/api-reference/template-endpoints) — un esempio di rotta autenticata con controllo dell'ambito.
* [Sicurezza — Segreti e crittografia](/it/security/secrets-and-encryption) — come le chiavi e altri segreti vengono sottoposti a hash e memorizzati at rest.