Una chiave di accesso è una stringa di caratteri che consente a Bitrix24 di identificare la tua app. Senza una chiave, l’app non può leggere gli affari, creare incarichi o inviare messaggi. Quando la chiave viene revocata, l’app smette immediatamente di ricevere i dati.

Tipi di chiavi in Alaio Vibecode

Scegli la chiave in base allo scopo dell’app. Ogni tipo di chiave ha una funzione specifica:

• La chiave API è necessaria a un’app, un bot o un’integrazione server per lavorare con Bitrix24. È il tipo di chiave principale e viene creata quando è necessario collegare un’app a Bitrix24.
• La chiave di autorizzazione è necessaria per le app utilizzate dai dipendenti. Dopo l’accesso, l’app opera con le autorizzazioni del singolo dipendente e non con quelle generali del proprietario dell’app.
• La chiave Management è necessaria a uno script di servizio per gestire le chiavi API: crearle, visualizzarle, sostituirle e disattivarle. Non consente all’app di accedere ad affari, incarichi, messaggi o altri dati di Bitrix24.

Come scegliere la chiave. Per un bot, un’app o un’integrazione, crea una chiave API. Se l’app deve identificare il dipendente dopo l’accesso e operare con le sue autorizzazioni, utilizza una chiave di autorizzazione. Crea una chiave Management solo per un’automazione che gestisce le chiavi API senza interventi manuali nell’account.

Chiave API

La chiave API consente a un’app di lavorare con Bitrix24. Ad esempio, può ricevere richieste da un sito web e aggiungerle al CRM.

Crea una chiave API quando:

• colleghi una nuova app o un bot,
• configuri un’integrazione server,
• vuoi concedere a uno script separato l’accesso all’app,
• sostituisci una chiave che potrebbe essere finita nelle mani di persone non autorizzate.

Per app e ambienti diversi, ad esempio di test e di produzione, è più sicuro utilizzare chiavi differenti. In questo modo, quando sostituisci una chiave, le altre continuano a funzionare.

Creare una chiave API.

1. Apri la sezione Accesso > Chiavi API.
2. Fai clic su Crea chiave.
3. Inserisci un nome che indichi chiaramente lo scopo della chiave. Ad esempio, Dashboard CRM.
4. Seleziona la modalità di accesso:

• Solo lettura: se l’app deve esclusivamente recuperare i dati. Ad esempio, per una dashboard CRM.
• Lettura e scrittura: se l’app deve creare o modificare i dati. Ad esempio, per aggiungere richieste al CRM.

5. Nel blocco Permessi di accesso, seleziona solo le sezioni necessarie. Per una dashboard CRM è sufficiente l’accesso al CRM, mentre non sono necessarie le autorizzazioni per gli incarichi, le chat o altre sezioni.
6. Seleziona il periodo di validità della chiave e, se necessario, specifica il limite di richieste al minuto.
7. Fai clic su Crea.
8. Copia la chiave e conservala in un luogo sicuro. Il valore completo viene mostrato una sola volta.

Nella sezione Chiavi API vengono visualizzati il nome della chiave, le autorizzazioni disponibili, il numero di richieste, la data dell’ultimo utilizzo e lo stato. Queste informazioni aiutano a capire quale chiave utilizza l’app e se è ancora necessaria.

Utilizzare una chiave API. Dopo la creazione, Alaio Vibecode mostra la chiave API e un prompt pronto per l’agente IA. Il prompt contiene la chiave, il link alla documentazione e le istruzioni per creare un’app o un bot.

1. Nella finestra con la chiave, fai clic su Copia prompt.
2. Incolla il prompt in Claude Code, Codex, Cursor.
3. Aggiungi la descrizione dell’attività. Ad esempio: Crea una dashboard CRM con gli indicatori del reparto vendite relativi all’ultimo mese.
4. L’agente IA creerà l’app ed eseguirà il deploy sul server.

Se per la chiave selezioni l’accesso Solo lettura al CRM, l’agente IA potrà creare una dashboard che recupera i dati degli affari e prepara un rapporto. L’app non potrà modificare o creare affari.
Alaio Vibecode: come creare e preparare un’app per l’utilizzo

Chiave di autorizzazione

La chiave di autorizzazione è necessaria quando l’app deve identificare l’utente che ha effettuato l’accesso e mostrare i dati in base alle autorizzazioni di quel dipendente.

Ad esempio, in un’app per registrarsi a un evento aziendale, ogni dipendente crea e visualizza la propria richiesta, mentre l’organizzatore può vedere le richieste di tutti i dipendenti.

Creare una chiave di autorizzazione.

1. Apri la sezione Accesso > Chiavi di autorizzazione.
2. Fai clic su Crea chiave.
3. Inserisci un nome.
4. Seleziona la modalità di accesso: Solo lettura oppure Lettura e scrittura.
5. Se l’app deve aprirsi nell’app mobile Bitrix24, attiva l’opzione Supporta l’app mobile Bitrix24. Non sarà possibile modificare questo parametro dopo la creazione.
6. Nel blocco Diritti di accesso, seleziona solo le sezioni necessarie.
7. Fai clic su Crea.
8. Copia la chiave e il prompt pronto per l’agente IA. Il valore completo della chiave viene mostrato una sola volta.

Utilizzare una chiave di autorizzazione.

1. Nella finestra con la chiave, fai clic su Copia prompt.
2. Incolla il prompt in Claude Code, Codex, Cursor.
3. Aggiungi la descrizione dell’attività. Ad esempio: Crea un’app per registrare i dipendenti a un evento aziendale.
4. L’agente IA creerà l’app ed eseguirà il deploy sul server.

L’agente IA creerà l’app. Se deve essere aperta all’interno di Bitrix24, nell’elenco delle chiavi di autorizzazione fai clic su Incorpora in Bitrix24.
Alaio Vibecode: come scegliere i punti di incorporamento dell’app

Chiave Management

La chiave Management è necessaria a uno script che gestisce le chiavi API tramite REST API. Se le chiavi API vengono create e sostituite manualmente nell’account, la chiave Management non è necessaria.

Ad esempio, per ogni nuovo progetto di lavoro potrebbe essere necessario generare automaticamente una chiave API separata. Lo script con la chiave Management accede all’API di gestione delle chiavi, crea una chiave API e la trasmette al processo di configurazione del progetto. In questo modo non è necessario creare manualmente una chiave ogni volta.

Non utilizzare la chiave Management in un’app al posto della chiave API. Non consente di accedere al CRM, agli incarichi, alle chat o ad altri dati di Bitrix24. Per permettere all’app di lavorare con questi dati, utilizza una chiave API.

Creare una chiave Management.

1. Fai clic sull’avatar nell’angolo in alto a destra.
2. Seleziona Chiavi Management.
3. Fai clic su Crea chiave.
4. Inserisci un nome chiaro. Ad esempio, Rotazione programmata delle chiavi.
5. Seleziona la modalità:

• Solo lettura: se lo script deve soltanto visualizzare l’elenco delle chiavi.
• Lettura e scrittura: se lo script deve creare, modificare o disattivare le chiavi.

6. Seleziona le autorizzazioni necessarie:

• Gestione delle chiavi API: per creare, sostituire ed eliminare le chiavi API.
• Lettura account Bitrix24: per ottenere l’elenco degli account disponibili.
• Revisione dei ticket: solo se lo script lavora con le richieste. Questa autorizzazione è disponibile per gli utenti con il ruolo platform-admin.

7. Fai clic su Crea.
8. Copia la chiave. Il valore completo della chiave Management viene mostrato una sola volta.

Utilizzare una chiave Management. Quando lo script accede all’API di gestione delle chiavi /v1/keys/*, la chiave Management viene trasmessa nell’intestazione X-Api-Key. Durante la creazione di una chiave Management non viene fornito un prompt pronto per l’agente IA.

1. Crea una chiave Management separata per ogni script.
2. Salva la chiave nei secret CI/CD o in un gestore di segreti. Non inserirla nel codice dello script.
3. Seleziona solo le autorizzazioni necessarie. Se lo script deve soltanto controllare l’elenco delle chiavi, è sufficiente la modalità Solo lettura.
4. Aggiungi la chiave alle impostazioni dello script. All’avvio, lo script la trasmetterà all’API e potrà eseguire le azioni consentite sulle chiavi API.
5. Quando lo script non è più necessario, disattiva o elimina la relativa chiave Management.

Rigenerare una chiave

Rigenera una chiave quando devi sostituirne il valore senza creare una nuova app. Può essere necessario, ad esempio, durante una rotazione programmata delle chiavi, quando trasferisci l’app a un altro dipendente oppure se la chiave potrebbe essere diventata pubblica.

Durante la rigenerazione, Alaio Vibecode crea una nuova chiave. L’app, il server, i punti di incorporamento, le posizioni e le autorizzazioni rimangono invariati.

1. Apri la sezione Applicazioni.
2. Seleziona l’app desiderata.
3. Nella riga Chiave, fai clic su Rigenera chiave.
4. Fai clic su Riemetti la chiave.
5. Copia la nuova chiave e salvala in un luogo sicuro. Il valore completo viene mostrato una sola volta.
6. Aggiorna la chiave nelle integrazioni esterne, se utilizzano ancora il valore precedente.

Durante una normale rigenerazione, la vecchia chiave attiva continua a funzionare per altre 24 ore. Aggiorna le integrazioni esterne durante questo periodo: allo scadere delle 24 ore, la vecchia chiave smetterà di funzionare.

Se la chiave è bloccata. Alaio Vibecode può bloccare una chiave che è diventata pubblica. Nella scheda dell’app, la chiave avrà lo stato Bloccata e l’app non potrà accedere ai dati di Bitrix24.

Rigenera la chiave seguendo gli stessi passaggi. Non fare affidamento sul periodo di transizione di 24 ore: è disponibile solo durante la normale rigenerazione di una chiave attiva.

Se Alaio Vibecode non ha aggiornato la chiave sul server. Dopo la sostituzione della chiave, Alaio Vibecode mostrerà il risultato nella stessa finestra. Le azioni successive dipendono dal messaggio visualizzato.

• La chiave sul server è stata aggiornata e l’applicazione è stata riavviata: non devi eseguire altre operazioni.
• Il server dell’applicazione non è disponibile, quindi la chiave nel suo ambiente non è stata aggiornata: apri la scheda del server dell’app nella sezione Server Black Hole. Se il server è sospeso, fai clic su Riattiva. Quando il server si avvia, torna alla scheda dell’applicazione e sostituisci nuovamente la chiave.
• La chiave non è stata trovata nelle variabili di ambiente del server oppure Impossibile aggiornare la chiave sul server: Alaio Vibecode non è riuscito a sostituire automaticamente il valore. Copia la nuova chiave e apri lo strumento IA in cui hai creato l’app. Chiedi di sostituire nelle impostazioni dell’app la vecchia chiave API con quella nuova e di eseguire nuovamente il deploy.
• La chiave sul server è stata aggiornata, ma non è stato possibile riavviare l’applicazione: riavvia manualmente l’app.

Per una chiave attiva, il vecchio valore continua a funzionare per altre 24 ore. Se la vecchia chiave è stata bloccata, aggiorna immediatamente la variabile di ambiente e riavvia l’app: la chiave precedente non funziona più.