> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syrto.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Chiavi API
> Collegati al server MCP di Syrto con una chiave API di organizzazione invece di effettuare l'accesso.
La maggior parte dei client MCP si collega a Syrto facendoti accedere con OAuth: aggiungi l'URL del server e segui la richiesta di login, come descritto in [Configurazione](/it/mcp/setup). Serve quindi una persona davanti allo schermo.
Per script, job pianificati, pipeline di CI e integrazioni server-to-server, il server MCP di Syrto accetta anche una **chiave API di organizzazione** inviata come bearer token. Non c'è alcun flusso di accesso: la chiave viene verificata a ogni richiesta.
## Accesso o chiave API
| | Accesso (OAuth) | Chiave API di organizzazione |
| - | - | - |
| **Identifica** | Te e la tua organizzazione | Solo la tua organizzazione, nessuna persona |
| **Adatto a** | Assistenti AI usati da persone | Script, automazioni, integrazioni server-to-server |
| **Strumenti disponibili** | Tutti | Tutti tranne i [cinque che richiedono una persona](#cosa-non-può-fare-una-chiave-api) |
| **Limiti di frequenza** | Conteggiati per persona | Condivisi da tutte le chiavi dell'organizzazione |
| **Consumi addebitati a** | La tua organizzazione | La tua organizzazione |
## Crea una chiave
Le chiavi API vengono create da un **amministratore** dell'organizzazione nella [dashboard Syrto](https://dashboard.syrto.ai/api-keys), in **Impostazioni → Chiavi API**. Sono le stesse chiavi di organizzazione usate dalla [API Syrto](/it/api/authentication), quindi una chiave che hai già per la API funziona anche qui.
Le chiavi iniziano con `sk_`. Trattale come una password: danno accesso ai dati della tua organizzazione e ne consumano il plafond. Conservale in un archivio di segreti o in una variabile d'ambiente, mai in un URL, in un prompt o in un file che finisce nel repository.
Sono accettate solo le chiavi **di organizzazione**. Le chiavi personali che puoi creare in **Profilo → Chiavi API** vengono rifiutate con `401 Unauthorized`, perché una chiave API è pensata per identificare un'organizzazione e non una persona. Per usare Syrto a tuo nome, accedi con OAuth.
## Invia la chiave
Punta il client al server MCP di Syrto e invia la chiave nell'header `Authorization`:
```
URL: https://mcp.syrto.ai/mcp
Header: Authorization: Bearer sk_...
```
Gli esempi qui sotto leggono la chiave dalla variabile d'ambiente `SYRTO_API_KEY`:
```bash theme={null}
export SYRTO_API_KEY=sk_...
```
Aggiungi il server con un header `Authorization` fisso:
```bash theme={null}
claude mcp add --transport http syrto https://mcp.syrto.ai/mcp \
--header "Authorization: Bearer $SYRTO_API_KEY"
```
La shell espande `$SYRTO_API_KEY` quando esegui il comando, quindi Claude Code salva la chiave stessa nella sua configurazione.
Aggiungi il server a `.vscode/mcp.json`. La voce `inputs` fa sì che VS Code chieda la chiave una sola volta e la conservi in modo sicuro, così non compare mai nel file:
```json theme={null}
{
"inputs": [
{
"type": "promptString",
"id": "syrto-api-key",
"description": "Chiave API Syrto",
"password": true
}
],
"servers": {
"syrto": {
"type": "http",
"url": "https://mcp.syrto.ai/mcp",
"headers": {
"Authorization": "Bearer ${input:syrto-api-key}"
}
}
}
}
```
Qualsiasi client o SDK MCP in grado di inviare header HTTP personalizzati funziona allo stesso modo. Per verificare una chiave da riga di comando, invia una richiesta `initialize`:
```bash theme={null}
curl -s https://mcp.syrto.ai/mcp \
-H "Authorization: Bearer $SYRTO_API_KEY" \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
```
Una chiave valida restituisce il nome e le capacità del server. Un `401 Unauthorized` significa che la chiave non è stata accettata: vedi [Errori](#errori).
## Cosa non può fare una chiave API
Una chiave di organizzazione non identifica alcuna persona, quindi gli strumenti per documenti ufficiali, contatti persona e consumi personali non vengono proposti su una connessione con chiave:
| Strumento | Perché richiede una persona |
| - | - |
| [`syrto_list_official_documents`](/it/mcp/tools/official-documents#syrto_list_official_documents) | Riporta il saldo crediti dell'organizzazione, disponibile solo a un utente connesso |
| [`syrto_request_official_document`](/it/mcp/tools/official-documents#syrto_request_official_document) | Spende i crediti dell'organizzazione per conto di qualcuno |
| [`syrto_get_person_contacts`](/it/mcp/tools/person-contacts#syrto_get_person_contacts) | Registra chi ha cercato la persona e riporta il saldo crediti |
| [`syrto_request_person_contacts`](/it/mcp/tools/person-contacts#syrto_request_person_contacts) | Spende i crediti dell'organizzazione per conto di qualcuno |
| [`syrto_get_usage`](/it/mcp/tools/usage) | Riporta i consumi di una singola persona |
Non compaiono nell'elenco degli strumenti, e chiamarne uno comunque restituisce un errore che indica che lo strumento richiede un utente connesso. Tutti gli altri strumenti funzionano con una chiave, compresi la ricerca di aziende e persone, i profili aziendali, la struttura, le metriche e le analisi.
## Limiti di frequenza e consumi
Quando usi una chiave API, i [limiti di frequenza](/it/mcp/setup#limiti-di-frequenza) si applicano all'**organizzazione nel suo insieme**: tutte le chiavi dell'organizzazione attingono a un unico insieme di limiti condiviso, quindi creare altre chiavi non li aumenta. Tienine conto prima di collegare una pipeline ad alto volume a una chiave.
I consumi fatti con una chiave vengono addebitati al plafond Syrto AI dell'organizzazione, come quelli dei membri che accedono con il proprio account.
## Revoca una chiave
Un amministratore elimina le chiavi dalla stessa pagina **Impostazioni → Chiavi API** della dashboard. Una chiave eliminata o scaduta smette di funzionare entro circa un minuto.
## Errori
Una chiave non accettata riceve sempre `401 Unauthorized`. Le cause più comuni:
* Manca l'header `Authorization`, oppure non è nella forma `Bearer sk_...`.
* La chiave è scritta male, eliminata o scaduta.
* La chiave è una chiave personale di **Profilo → Chiavi API** invece di una chiave di organizzazione.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.