Chiavi API
In questa pagina
Le chiavi API consentono al tuo software, o a qualsiasi sistema di terze parti che supporti il BYOK (Bring Your Own Key), di usare i modelli pubblicati dal Performance Hub. Le chiavi si gestiscono in Settings (ingranaggio) → Service Access & API Keys. Per gestirle devi essere un Organisation Administrator.
"Genera chiavi API affinché software e sistemi di terze parti che supportano BYOK (Bring Your Own Key) possano connettersi ai models pubblicati da Performance Hub."
Figura 1: l'elenco delle chiavi API: etichetta, chiave mascherata, stato, spesa e limiti, modelli, ultimo utilizzo e azioni di riga
L'elenco delle chiavi
| Colonna | Significato |
|---|---|
| Label | Il nome facoltativo che hai assegnato alla chiave. |
| Key | La chiave mascherata (ad es. phk_7Qm2…Xa9LkP): il segreto completo non viene più mostrato dopo la creazione. |
| Status | Active, Provisioning… (per poco tempo, mentre una nuova chiave viene configurata) oppure Disabled (revocata; la riga appare attenuata). |
| Spend / limits | La spesa complessiva e l'avanzamento rispetto agli eventuali limiti di spesa impostati sulla chiave. |
| Models | all oppure il numero di modelli a cui la chiave è limitata. |
| Last used | Quando la chiave ha effettuato l'ultima richiesta. |
| Actions | Edit, Rotate, Revoke (o Re-activate), Delete. |
Se usi i Workflows, una riga Workflows mostra Managed service al posto di una chiave mascherata. Se non ci sono chiavi, l'elenco mostra "No API keys yet."
Creare una chiave
Fai clic su Create key. Si apre il pannello Create API key:
Figura 2: il pannello Create API key: etichetta, tipo di connessione, limiti di spesa, limiti di frequenza, restrizione dei modelli e sostituzione dei guardrail
| Impostazione | Comportamento |
|---|---|
| Label (optional) | Un nome per la chiave, di solito il sistema a cui è destinata (ad esempio Hotel Concierge App, Clinic Intake Assistant o Booking Website). Fortemente consigliato: le etichette sono il modo in cui l'utilizzo viene attribuito in Activity e Logs. |
| Connection type | API key: "Generic API keys remain in the API Keys list." External agent: "External agents appear under Connected Services and use this key to authenticate." Si imposta alla creazione della chiave e non può essere modificato in seguito. |
| Set spend limits for this key | "Set any combination of daily, monthly and lifetime caps for this key.": Daily limit ("Resets at the start of each day (facility timezone)."), Monthly limit ("Resets on the 1st of each month (facility timezone).") e Lifetime cap ("Total spend over the lifetime of this key. Never resets."). |
| Rate limits (optional) | "Cap requests and tokens per minute for this key. Leave blank for unlimited.": Requests / min e Tokens / min. |
| Restrict models for this key | "Only the selected models will be usable with this key." Scegli tra i modelli attivati per la struttura. |
| Override facility guardrails for this key | "Select none to explicitly disable guardrails for this key." Quando è attivo, questa chiave usa una propria selezione di guardrail invece di quella della struttura, compresa l'opzione "none". Vedi Guardrails. |
Fai clic su Create key.
Il segreto visualizzato una sola volta
La nuova chiave viene mostrata una sola volta, nella finestra di dialogo Copy your API key:
Figura 3: la nuova chiave viene mostrata una sola volta: copiala prima di chiudere la finestra di dialogo
"Questa è l'unica volta in cui viene mostrata la chiave completa. Conservala in un luogo sicuro."
Copiala nel tuo gestore dei segreti prima di fare clic su Done. Dopo la chiusura di questa finestra di dialogo viene visualizzata solo la forma mascherata. Se perdi il segreto, usa Rotate sulla chiave per ottenerne uno nuovo.
Modificare una chiave
Fai clic sulla riga di una chiave (o sulla sua matita Edit) per aprire il pannello Configure API key, con le stesse impostazioni della creazione (etichetta, limiti di spesa, limiti di frequenza, restrizione dei modelli, sostituzione dei guardrail):
Figura 4: il pannello Configure API key
Le modifiche diventano effettive pochi istanti dopo il salvataggio. Quando una chiave ha limiti giornalieri/mensili, la sua riga mostra l'utilizzo rispetto a tali limiti (Today, This month, Lifetime) e un badge Limit reached quando uno viene raggiunto.
Ciclo di vita della chiave: rotazione, revoca, eliminazione
Ogni azione prevede una finestra di conferma che indica esattamente cosa succederà:
| Azione | Effetto | Testo di conferma |
|---|---|---|
| Rotate | Emette un nuovo segreto (mostrato una sola volta) con le stesse impostazioni; il vecchio segreto smette di funzionare immediatamente. | "A new key will be issued and the current key will stop working immediately." "You will need to reconfigure any services still using the old key. This cannot be undone." |
| Revoke | Disattiva la chiave immediatamente, in modo reversibile. | "This key will be disabled immediately and any services using it will stop working. You can re-activate it again later." |
| Re-activate | Ripristina una chiave revocata (stesso segreto). | Nessuno: viene eseguita immediatamente. |
| Delete | Rimuove la chiave in modo permanente. | "This permanently deletes the key and any services using it will stop working. This cannot be undone." |
Figura 5: la conferma di eliminazione della chiave API
Quale usare: ruota la chiave se sospetti una fuga di dati (il servizio mantiene impostazioni e cronologia, basta aggiornare il segreto); revocala per sospendere temporaneamente un sistema; eliminala solo quando l'integrazione è dismessa definitivamente.
Connettersi con una chiave
La scheda Connecting to the API sotto l'elenco delle chiavi mostra l'URL di base e una richiesta di esempio da copiare e incollare per il tuo ambiente. Vedi Connettere la tua applicazione per la guida rapida completa con esempi di SDK e gestione degli errori.