API

Chiavi API di ArchibotChat

Crea, copia, ruota e revoca chiavi API generate e collega uno strumento di collaboratore esterno all'endpoint pubblico di Archibot.

Amministratori clienteMembri del clienteOperatori della piattaforma

Ultimo aggiornamento 18 giugno 2026

Le chiavi API ti consentono di chiamare l’endpoint pubblico di Archibot da script, strumenti di agente locale e integrazioni che vengono eseguiti al di fuori di un workspace gestito. Sono separate dalla credenziale nascosta che alimenta la schermata di Chat del browser, che non viene mai mostrata agli utenti.

I workspace Archibot gestiti effettuano già automaticamente il provisioning delle proprie chiavi. Usa una chiave API generata solo per uno strumento di agente locale, un’estensione dell’editor o un harness di proprietà del cliente che debba chiamare Archibot come collaboratore esterno.

Quando usare le chiavi API

Crea una chiave generata quando devi:

• Chiamare Archibot da uno script o da un job pianificato.
• Connettere uno strumento di agente locale o un’estensione dell’editor all’endpoint.
• Eseguire un client compatibile con OpenAI contro l’endpoint di Archibot.
• Collegare ad Archibot un harness di proprietà del cliente al di fuori del workspace.

Per domande interattive, usa invece la schermata di Chat del browser. Vedi Usare ArchibotChat.

Aprire la scheda Chiavi API

1. Apri Impostazioni dalla navigazione a sinistra.
2. Seleziona la vista Archibot account.
3. Apri la scheda API Keys.

La scheda si trova sulla stessa riga di Setup, Git access, CI & Review, Support, Activity e Billing. Se l’accesso API non è abilitato per l’account, la scheda mostra il messaggio API access is not enabled for this account. e il pulsante Create key è disabilitato. Chiedi prima a un amministratore cliente o a ISM di abilitare il gate di prodotto API. Vedi Configurazione di ArchibotChat.

Creare una chiave

1. Nella scheda API Keys, scegli Create key.
2. La nuova chiave appare in cima all’elenco e il suo valore completo viene mostrato una sola volta in un avviso evidenziato che recita Copy this key now. It will not be shown again.
3. Scegli Copy accanto al valore della chiave.
4. Archiviala nel tuo gestore di segreti approvato o nell’ambiente di runtime.

Le chiavi vengono nominate automaticamente (per esempio, Console generated key 1) e ricevono lo scope api. Il valore grezzo viene mostrato solo in questo avviso. Una volta che lasci la scheda o crei un’altra chiave, restano visibili solo il prefisso della chiave e i metadati.

Se il pulsante di copia non riesce a raggiungere gli appunti, la scheda mostra Clipboard copy unavailable. Seleziona manualmente il testo della chiave e copialo prima di spostarti altrove.

Collegare uno strumento di collaboratore esterno

La scheda External coworker access crea uno script di configurazione pronto all’uso così non devi assemblare a mano le variabili d’ambiente.

La scheda mostra due campi di riferimento:

Sotto questi campi, un’anteprima mostra uno script di shell che esporta le variabili d’ambiente dell’endpoint e della chiave ed esegue un comando di collaboratore di esempio. Quando hai appena creato o ruotato una chiave, lo script include quel valore di chiave monouso; altrimenti usa un segnaposto <new-api-key>.

1. Crea o ruota una chiave in modo che il campo Key source mostri New one-time key included.
2. Scegli Copy setup sulla scheda External coworker access.
3. Incolla lo script nella tua shell locale, nel gestore di segreti o nella configurazione dello strumento.

Lo script imposta variabili standard compatibili con OpenAI (OPENAI_BASE_URL, OPENAI_API_KEY) insieme alle variabili del collaboratore Archibot, in modo che sia i client compatibili con OpenAI sia gli strumenti del collaboratore Archibot prelevino lo stesso endpoint e la stessa chiave. Usa l’URL dell’endpoint di produzione fornito da ISM per il tuo account anziché dedurlo da un esempio locale.

Usare una chiave

Usa la chiave come token bearer contro l’endpoint compatibile con OpenAI di Archibot.

curl https://chat.example.archibot.cloud/v1/responses \
  -H "Authorization: Bearer $ARCHIBOT_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "archibot",
    "input": "Summarize this Archibus request queue export."
  }'

L’endpoint inoltra all’endpoint Archibot i campi dell’API Responses compatibili con OpenAI come tools, tool_choice, reasoning, metadata e il contenuto input strutturato dopo che le verifiche di chiave API e crediti sono superate.

Per le risposte in streaming, invia stream: true:

curl -N https://chat.example.archibot.cloud/v1/responses \
  -H "Authorization: Bearer $ARCHIBOT_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "model": "archibot",
    "input": "Draft a short work plan for this Archibus data cleanup.",
    "stream": true
  }'

Le risposte in streaming restituiscono le evidenze di fatturazione negli header di risposta X-Archibot-* anziché riscrivere ogni frammento di evento.

La scoperta dei modelli compatibile con OpenAI usa la stessa chiave bearer:

curl https://chat.example.archibot.cloud/v1/models \
  -H "Authorization: Bearer $ARCHIBOT_API_KEY"

La scoperta dei modelli non attinge dalla tua quota di utilizzo.

Limiti di frequenza

Le chiavi API generate hanno un limite di richieste per chiave. Le risposte includono gli header X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Quando il limite viene superato, l’endpoint restituisce 429 con un header Retry-After.

Scadenza

Le chiavi API generate scadono un anno dopo la creazione. Ogni riga di chiave mostra le date di creazione, scadenza e ultimo utilizzo accanto al prefisso della chiave.

Le chiavi scadute restano visibili per nome, prefisso e metadati così puoi controllare le vecchie integrazioni, ma non possono più chiamare la scoperta dei modelli o l’endpoint delle risposte. I rifiuti di chiave scaduta avvengono prima che venga conteggiato qualsiasi utilizzo. Ruota una chiave scaduta per emettere una sostituta con lo stesso nome e scope, oppure revocala se l’integrazione viene dismessa.

Ruotare una chiave

Ruota una chiave quando un’integrazione deve continuare a funzionare con lo stesso nome e scope ma il valore segreto deve cambiare.

1. Nella scheda API Keys, trova la chiave attiva per nome o prefisso.
2. Scegli Rotate su quella riga di chiave.
3. Copia il valore sostitutivo dall’avviso monouso.
4. Aggiorna lo script, la voce del gestore di segreti o l’ambiente di runtime interessato.

La rotazione revoca la chiave precedente e crea una sostituta con lo stesso nome e scope. Il valore sostitutivo viene mostrato una sola volta, nello stesso avviso usato per le chiavi nuove. La rotazione agisce immediatamente; non c’è una finestra di conferma separata, quindi preparati ad aggiornare l’integrazione prima che il vecchio traffico fallisca.

Revocare una chiave

Revoca una chiave quando:

• Non è più utilizzata.
• È stata incollata in una chat, un’e-mail, un ticket, un repository o un documento condiviso.
• Il proprietario lascia il team.
• L’integrazione viene sostituita.

1. Nella scheda API Keys, trova la chiave per nome o prefisso.
2. Scegli Revoke su quella riga di chiave.
3. Aggiorna o rimuovi qualsiasi script o integrazione che ne dipendeva.

La revoca ha effetto immediato e non c’è una finestra di conferma separata, quindi conferma che la chiave sia quella giusta prima di scegliere Revoke.

Fatturazione

Le chiavi API generate attingono dalla stessa quota condivisa di utilizzo di chat e API mostrata in Billing. I controlli di prevolo falliti e le richieste upstream rifiutate non dovrebbero consumare crediti; una richiesta in streaming diventa fatturabile una volta che l’endpoint Archibot accetta lo stream. Vedi Fatturazione e crediti di ArchibotChat.

Regole di sicurezza

• Non eseguire mai il commit di chiavi API nel controllo di versione.
• Non incollare mai chiavi API in ticket di supporto o documenti condivisi.
• Usa variabili d’ambiente o un gestore di segreti, non valori inline.
• Usa una chiave per integrazione quando possibile.
• Ruota regolarmente le chiavi per le integrazioni di lunga durata.
• Revoca una chiave immediatamente se si sospetta un’esposizione.

Credenziale di chat rispetto alla chiave API

Non chiedere al supporto ISM di rivelare la credenziale di chat nascosta. È intenzionalmente non visibile all’utente.

Guide correlate

• Configurazione di ArchibotChat
• Usare ArchibotChat
• Fatturazione e crediti di ArchibotChat
• Panoramica sulla sicurezza di ArchibotChat
• Uso approvato dei dati di ArchibotChat