Autenticazione delle automazioni
Creare, conservare, ruotare e revocare le chiavi API usate dai robot e dai middleware di integrazione.
Ogni chiamata inbound verso Blu Pantheon deve essere autenticata con una chiave API. Le chiavi sono legate al tenant, hanno scope espliciti e una scadenza. Questa pagina descrive il ciclo di vita completo.
Prima di iniziare
- Un utente con ruolo Amministratore tenant o permesso identity:api-keys:write
- Il progetto di destinazione già creato (es. bp_proj_7f3a9c21)
- Un gestore di segreti disponibile (Orchestrator Assets, Azure Key Vault, credenziali n8n)
Formato della chiave
Esempio di chiave API di produzione
bp_live_••••••••••••••••Il prefisso identifica l ambiente. Il resto è generato casualmente.
| Prefisso | Ambiente | Uso |
|---|---|---|
bp_live_ | Produzione | Dati reali, effetti sul business |
bp_test_ | Sandbox | Dati di prova, nessun effetto su clienti reali |
Sul server viene conservato solo l'hash SHA-256 della chiave. Il prefisso e gli ultimi quattro caratteri restano visibili in Console per permetterti di riconoscerla nei log.
Il valore viene mostrato una sola volta
Alla creazione, la chiave completa compare in un riquadro con pulsante di copia. Chiudendo la finestra non è più recuperabile. Se la perdi, revocala e creane una nuova.
Creare una chiave API
Apri la sezione Chiavi API
Dal menu Amministrazione, seleziona Chiavi API. La tabella elenca le chiavi attive con nome, prefisso, scope, data di creazione, ultimo utilizzo e scadenza.
Crea la nuova chiave
Clicca Nuova chiave e compila:
| Campo | Valore consigliato |
|---|---|
| Nome | rpa-uipath-prod — descrittivo, identifica il consumatore |
| Descrizione | Robot prenotazioni verso ERP — owner: team automazione |
| Progetto | bp_proj_7f3a9c21 |
| Ambiente | Produzione |
| Scadenza | 12 mesi |
Assegna solo gli scope necessari
Seleziona i permessi minimi per il compito del robot. Non usare mai un profilo amministrativo per un'automazione.
Copia e conserva il valore
Copia immediatamente la chiave e salvala nel gestore di segreti. Verifica che l'operazione sia riuscita prima di chiudere la finestra.
Verifica con una chiamata di prova
curl -sS -o /dev/null -w "%{http_code}\n" \
"https://api.blupantheon.com/identity/v1/me" \
-H "Authorization: Bearer bp_live_xxxxxxxxxxxxxxxx"Il risultato atteso è 200. Un 401 indica chiave errata o già revocata.
Scope e principio del minimo privilegio
I permessi seguono il formato {servizio}:{risorsa}:{azione}.
| Scope | Consente di | Assegnalo quando |
|---|---|---|
identity:sessions:read | Leggere sessioni e trascrizioni | Il robot deve consultare la conversazione |
identity:sessions:write | Aggiornare metadati, aggiungere note, chiudere sessioni | Il robot riporta l'esito nella sessione |
identity:clients:read | Leggere anagrafiche cliente | Il robot cerca il cliente nel gestionale |
identity:clients:write | Creare o aggiornare clienti | Il robot sincronizza il CRM |
identity:bookings:read | Leggere prenotazioni | Il robot allinea l'agenda |
identity:bookings:write | Creare, confermare, annullare prenotazioni | Il robot scrive nell'ERP e conferma |
identity:documents:read | Scaricare documenti e metadati | Il robot deposita nel DMS |
identity:documents:write | Caricare documenti e classificazioni | Il robot importa da protocollo |
identity:webhooks:read | Leggere configurazione ed esiti di consegna | Il monitoraggio interroga i log |
Errore frequente
Assegnare write quando serve solo read. Un robot che sbaglia una selezione a schermo può
sovrascrivere anagrafiche reali. Parti sempre dai soli scope di lettura e aggiungi le scritture
quando il flusso è verificato.
Uso della chiave nelle richieste
/identity/v1/sessionsAPI KeyTutte le richieste inbound usano lo stesso schema di autenticazione.
Header di autenticazione
| Parametro | Tipo | Obblig. | Default | Descrizione |
|---|---|---|---|---|
Authorization | string | Sì | — | Formato "Bearer bp_live_xxxxxxxxxxxxxxxx". Obbligatorio su ogni richiesta. |
X-BP-Project | string | No | — | Identificativo del progetto quando la chiave ha accesso a più progetti. |
Idempotency-Key | string | No | — | Chiave di deduplica per le richieste di scrittura. Consigliata su POST e PATCH. |
Content-Type | string | No | — | Impostare "application/json" su tutte le richieste con corpo. |
Mai nella query string
Non passare la chiave come parametro URL. Finisce nei log dei proxy, nei referrer e nella
cronologia dei browser. Usa esclusivamente l'header Authorization.
Variabili d'ambiente dell'automazione
| Variabile | Obbligatoria | Default | Descrizione | Esempio |
|---|---|---|---|---|
BP_API_BASE_URL | Sì | — | Base URL delle API. Non includere lo slash finale. | https://api.blupantheon.com |
BP_API_KEY | Sì | — | Chiave API usata nel header Authorization. Da gestore di segreti, mai nel codice. | bp_live_xxxxxxxxxxxxxxxx |
BP_PROJECT_ID | Sì | — | Progetto di riferimento per le chiamate inbound. | bp_proj_7f3a9c21 |
BP_WEBHOOK_SECRET | Sì | — | Segreto per la verifica della firma HMAC dei webhook in ingresso. | whsec_xxxxxxxxxxxxxxxx |
BP_WEBHOOK_SECRET_NEXT | No | — | Secondo segreto accettato durante una rotazione senza interruzioni. | whsec_yyyyyyyyyyyyyyyy |
BP_TIMEOUT_MS | No | — | Timeout delle chiamate HTTP verso le API. Valore consigliato 15000. | 15000 |
BP_MAX_RETRIES | No | — | Numero massimo di ritentativi con backoff esponenziale sui codici 429 e 5xx. | 3 |
Richiesta autenticata: esempi
#!/usr/bin/env bash
set -euo pipefail
: "${BP_API_KEY:?variabile BP_API_KEY non impostata}"
BASE_URL="${BP_API_BASE_URL:-https://api.blupantheon.com}"
curl -sS --fail-with-body \
"$BASE_URL/identity/v1/clients?limit=20" \
-H "Authorization: Bearer $BP_API_KEY" \
-H "X-BP-Project: bp_proj_7f3a9c21" \
-H "Accept: application/json"Conservazione dei segreti
| Piattaforma | Dove conservare | Come leggere |
|---|---|---|
| UiPath | Orchestrator → Assets → tipo Credential | Attività Get Credential |
| Power Automate | Azure Key Vault | Connettore Key Vault, azione Get secret |
| n8n | Credentials → Header Auth | Selezione della credenziale nel nodo HTTP Request |
| Make | Connections / variabili di scenario | Riferimento alla connessione nel modulo HTTP |
| Zapier | Storage cifrato dello Zap o variabile in Code step | inputData mappato dallo step |
| Python / Robocorp | Robocorp Vault o variabili d'ambiente | RPA.Robocloud.Secrets oppure os.environ |
| Automation Anywhere | Credential Vault | Locker + Credential attribute |
| Container / Kubernetes | Secret del cluster o Azure Key Vault CSI | Variabile d'ambiente montata |
Vietato
Chiavi hardcoded nel sorgente del workflow, nei file .xaml versionati, nei log applicativi,
nei messaggi di errore inviati via email o negli screenshot allegati ai ticket.
Rotazione senza interruzioni
La rotazione si esegue con due chiavi attive contemporaneamente. In nessun momento il robot resta senza credenziale valida.
Crea la nuova chiave
Nome rpa-uipath-prod-2026b, stessi scope della chiave in uso, stessa scadenza a 12 mesi.
Copia il valore.
Distribuisci la nuova chiave
Aggiorna il valore nel gestore di segreti. Non rimuovere ancora la chiave precedente: entrambe sono valide e accettate dalla piattaforma.
Riavvia i consumatori
Riavvia i robot, i job e i servizi che leggono il segreto all'avvio. Chi legge il segreto a ogni esecuzione non richiede riavvio.
Verifica l'adozione
Nella tabella Chiavi API controlla la colonna Ultimo utilizzo. Attendi finché la nuova chiave risulta usata e la vecchia non registra più utilizzi. Come regola, attendi almeno 48 ore per coprire i job settimanali più lenti.
Revoca la chiave precedente
Dal menu contestuale della vecchia chiave scegli Revoca. La revoca è immediata e
irreversibile: ogni richiesta che la usa riceve 401.
Registra l'operazione
Annota data, operatore e motivo nel registro delle credenziali. L'evento è comunque tracciato negli audit log.
Scadenza e revoca
| Situazione | Azione |
|---|---|
| Chiave in scadenza tra 30 giorni | La Console mostra un avviso. Pianifica la rotazione. |
| Chiave scaduta | Le richieste rispondono 401. Serve una nuova chiave. |
| Sospetto di compromissione | Revoca subito, poi crea la sostituta. Non rimandare. |
| Robot dismesso | Revoca la chiave nello stesso giorno della dismissione. |
| Fornitore esterno che termina il contratto | Revoca e verifica negli audit log gli accessi finali. |
Revoca in emergenza
In caso di chiave esposta pubblicamente (repository, log, ticket), revoca prima e comunica
poi. Una chiave bp_live_ compromessa consente operazioni sui dati reali del tenant.