Vai al contenuto principale
Una credenziale che puoi leggere da uno schermo è una credenziale che puoi far trapelare. Una volta copiata una nuova chiave, quasi mai ti serve di nuovo il suo plaintext — ti serve riconoscerla: quale chiave è questa, in quale environment, è quella usata dall’agent in errore. La console di OrcaRouter risponde a questo senza mai ri-stampare un segreto funzionante: ogni chiave è resa in una forma mascherata che conserva giusto abbastanza caratteri per identificarla e nasconde il resto. Questa pagina copre come appare la forma mascherata, quando il plaintext è e non è mostrato, e come mascherare i valori delle chiavi API in sicurezza nei tuoi log e nel tuo tooling.

​
1. Perché mascherare i valori delle chiavi API quando vengono mostrati

La chiave completa è una credenziale bearer: chiunque la legga può chiamare il gateway come te, fino ai limiti di quella chiave. Le viste di console vengono copiate in screenshot, screen-share, ticket di supporto e bug report di continuo — quindi mostrare il segreto vivo in un elenco di chiavi trasformerebbe ognuno di questi in un leak di credenziale. Il mascheramento risolve questo separando due bisogni che di solito vengono confusi:
  • Identificazione — quale chiave è questa? Risposta da un’impronta mascherata stabile che puoi leggere a colpo d’occhio.
  • Uso — qual è il segreto? Risposta esattamente una volta alla creazione, e dietro una rivelazione deliberata e role-gated dopo quella.
La console soddisfa il primo bisogno ovunque e controlla il secondo, così la superficie di default — l’elenco delle chiavi che fissi tutto il giorno — non porta mai un segreto utilizzabile.
Una chiave mascherata non è una credenziale funzionante. Non può autenticare una richiesta. Solo il plaintext completo (sk-orca-…) che hai copiato alla creazione, o rivelato nuovamente attraverso l’endpoint controllato, può chiamare il gateway.

​
2. Come appare la forma mascherata

La console mostra il prefisso di brand della chiave, poi una sequenza fissa di asterischi, poi gli ultimi quattro caratteri — abbastanza per distinguere due chiavi, non abbastanza per ricostruirne nessuna.
Hai creatoLa console mostra
sk-orca-9f3aK2…long…7Qm4sk-orca-9f3****7Qm4
Il primo segmento conserva il prefisso sk-orca- e alcuni caratteri iniziali; gli ultimi quattro caratteri sono la coda che riconoscerai quando incroci una riga di log o un errore. Tutto ciò che sta in mezzo è collassato in una maschera fissa — la sequenza di asterischi è una costante, così la sua larghezza non rivela mai la vera lunghezza della chiave.
Abbina la coda mascherata all’etichetta environment della chiave e al suo nome quando devi trovare in fretta una chiave specifica — la coda di quattro caratteri più un tag prod / staging è quasi sempre sufficiente per pescare quella giusta da un elenco senza mai rivelare il plaintext.

​
3. Quando il plaintext è mostrato — e quando non lo è

C’è esattamente un momento in cui la chiave completa è tua da copiare, e un unico percorso controllato per recuperarla di nuovo.
Quando coni una chiave, la console mostra il plaintext completo sk-orca-… una volta. Copialo nel tuo secret manager in quel momento. Ogni visualizzazione successiva di quella chiave — l’elenco, il pannello di dettaglio, i risultati di ricerca — mostra solo la forma mascherata.
Puoi rivelare nuovamente il plaintext di una chiave ordinaria su richiesta, ma è un’azione deliberata dietro il ruolo Developer+ — non qualcosa che l’elenco di default esponga mai. Rivelare nuovamente una chiave con scope gateway (is_firewall_gateway) richiede il ruolo Admin (o Owner), perché quel token può leggere le credenziali degli MCP server registrati.
Elencare le chiavi, aprire il dettaglio di una chiave, cercare, e ogni lettura del token object restituiscono la forma mascherata. Il plaintext non è mai incluso in una risposta di elenco o di ricerca.
Poiché la ri-rivelazione è controllata e una chiave con scope gateway ha bisogno di Admin per essere riletta, tratta la copia al momento della creazione come la tua unica cattura affidabile. Salvala subito nel tuo secret manager. Se perdi il plaintext di una chiave ordinaria puoi rivelarlo di nuovo (Developer+); se non puoi rivelarlo e non puoi recuperarlo, ruota a una chiave nuova anziché aggirare una chiave che non puoi più leggere.

​
4. Un esempio concreto: identificare la chiave trapelata

Supponi che scatti un alert — una chiave sta facendo chiamate da un IP inatteso — e la riga di log porta la coda mascherata …7Qm4. Non ti serve il plaintext per agire:
  1. Apri l’elenco Chiavi della console (/console/token). Ogni riga mostra la sua impronta mascherata — sk-orca-9f3****7Qm4 e la sua etichetta environment.
  2. Abbina la coda …7Qm4 (e il tag prod) alla riga incriminata. La forma mascherata è esattamente l’identificatore che ti serve qui — nessun segreto è esposto nell’elenco, nell’alert o nel tuo screenshot di esso.
  3. Disabilita quella chiave per metterla in pausa, o eliminala per revocarla per sempre — entrambe sono azioni masked-safe che non stampano mai il plaintext. Vedi Gestire le chiavi e Risposta a una chiave trapelata.
L’intero triage gira sull’impronta mascherata. Il plaintext resta nel tuo secret manager dove appartiene.

​
5. Mascheramento nei tuoi log e nel tuo tooling

Il gateway maschera le proprie superfici; il tuo lato lo controlli tu. Lo stesso principio si applica ovunque una chiave possa atterrare nel tuo stack:
  • Non loggare mai l’header Authorization o il valore sk-orca-… grezzo. Se devi registrare quale chiave ha fatto una chiamata, logga la stessa forma che usa la console — il prefisso e gli ultimi quattro caratteri — non il segreto completo.
  • Memorizza il plaintext solo in un secret manager, mai in source control, nei log di CI o in un file di config committato in un repo. La chiave è mascherata nella console proprio perché i tuoi stessi sistemi siano l’unico posto in cui il segreto vivo risiede.
  • Dai alle chiavi uno scope ristretto così che anche una credenziale trapelata abbia un raggio d’esplosione limitato — un modello, un range di IP, un cap di spesa. Vedi la Checklist di minima agenzia.
Il mascheramento riduce l’esposizione in visualizzazione; non riduce il potere di una chiave che effettivamente trapela. Un’impronta mascherata in un log è sicura, ma la chiave viva in un secret manager autentica comunque pienamente — ed è per questo che uno scope ristretto e una rotazione rapida contano tanto quanto il mascheramento.

​
6. Come si inserisce nel resto dell’igiene delle chiavi

Il mascheramento è un layer di una postura di difesa in profondità per le credenziali:

Gestire le chiavi

Crea, disabilita e revoca le chiavi — il ciclo di vita dietro ogni riga mascherata nell’elenco.

Il token object

Ogni campo che una chiave porta, inclusi i limiti che vincolano il raggio d’esplosione di una chiave trapelata.

Rotazione delle chiavi

Il passaggio di consegne zero-downtime a una chiave nuova quando non puoi recuperare o fidarti di una vecchia.

Risposta a una chiave trapelata

Cosa fare nell’istante in cui sospetti che una credenziale sia esposta.
Per il quadro più ampio di come chiavi, policy e workspace si annidano per dare a ogni agent l’identità più ristretta, vedi Scope e chiavi. La regola è semplice: la console ti mostra abbastanza per riconoscere una chiave e mai abbastanza per farne trapelare una. Tieni il plaintext nel tuo secret manager, appoggiati all’impronta mascherata ovunque altro, e ruota nell’istante in cui l’identità di una chiave è in dubbio.