Configurare la Compliance API

La Compliance API utilizza due tipi di chiave, e quale creare dipende da quale prodotto Claude utilizza la tua organizzazione. I proprietari principali e i proprietari dell'organizzazione creano Compliance Access Key in claude.ai; queste chiavi sbloccano l'intera Compliance API. La chiave di un proprietario principale può coprire ogni organizzazione sotto l'organizzazione padre; la chiave di un proprietario dell'organizzazione copre solo la propria organizzazione. Gli amministratori dell'organizzazione creano chiavi Admin API in Claude Console; queste chiavi sbloccano solo l'Activity Feed (feed delle attività).

Di quale chiave hai bisogno?

Un tenant Claude Enterprise ha una organizzazione padre che centralizza identità, SSO e SCIM per ogni organizzazione di carico di lavoro al di sotto di essa. Queste organizzazioni di carico di lavoro sono le organizzazioni collegate dell'organizzazione padre.

Configurare la Compliance API

La configurazione è un unico flusso: abilita la Compliance API per la tua organizzazione, quindi crea una Compliance Access Key in claude.ai. Un'organizzazione Claude Console invece crea una chiave Admin API dopo l'abilitazione; le chiavi Admin API raggiungono solo l'Activity Feed.

1. 1

   Abilita la Compliance API

   Dove abiliti la Compliance API dipende da come è configurata la tua organizzazione:

   • Organizzazioni Claude Enterprise: Il proprietario principale abilita la Compliance API in claude.ai > Organization settings > API. L'abilitazione avviene a livello di organizzazione padre e si propaga a ogni organizzazione collegata, sia claude.ai che Claude Console.
   • Organizzazioni Claude Console autonome: Un amministratore dell'organizzazione attiva l'interruttore Compliance API in Claude Console > Settings > Security. L'abilitazione è self-service per le organizzazioni idonee e la modifica ha effetto immediato. Se la sezione Compliance API non è visibile, non hai il ruolo di amministratore, la tua organizzazione è collegata a un'organizzazione padre (la Compliance API viene invece abilitata dall'organizzazione padre), oppure la tua organizzazione non è idonea all'abilitazione self-service; contatta il tuo team account o il supporto Anthropic se non sei sicuro di quale caso si applichi.
   • Organizzazioni Claude Console collegate a un'organizzazione padre: Non c'è nulla da attivare in Claude Console. Chiedi al proprietario principale della tua organizzazione padre di abilitare la Compliance API in claude.ai, oppure contatta il tuo team account.

   Un'organizzazione Claude Console autonoma utilizza chiavi Admin API anziché Compliance Access Key: dopo l'abilitazione, salta i passaggi rimanenti e crea una nuova chiave Admin API. I passaggi rimanenti forniscono Compliance Access Key, disponibili solo per le organizzazioni che fanno parte di un tenant Claude Enterprise.

2. 2

   Decidi l'ambito della chiave

   L'accesso di una chiave viene impostato al momento della creazione. Decidi quali organizzazioni copre la chiave:

   • Una chiave per l'organizzazione padre può accedere a ogni organizzazione sotto l'organizzazione padre.
   • Una chiave per una singola organizzazione può accedere solo a quell'organizzazione.
3. 3

   Accedi con il ruolo corrispondente

   Accedi a claude.ai. Il proprietario principale dell'organizzazione padre può creare una chiave con entrambi gli ambiti. Un proprietario dell'organizzazione può creare una chiave limitata solo alla propria organizzazione.

   Se la pagina API descritta nel passaggio successivo non è visibile, o gli scope di compliance non sono disponibili durante la creazione di una chiave, o il tuo ruolo non può creare Compliance Access Key, oppure la Compliance API non è ancora stata abilitata per la tua organizzazione (torna al primo passaggio).

4. 4

   Apri le impostazioni API

   Vai a claude.ai > Organization settings > API e trova la sezione Keys.

5. 5

   Crea la chiave

   Fai clic su Create key, assegna un nome alla chiave e seleziona uno o più scope dalla tabella seguente. Fai clic su Create.

   Scope	Concede
   read:compliance_activities	Leggere l'Activity Feed. Una chiave che copre l'organizzazione padre legge gli eventi per l'organizzazione padre e tutte le organizzazioni collegate.
   read:compliance_user_data	Leggere chat, messaggi, file, progetti, metadati e trascrizioni delle sessioni degli utenti, utenti dell'organizzazione e membri dei gruppi
   delete:compliance_user_data	Eliminare chat, file e progetti degli utenti
   read:compliance_org_data	Leggere i metadati dell'organizzazione (nomi, tipi, ruoli e gruppi) e le impostazioni effettive in vigore per le organizzazioni sotto l'organizzazione padre. Gli elenchi degli utenti e l'appartenenza ai gruppi richiedono read:compliance_user_data.

   Scegli l'insieme di scope più ristretto di cui la tua integrazione ha bisogno:

   • Una pipeline di audit che legge solo l'Activity Feed ha bisogno solo di read:compliance_activities.
   • Uno strumento di eDiscovery che legge chat e file ma non li elimina mai non ha bisogno di delete:compliance_user_data.
   • Se il tuo flusso di lavoro legge ed elimina, usa due chiavi con scope separati in modo che una chiave di lettura trapelata non possa eliminare dati.

   Gli scope delle Compliance Access Key sono immutabili dopo la creazione. Per modificare gli scope, crea una nuova chiave con gli scope desiderati, quindi elimina quella vecchia.

6. 6

   Copia e conserva il segreto

   Copia la chiave segreta visualizzata (che inizia con sk-ant-api01-) e conservala nel tuo gestore di segreti. Il segreto completo viene visualizzato una sola volta.

7. 7

   Esporta la chiave per gli esempi di questa guida

   Imposta la chiave come variabile d'ambiente in modo che gli esempi shell di questa guida possano leggerla:

   export ANTHROPIC_COMPLIANCE_ACCESS_KEY=sk-ant-api01-...

   

Creare una chiave Admin API

Segui i passaggi in Creare una chiave Admin API, quindi imposta la chiave come variabile d'ambiente:

export ANTHROPIC_ADMIN_KEY=sk-ant-admin01-...

Il nome di variabile distinto impedisce alla chiave Admin API di sovrascrivere una Compliance Access Key se le fornisci entrambe. Gli esempi cURL di questa guida leggono la chiave da $ANTHROPIC_COMPLIANCE_ACCESS_KEY; sostituisci con $ANTHROPIC_ADMIN_KEY quando chiami l'Activity Feed con una chiave Admin API.

Le chiavi Admin API hanno lo scope read:compliance_activities solo se la Compliance API era abilitata per l'organizzazione al momento della creazione della chiave; vedi Configurare la Compliance API. Non possono ricevere nessun altro scope della Compliance API, quindi le chiamate a qualsiasi endpoint diverso dall'Activity Feed restituiscono 403 Forbidden.

Per il ruolo della stessa chiave nella gestione della tua organizzazione Claude Console, vedi Admin API.

Verificare gli scope della tua chiave

Per ispezionare gli scope di una chiave che già possiedi, usa uno dei seguenti segnali.

• Prefisso della chiave. sk-ant-admin01- è una chiave Admin API (ha solo read:compliance_activities, soggetto alla tempistica di abilitazione descritta nella sezione precedente). sk-ant-api01- è una Compliance Access Key; i suoi scope sono il sottoinsieme che hai selezionato alla creazione.
• Interfaccia delle impostazioni. Apri la sezione Keys in claude.ai > Organization settings > API, oppure la sezione Admin keys in Claude Console > Settings > Admin keys, e leggi la colonna Scopes per la chiave.
• Risposte di errore. Una chiamata che supera gli scope della chiave restituisce un 403 con un messaggio nel formato Missing required scopes. Got: [<scopes the key carries>] Needed: [<scopes the endpoint requires>]. Vedi Gestire gli errori della Compliance API per il catalogo completo degli errori.

{
  "error": {
    "type": "permission_error",
    "message": "Missing required scopes. Got: ['read:compliance_activities'] Needed: ['read:compliance_user_data']"
  }
}

Gestire e ruotare le chiavi

Elimina una Compliance Access Key dalla stessa tabella Keys in cui l'hai creata: vai a claude.ai > Organization settings > API. Elimina una chiave Admin API da Claude Console > Settings > Admin keys.

L'eliminazione di una chiave ha effetto alla richiesta successiva: non c'è alcun periodo di tolleranza. Le Compliance Access Key non scadono da sole.

Per ruotare una chiave senza interruzioni:

1. Crea una nuova chiave con gli stessi scope.
2. Aggiorna la tua integrazione per usare la nuova chiave.
3. Verifica che l'integrazione funzioni con la nuova chiave.
4. Elimina la vecchia chiave.

I cursori di paginazione memorizzati prima di una rotazione rimangono validi: i cursori sono legati all'organizzazione, non alla chiave.

Se una Compliance Access Key trapela, eliminala immediatamente, controlla l'Activity Feed per le attività compliance_api_accessed della chiave compromessa e ruota tutte le credenziali a valle che la chiave trapelata poteva raggiungere. Passa activity_types[]=compliance_api_accessed per limitare la query, quindi nel tuo client mantieni le attività il cui actor.type è api_actor e il cui actor.api_key_id corrisponde alla chiave compromessa; vedi Comprendere l'oggetto Activity per lo schema dell'attore.

Passaggi successivi