# Chiavi API

Le chiavi API sono credenziali programmatiche per chiamare l'API di Voice Logica — ogni chiave è limitata alle operazioni che consenti e può essere ristretta a un singolo indirizzo IP. La stessa chiave collega anche i client MCP (ChatGPT, Claude) al tuo workspace. Le chiavi vivono in **Team and access → API Keys**.

> **Note:** Le chiavi dei provider di IA (OpenAI, ElevenLabs, …) sono un'altra cosa — stanno nella pagina **AI Provider Keys**, non qui.
## Creare una chiave API

1. **Apri la scheda API Keys**

   Vai su **Team and access** nel gruppo Account della barra laterale, seleziona la scheda **API Keys** e fai clic sul pulsante **"Api Key"**.

     ![Scheda API Keys](https://docs.voicelogica.ai/assets/getting-started/api-keys-0.png)

2. **Assegna un nome e limita l'IP**

   Dai un **nome** descrittivo che ne rifletta lo scopo — "CRM Integration", "Webhook Handler", "Initiate Call". Facoltativamente inserisci un **indirizzo IP** per limitare le chiamate a un solo indirizzo; lascia vuoto per consentire qualsiasi IP.

     ![Modulo di creazione chiave API](https://docs.voicelogica.ai/assets/getting-started/api-keys-1.png)

3. **Scegli le operazioni consentite**

   In **API operation restrictions**, attiva le operazioni che la chiave può chiamare. Sono raggruppate per area — **Calls**, **Agents**, **VoIP & SIP**, **SMS**, **Workflows**, **MCP**, **Billing** e **Shopify**. Lascia tutto attivo per l'accesso completo, oppure disattiva ciò che la chiave non deve fare.

     ![Restrizioni delle operazioni API](https://docs.voicelogica.ai/assets/getting-started/api-keys-2.png)

4. **Crea e copia la chiave**

   Fai clic su **"Create API Key"**. Il valore completo della chiave viene mostrato **solo questa volta** — copialo subito e conservalo al sicuro.

     ![Creazione della chiave API](https://docs.voicelogica.ai/assets/getting-started/api-keys-3.png)

> **La chiave si vede una sola volta:** Dopo la creazione la chiave è salvata mascherata — non vedrai mai più il valore completo. Se la perdi, elimina la chiave e creane una nuova.
> **Privilegio minimo:** Concedi solo le operazioni davvero necessarie, crea una chiave separata per ogni integrazione e limita l'IP quando il chiamante ha un indirizzo fisso. Se una chiave viene esposta, eliminala subito.
## Gestire le chiavi

La tabella API Keys elenca ogni chiave con **nome**, **chiave mascherata**, **ultimo utilizzo** e data di **creazione**.

  ![Tabella delle chiavi API](https://docs.voicelogica.ai/assets/getting-started/api-keys-4.png)

- **Modifica** — aggiorna nome, restrizione IP e operazioni consentite. Il valore della chiave non viene più mostrato e non può essere cambiato.
- **Elimina** — rimuove definitivamente la chiave. Non è annullabile, e qualsiasi applicazione che la usa perde subito l'accesso.

## Usare la chiave API

Autentica le richieste inviando la chiave nell'header `x-api-key`:

```
x-api-key: YOUR_API_KEY
```

Ad esempio, avviare una chiamata IA in uscita:

```bash
curl -X POST https://api.voicelogica.ai/api/v1/phones/calls/initiate-call \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationNumber": "+302101234567",
    "agentId": "your-agent-id",
    "voipPhoneId": "your-voip-phone-id"
  }'
```

`destinationNumber` è obbligatorio; passa `agentId` per le chiamate IA in uscita, e `voipPhoneId` oppure `sipTrunkId` per scegliere la linea di uscita. Il riferimento interattivo completo di ogni endpoint è su [api.voicelogica.ai/api-docs](https://api.voicelogica.ai/api-docs).

> **Note:** Le chiamate in uscita rispettano di default le regole del paese di destinazione — ad es. nessuna chiamata tra le 21:00 e le 09:00 ora locale. L'API espone flag espliciti di override se il tuo caso li richiede; le chiamate in entrata non sono mai limitate.
## Risoluzione dei problemi

**Le mie richieste restituiscono 401 Unauthorized**

- Verifica che la chiave sia inviata nell'header `x-api-key` — non come token `Bearer`.
- Controlla che la chiave non sia stata eliminata dalla tabella.
- Se la chiave ha una restrizione IP, la richiesta deve provenire esattamente da quell'indirizzo.

**Le mie richieste restituiscono 403 Forbidden**

- Le restrizioni della chiave non includono l'endpoint chiamato — modifica la chiave e attiva il gruppo di operazioni pertinente.

## Prossimi passi

> **Costruisci sull'API:** Esplora il [riferimento interattivo dell'API](https://api.voicelogica.ai/api-docs), automatizza con i [trigger dei flussi](https://docs.voicelogica.ai/it/workflows/) — oppure collega un client MCP come ChatGPT o Claude al tuo workspace con la stessa chiave.
## Serve aiuto?

In caso di problemi, il team di supporto di Voice Logica è a disposizione:

- EMAIL [support@voicelogica.ai](mailto:support@voicelogica.ai)
- SVILUPPATORI [developers@voicelogica.ai](mailto:developers@voicelogica.ai)
- RIFERIMENTO API [api.voicelogica.ai/api-docs](https://api.voicelogica.ai/api-docs)