Profili utente per l'attribuzione ai clienti finali

I "user profiles" (profili utente, di seguito "profili") indicano ad Anthropic a quale dei tuoi clienti finali si riferisce ciascuna richiesta API. Una "safety enforcement action" (azione di applicazione delle misure di sicurezza), come una sospensione o un blocco, può quindi riguardare un solo cliente finale invece dell'intera organizzazione. In tal caso, il resto del tuo traffico non subisce conseguenze.

Se gestisci una piattaforma o un gateway, oppure rivendi l'accesso all'API, le richieste che invii per i tuoi clienti finali arrivano sotto la tua organizzazione. Anthropic esegue classificatori di sicurezza automatici sul traffico API. Senza un profilo nella richiesta, un singolo cliente finale può attivare un'azione di applicazione che riguarda l'intera organizzazione.

Registra ciascun cliente finale una sola volta con POST /v1/user_profiles e memorizza l'ID uprof_ restituito. Poi invia quell'ID nell'header anthropic-user-profile-id in ogni richiesta che effettui per conto di quel cliente finale.

I profili non sono fatturabili e non influiscono sui prezzi.

Decidi chi riceve un profilo

Ciò che un profilo rappresenta dipende da come vendi Claude: una persona che usa il tuo prodotto, oppure un'azienda a cui rivendi l'accesso all'API. Questi due casi coprono la maggior parte delle piattaforme. Il campo access_type del profilo indica quale dei due si applica.

Cosa contiene un profilo e come lo usa Anthropic

Un profilo contiene solo ciò che invii riguardo al cliente finale, più l'eventuale stato del programma impostato da Anthropic. Non contiene il contenuto delle conversazioni. Anthropic usa i dettagli che invii per attribuire le richieste, per monitorare gli abusi, per l'applicazione della Politica di utilizzo e per consentire la candidatura e l'accesso ai programmi di accesso attendibile. Anthropic non verifica i dettagli.

Anthropic tratta i profili in conformità con l'Informativa sulla privacy.

Prima di iniziare

Crei e gestisci i profili in uno dei seguenti ambienti:

• Un'organizzazione sulla Claude API.
• Un'organizzazione su Claude Platform on AWS. Il principal chiamante necessita delle azioni IAM per i profili utente.
• Un deployment Microsoft Foundry ospitato su Anthropic, non uno ospitato su Azure. Non ti serve un'organizzazione sulla Claude API o su Claude Platform on AWS. Usa il tuo endpoint Foundry, con lo stesso URL di base e la stessa autenticazione che usi per l'inferenza.

Amazon Bedrock e Google Cloud non dispongono degli endpoint /v1/user_profiles. Se la tua inferenza viene eseguita lì, crea i tuoi profili in un'organizzazione sulla Claude API o su Claude Platform on AWS. Su Amazon Bedrock, i profili funzionano solo con Claude in Amazon Bedrock. Consulta Attribuisci le richieste su Amazon Bedrock e Google Cloud.

Mantieni il traffico che invii per i tuoi clienti finali in un'organizzazione e il tuo utilizzo interno in un'altra. I profili appartengono a un'organizzazione, non a un workspace, quindi workspace separati all'interno di un'unica organizzazione non sono sufficienti. Solo l'organizzazione per il traffico dei clienti finali necessita di profili utente. Per creare un'altra organizzazione sulla Claude API, consulta la sezione "How to create a new organization" di Creating and managing Workspaces in the Claude Console nel Centro assistenza di Claude.

Gli esempi chiamano la Claude API con una chiave API. Non ti serve una chiave Admin API. Su Claude Platform on AWS, usa il relativo URL di base e la relativa autenticazione.

Crea un profilo per ciascun cliente finale

Crea un profilo per ciascun cliente finale il cui traffico invii a Claude. Crealo una sola volta, nel tuo flusso di onboarding dei clienti. POST /v1/user_profiles non è idempotente, quindi ogni chiamata crea un nuovo profilo, anche quando reference_id corrisponde a uno esistente. Se hai già clienti finali senza profili, consulta le indicazioni sulla registrazione di una base clienti esistente più avanti in questa sezione.

L'esempio seguente registra un'azienda che acquista l'accesso all'API tramite un gateway, quindi imposta access_type su passthrough. Per un profilo application, ometti access_type e descrivi un singolo utente finale in name e external_user_details invece di un'azienda. Decidi chi riceve un profilo confronta i due tipi di accesso.

client = anthropic.Anthropic()

profile = client.user_profiles.create(
    name="Acme Analytics, Inc.",
    access_type="passthrough",
    external_user_details={"reference_id": "cust-8f2a1c", "country": "US"},
)

print(profile.id)

La risposta è il nuovo profilo:

{
  "type": "user_profile",
  "id": "uprof_011CZkZCu8hGbp5mYRQgUmz9",
  "name": "Acme Analytics, Inc.",
  "access_type": "passthrough",
  "external_user_details": {
    "reference_id": "cust-8f2a1c",
    "onboarded_at": null,
    "account_status": null,
    "entity_type": null,
    "country": "US",
    "name_hash": null,
    "email_hash": null
  },
  "metadata": {},
  "programs": {
    "cyber": null,
    "efs": null
  },
  "created_at": "2026-03-15T10:00:00Z",
  "updated_at": "2026-03-15T10:00:00Z"
}

Memorizza l'id nel record del cliente e fai in modo che le istanze del tuo servizio lo leggano da lì invece di creare un proprio profilo. Recuperi, aggiorni ed elimini un profilo tramite quell'id. Il campo programs è di sola lettura e l'attribuzione non lo utilizza. Contiene lo stato del cliente finale in ciascun programma gestito da Anthropic. Per il significato dei suoi valori, consulta quali programmi si applicano a un profilo.

Non esiste un limite al numero di profili in un'organizzazione, ma la creazione dei profili è soggetta a un "rate limit" (limite di velocità). Prima di registrare in blocco una base clienti esistente, contatta il tuo team account Anthropic.

Cosa comunicare ad Anthropic su un cliente finale

Ogni campo è facoltativo. Puoi inviare name, metadata e questi campi in external_user_details: entity_type, country, reference_id, onboarded_at, account_status, name_hash ed email_hash. Il riferimento Creare un profilo descrive ciascun campo, con il relativo tipo, formato e limite di lunghezza.

Segui queste regole quando imposti i campi:

• Valori sconosciuti: se non conosci un valore, omettilo invece di inviare un segnaposto. Puoi sostituire un valore in external_user_details in seguito, ma non puoi cancellarlo.
• Nomi delle aziende: per un profilo passthrough, invia la ragione sociale dell'azienda in name, se la conosci.
• Paese: in country, invia il paese del cliente finale, non il tuo.
• Il tuo ID: in reference_id, invia un tuo identificatore stabile per il cliente finale. Non deve essere univoco.
• Nomi e indirizzi email che non puoi condividere: ometti name e invia invece external_user_details.name_hash. Per l'indirizzo email, invia external_user_details.email_hash. Un profilo non ha un campo per l'indirizzo stesso.
• Hash: calcola tu stesso gli hash, con una funzione a tua scelta. Mostrano ad Anthropic quali dei tuoi profili condividono un nome o un indirizzo email. Usa la stessa funzione e la stessa normalizzazione di maiuscole/minuscole e spazi per ogni profilo, perché corrispondono solo i valori calcolati nello stesso modo.

Attribuisci ogni richiesta

Invia l'ID del profilo nell'header anthropic-user-profile-id in ogni richiesta che effettui per conto del cliente finale. Gli SDK e la CLI dispongono di un argomento che invia l'header per te: user_profile_id.

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello, Claude"}],
    user_profile_id="uprof_011CZkZCu8hGbp5mYRQgUmz9",
)

print(message)

L'header funziona allo stesso modo nelle richieste di conteggio dei token, Message Batches e compatibilità con l'SDK OpenAI. In un batch, si applica a ogni richiesta del batch.

La Claude API, Claude Platform on AWS e i deployment Microsoft Foundry ospitati su Anthropic verificano l'ID in ogni richiesta. Se l'ID è malformato o non appartiene all'organizzazione che invia la richiesta, l'API restituisce un 400 invalid_request_error. Per impostazione predefinita, queste piattaforme accettano un ID profilo solo nelle richieste provenienti dall'organizzazione che ha creato il profilo. Ciò significa che, se invii traffico sotto più di un'organizzazione, ad esempio una sulla Claude API e una su Claude Platform on AWS, una richiesta proveniente da un'organizzazione che non ha creato il profilo riceve lo stesso 400.

Message Batches costituisce l'eccezione: la creazione di un batch verifica solo il formato dell'ID. Se un ID ben formato non appartiene all'organizzazione che invia il batch, il batch viene comunque creato, e ciascuna richiesta al suo interno fallisce poi con un risultato errored che contiene lo stesso invalid_request_error.

Attribuisci le richieste su Amazon Bedrock e Google Cloud

Un ID profilo di uno qualsiasi dei due tipi di accesso funziona anche su Claude in Amazon Bedrock e su Google Cloud. Non funziona con l'integrazione Amazon Bedrock precedente che chiami con InvokeModel o Converse. Usi le credenziali della tua organizzazione Anthropic solo per creare e gestire i profili. L'inferenza continua a usare le tue credenziali AWS o Google Cloud esistenti.

Su Claude in Amazon Bedrock, inserisci l'ID al livello superiore del corpo della richiesta:

{
  "model": "anthropic.claude-opus-5-5",
  "max_tokens": 1024,
  "user_profile_id": "uprof_011CZkZCu8hGbp5mYRQgUmz9",
  "messages": [{ "role": "user", "content": "Hello, Claude" }]
}

Collega ciascun account AWS che invia richieste a Claude in Amazon Bedrock, e ciascun progetto Google Cloud che invia richieste su Google Cloud, all'organizzazione Anthropic che crea i tuoi profili:

1. Un amministratore o proprietario di quell'organizzazione avvia il collegamento nel Verification Portal all'indirizzo portal.anthropic.com, in Linked accounts.
2. Una persona in grado di gestire IAM nell'account AWS o nel progetto Google Cloud esegue un comando fornito dal portale.
3. L'amministratore o proprietario completa la verifica nel portale.

I programmi che si applicano a un profilo si applicano alle richieste di un account solo dopo che l'account è stato collegato e il portale lo mostra come Linked. Tali programmi includono quelli per cui l'organizzazione di un cliente finale è approvata dopo che il cliente finale collega il profilo a quell'organizzazione.

Claude in Amazon Bedrock e Google Cloud verificano il formato dell'ID ma non cercano il profilo. Rifiutano un ID malformato con un 400. Accettano qualsiasi ID ben formato, quindi una risposta riuscita non conferma che l'ID corrisponda a un profilo. Una richiesta senza ID viene elaborata senza attribuzione e, se attiva un'azione di applicazione, l'azione riguarda l'intera organizzazione.

Identifica i singoli utenti all'interno di un'azienda

Un profilo passthrough identifica un'azienda, non la persona che effettua la richiesta. Se una richiesta proviene da una persona identificabile, invia anche un identificatore per quella persona nel campo metadata.user_id della richiesta Messages. Si tratta dell'oggetto metadata della richiesta stessa, non del campo metadata del profilo. L'identificatore è facoltativo e aiuta Anthropic a rilevare gli abusi da parte di una singola persona.

Mantieni aggiornati i profili

Aggiorna un profilo quando cambiano i dettagli o lo stato dell'account del cliente finale, ed eliminalo quando il cliente chiude il proprio account o ti chiede di cancellare i suoi dati.

Aggiorna un profilo

POST /v1/user_profiles/{id} modifica solo i campi che invii. Ad esempio, usalo quando un'azienda cambia marchio o quando sospendi un account.

• name e access_type sostituiscono il valore memorizzato.
• Ogni campo che invii in external_user_details sostituisce il valore memorizzato. Non puoi cancellare un valore. L'API rifiuta null con un 400.
• metadata viene unito chiave per chiave. Una chiave che invii sovrascrive il valore memorizzato, una stringa vuota elimina la chiave e le chiavi che ometti restano invariate.

L'esempio seguente contrassegna l'account come sospeso e rimuove una chiave di metadati trial_cohort.

client = anthropic.Anthropic()

profile = client.user_profiles.update(
    "uprof_011CZkZCu8hGbp5mYRQgUmz9",
    external_user_details={"account_status": "suspended"},
    metadata={"trial_cohort": ""},
)

print(profile)

Elimina un profilo

DELETE /v1/user_profiles/{id} elimina definitivamente un profilo e tutto ciò che hai fornito per esso, inclusi name, external_user_details e metadata. Non rimuove i registri di trust and safety che Anthropic conserva su quell'ID profilo.

Elimina un profilo quando un cliente finale chiude il proprio account o ti chiede di cancellare i suoi dati. Prima di eliminare un profilo, smetti di inviarne l'ID nelle richieste di quel cliente finale. Se il cliente finale resta con te dopo una richiesta di cancellazione, crea un nuovo profilo e passa al suo ID. Poi elimina quello vecchio.

client = anthropic.Anthropic()

deleted = client.user_profiles.delete("uprof_011CZkZCu8hGbp5mYRQgUmz9")

print(deleted.id)

La risposta ripete l'ID con "type": "user_profile_deleted". Se un'eliminazione restituisce un errore del server, riprovala. Un 404 al nuovo tentativo significa che la prima eliminazione è andata a buon fine.

Dopo un'eliminazione, gli endpoint dei profili restituiscono un 404 per quell'ID. Per circa 10 minuti al massimo, le richieste di inferenza che riportano l'ID eliminato possono ancora avere esito positivo. Trascorso tale periodo, le piattaforme che verificano l'ID in ogni richiesta rifiutano la richiesta con un 400. Claude in Amazon Bedrock e Google Cloud non cercano i profili, quindi continuano ad accettarla.

Passaggi successivi

Il riferimento API riporta i campi, i tipi e i limiti di ciascun endpoint: Creare un profilo, Recuperare un profilo, Aggiornare un profilo ed Elencare i profili.

Se le approvazioni dei programmi di un cliente finale devono applicarsi quando usa Claude tramite la tua piattaforma, consulta Inviare a un cliente finale un link al Verification Portal.