Benutzerprofile für die Zuordnung zu Endkunden

„User profiles“ (Benutzerprofile, kurz „Profile“) teilen Anthropic mit, für welchen deiner Endkunden eine API-Anfrage bestimmt ist. Eine sicherheitsbezogene „enforcement action“ (Durchsetzungsmaßnahme), etwa eine vorübergehende Sperre oder eine Blockierung, kann dann auf einen einzelnen Endkunden statt auf deine gesamte Organisation angewendet werden. In diesem Fall ist der Rest deines Traffics nicht betroffen.

Wenn du eine Plattform oder ein Gateway betreibst oder API-Zugang weiterverkaufst, kommen die Anfragen, die du für deine Endkunden sendest, unter deiner Organisation an. Anthropic lässt automatisierte Sicherheitsklassifikatoren über den API-Traffic laufen. Ohne ein Profil in der Anfrage kann ein einzelner Endkunde eine Durchsetzungsmaßnahme auslösen, die für deine gesamte Organisation gilt.

Du registrierst jeden Endkunden einmal mit POST /v1/user_profiles und speicherst die zurückgegebene uprof_-ID. Anschließend sendest du diese ID im Header anthropic-user-profile-id bei jeder Anfrage, die du im Namen dieses Endkunden stellst.

Profile sind nicht kostenpflichtig und wirken sich nicht auf die Preise aus.

Entscheiden, wer ein Profil erhält

Wofür ein Profil steht, hängt davon ab, wie du Claude verkaufst: an eine Person, die dein Produkt nutzt, oder an ein Unternehmen, an das du API-Zugang weiterverkaufst. Diese beiden Fälle decken die meisten Plattformen ab. Das Feld access_type des Profils gibt an, welcher Fall zutrifft.

Was ein Profil enthält und wie Anthropic es verwendet

Ein Profil enthält nur das, was du über den Endkunden sendest, sowie einen etwaigen Programmstatus, den Anthropic festlegt. Es enthält keine Gesprächsinhalte. Anthropic verwendet die von dir gesendeten Angaben, um Anfragen zuzuordnen, um Missbrauch zu überwachen, zur Durchsetzung der Nutzungsrichtlinie und um die Bewerbung für und den Zugang zu Trusted-Access-Programmen zu ermöglichen. Anthropic überprüft die Angaben nicht.

Anthropic verarbeitet Profile gemäß der Datenschutzrichtlinie.

Bevor du beginnst

Du erstellst und verwaltest Profile in einer der folgenden Umgebungen:

• Einer Organisation auf der Claude API.
• Einer Organisation auf Claude Platform on AWS. Der aufrufende Principal benötigt die IAM-Aktionen für Benutzerprofile.
• Einem Microsoft Foundry-Deployment, das auf Anthropic gehostet wird, nicht auf Azure. Du benötigst keine Organisation auf der Claude API oder auf Claude Platform on AWS. Verwende deinen Foundry-Endpunkt mit derselben Basis-URL und Authentifizierung, die du für die Inferenz verwendest.

Amazon Bedrock und Google Cloud verfügen nicht über die /v1/user_profiles-Endpunkte. Wenn deine Inferenz dort läuft, erstelle deine Profile in einer Organisation auf der Claude API oder auf Claude Platform on AWS. Auf Amazon Bedrock funktionieren Profile nur mit Claude in Amazon Bedrock. Siehe Anfragen auf Amazon Bedrock und Google Cloud zuordnen.

Halte den Traffic, den du für deine Endkunden sendest, in einer Organisation und deine eigene interne Nutzung in einer anderen. Profile gehören zu einer Organisation, nicht zu einem Workspace, daher reichen separate Workspaces in einer Organisation nicht aus. Nur die Organisation für den Endkunden-Traffic benötigt Benutzerprofile. Wie du eine weitere Organisation auf der Claude API erstellst, erfährst du im Abschnitt „How to create a new organization“ von Creating and managing Workspaces in the Claude Console im Claude Help Center.

Die Beispiele rufen die Claude API mit einem API-Key auf. Du benötigst keinen Admin-API-Key. Verwende auf Claude Platform on AWS deren Basis-URL und Authentifizierung.

Ein Profil für jeden Endkunden erstellen

Erstelle ein Profil für jeden Endkunden, dessen Traffic du an Claude sendest. Erstelle es einmalig in deinem Onboarding-Ablauf für Kunden. POST /v1/user_profiles ist nicht idempotent, daher erstellt jeder Aufruf ein neues Profil, selbst wenn reference_id mit einem bestehenden übereinstimmt. Wenn du bereits Endkunden ohne Profile hast, beachte die Hinweise zur Registrierung eines bestehenden Kundenstamms weiter unten in diesem Abschnitt.

Das folgende Beispiel registriert ein Unternehmen, das API-Zugang über ein Gateway kauft, und setzt daher access_type auf passthrough. Lass bei einem application-Profil access_type weg und beschreibe in name und external_user_details einen einzelnen Endbenutzer statt eines Unternehmens. Entscheiden, wer ein Profil erhält vergleicht die beiden Zugriffstypen.

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)

Die Antwort ist das neue Profil:

{
  "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"
}

Speichere die id in deinem Kundendatensatz und lass deine Service-Instanzen sie von dort lesen, statt eigene Profile zu erstellen. Über diese id rufst du ein Profil ab, aktualisierst es und löschst es. Das Feld programs ist schreibgeschützt und wird für die Zuordnung nicht verwendet. Es enthält den Status des Endkunden in jedem Programm, das Anthropic betreibt. Was seine Werte bedeuten, erfährst du im Abschnitt dazu, welche Programme für ein Profil gelten.

Es gibt keine Obergrenze für die Anzahl der Profile in einer Organisation, aber die Profilerstellung unterliegt einem Ratenlimit. Bevor du einen bestehenden Kundenstamm in großen Mengen registrierst, wende dich an dein Anthropic-Account-Team.

Was du Anthropic über einen Endkunden mitteilen solltest

Jedes Feld ist optional. Du kannst name, metadata und diese Felder in external_user_details senden: entity_type, country, reference_id, onboarded_at, account_status, name_hash und email_hash. Die Referenz Ein Profil erstellen beschreibt jedes Feld mit seinem Typ, Format und seiner Längenbegrenzung.

Befolge diese Regeln, wenn du die Felder setzt:

• Unbekannte Werte: Wenn du einen Wert nicht kennst, lass ihn weg, statt einen Platzhalter zu senden. Du kannst einen Wert in external_user_details später ersetzen, aber nicht löschen.
• Unternehmensnamen: Sende bei einem passthrough-Profil den rechtlichen Namen des Unternehmens in name, wenn du ihn kennst.
• Land: Sende in country das Land des Endkunden, nicht deines.
• Deine eigene ID: Sende in reference_id deine eigene stabile Kennung für den Endkunden. Sie muss nicht eindeutig sein.
• Namen und E-Mail-Adressen, die du nicht teilen kannst: Lass name weg und sende stattdessen external_user_details.name_hash. Sende für die E-Mail-Adresse external_user_details.email_hash. Ein Profil hat kein Feld für die Adresse selbst.
• Hashes: Berechne die Hashes selbst mit einer Funktion deiner Wahl. Sie zeigen Anthropic, welche deiner Profile einen Namen oder eine E-Mail-Adresse gemeinsam haben. Verwende für jedes Profil dieselbe Funktion und dieselbe Normalisierung von Groß-/Kleinschreibung und Leerzeichen, denn nur auf dieselbe Weise berechnete Werte stimmen überein.

Jede Anfrage zuordnen

Sende die Profil-ID im Header anthropic-user-profile-id bei jeder Anfrage, die du im Namen des Endkunden stellst. Die SDKs und die CLI haben ein Argument, das den Header für dich sendet: 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)

Der Header funktioniert auf dieselbe Weise bei Anfragen für Token-Zählung, Message Batches und OpenAI-SDK-Kompatibilität. Bei einem Batch gilt er für jede Anfrage im Batch.

Die Claude API, Claude Platform on AWS und auf Anthropic gehostete Microsoft Foundry-Deployments prüfen die ID bei jeder Anfrage. Wenn die ID fehlerhaft ist oder nicht zu der Organisation gehört, die die Anfrage sendet, gibt die API einen 400 invalid_request_error zurück. Standardmäßig akzeptieren diese Plattformen eine Profil-ID nur bei Anfragen von der Organisation, die das Profil erstellt hat. Das bedeutet: Wenn du Traffic unter mehr als einer Organisation sendest, zum Beispiel einer auf der Claude API und einer auf Claude Platform on AWS, erhält eine Anfrage von einer Organisation, die das Profil nicht erstellt hat, denselben 400.

Message Batches ist die Ausnahme: Beim Erstellen eines Batches wird nur das Format der ID geprüft. Wenn eine korrekt formatierte ID nicht zu der Organisation gehört, die den Batch sendet, wird der Batch trotzdem erstellt, und jede Anfrage darin schlägt dann mit einem errored-Ergebnis fehl, das denselben invalid_request_error enthält.

Anfragen auf Amazon Bedrock und Google Cloud zuordnen

Eine Profil-ID beider Zugriffstypen funktioniert auch auf Claude in Amazon Bedrock und auf Google Cloud. Sie funktioniert nicht mit der früheren Amazon Bedrock-Integration, die du mit InvokeModel oder Converse aufrufst. Die Anmeldedaten deiner Anthropic-Organisation verwendest du nur zum Erstellen und Verwalten von Profilen. Die Inferenz läuft weiterhin über deine bestehenden AWS- oder Google Cloud-Anmeldedaten.

Setze die ID bei Claude in Amazon Bedrock auf die oberste Ebene des Request-Bodys:

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

Verknüpfe jedes AWS-Konto, das Anfragen an Claude in Amazon Bedrock sendet, und jedes Google Cloud-Projekt, das Anfragen auf Google Cloud sendet, mit der Anthropic-Organisation, die deine Profile erstellt:

1. Ein Admin oder Owner dieser Organisation startet die Verknüpfung im Verification Portal unter portal.anthropic.com im Bereich Linked accounts.
2. Jemand, der IAM im AWS-Konto oder Google Cloud-Projekt verwalten kann, führt einen Befehl aus, den das Portal bereitstellt.
3. Der Admin oder Owner schließt die Verifizierung im Portal ab.

Programme, die für ein Profil gelten, gelten für die Anfragen eines Kontos erst, nachdem das Konto verknüpft ist und das Portal es als Linked anzeigt. Zu diesen Programmen gehören auch diejenigen, für die die Organisation eines Endkunden zugelassen ist, nachdem der Endkunde das Profil mit dieser Organisation verknüpft hat.

Claude in Amazon Bedrock und Google Cloud prüfen das Format der ID, schlagen das Profil aber nicht nach. Sie lehnen eine fehlerhafte ID mit einem 400 ab. Sie akzeptieren jede korrekt formatierte ID, daher bestätigt eine erfolgreiche Antwort nicht, dass die ID zu einem Profil passt. Eine Anfrage ohne ID wird ohne Zuordnung verarbeitet, und wenn sie eine Durchsetzungsmaßnahme auslöst, gilt die Maßnahme für deine gesamte Organisation.

Einzelne Benutzer innerhalb eines Unternehmens identifizieren

Ein passthrough-Profil identifiziert ein Unternehmen, nicht die Person, die die Anfrage stellt. Wenn eine Anfrage von einer identifizierbaren Person stammt, sende zusätzlich eine Kennung für diese Person im Feld metadata.user_id der Messages-Anfrage. Dies ist das eigene metadata-Objekt der Anfrage, nicht das metadata-Feld des Profils. Die Kennung ist optional und hilft Anthropic, Missbrauch durch eine einzelne Person zu erkennen.

Profile aktuell halten

Aktualisiere ein Profil, wenn sich die Angaben oder der Kontostatus des Endkunden ändern, und lösche es, wenn er sein Konto schließt oder dich bittet, seine Daten zu löschen.

Ein Profil aktualisieren

POST /v1/user_profiles/{id} ändert nur die Felder, die du sendest. Verwende es zum Beispiel, wenn ein Unternehmen sich umbenennt oder du ein Konto sperrst.

• name und access_type ersetzen den gespeicherten Wert.
• Jedes Feld, das du in external_user_details sendest, ersetzt den gespeicherten Wert. Du kannst einen Wert nicht löschen. Die API lehnt null mit einem 400 ab.
• metadata wird Schlüssel für Schlüssel zusammengeführt. Ein Schlüssel, den du sendest, überschreibt den gespeicherten Wert, ein leerer String löscht den Schlüssel, und Schlüssel, die du weglässt, bleiben unverändert.

Das folgende Beispiel markiert das Konto als gesperrt und entfernt einen trial_cohort-Metadatenschlüssel.

client = anthropic.Anthropic()

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

print(profile)

Ein Profil löschen

DELETE /v1/user_profiles/{id} löscht ein Profil und alles, was du dafür angegeben hast, dauerhaft, einschließlich name, external_user_details und metadata. Die Trust-and-Safety-Aufzeichnungen, die Anthropic zu dieser Profil-ID aufbewahrt, werden dadurch nicht entfernt.

Lösche ein Profil, wenn ein Endkunde sein Konto schließt oder dich bittet, seine Daten zu löschen. Bevor du ein Profil löschst, sende seine ID nicht mehr bei den Anfragen dieses Endkunden. Wenn der Endkunde nach einer Löschanfrage bei dir bleibt, erstelle ein neues Profil und wechsle zu dessen ID. Lösche dann das alte.

client = anthropic.Anthropic()

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

print(deleted.id)

Die Antwort wiederholt die ID mit "type": "user_profile_deleted". Wenn ein Löschvorgang einen Serverfehler zurückgibt, wiederhole ihn. Ein 404 bei der Wiederholung bedeutet, dass der erste Löschvorgang erfolgreich war.

Nach einem Löschvorgang geben die Profil-Endpunkte für diese ID einen 404 zurück. Bis zu etwa 10 Minuten lang können Inferenzanfragen, die die gelöschte ID enthalten, noch erfolgreich sein. Danach lehnen die Plattformen, die die ID bei jeder Anfrage prüfen, die Anfrage mit einem 400 ab. Claude in Amazon Bedrock und Google Cloud schlagen Profile nicht nach und akzeptieren sie daher weiterhin.

Nächste Schritte

Die API-Referenz enthält die Felder, Typen und Grenzen jedes Endpunkts: Ein Profil erstellen, Ein Profil abrufen, Ein Profil aktualisieren und Profile auflisten.

Wenn die Programmzulassungen eines Endkunden gelten sollen, wenn er Claude über deine Plattform nutzt, siehe Einem Endkunden einen Link zum Verification Portal senden.