Linked billing
Lass deine Kunden ihre Claude Platform-Organisation per OAuth mit deiner App verknüpfen und rechne die Claude-Nutzung über die Organisation des Kunden ab.
Mit Linked billing können deine Kunden die Claude-Nutzung in deiner App über ihre eigene Claude-Organisation bezahlen. Ein Kunde verknüpft seine Claude-Organisation einmalig mit deiner App. Die API nennt diese Verknüpfung eine „connection“ (Verbindung). Nachdem der Kunde verknüpft hat, entscheidest du bei jeder Claude API-Anfrage, ob der Kunde oder du bezahlst. Der Kunde kann die Verknüpfung mit deiner App jederzeit aufheben. Wenn eine Anfrage, die du für den Kunden markierst, ihm nicht in Rechnung gestellt werden kann, lehnt die Claude API sie ab, anstatt sie dir in Rechnung zu stellen.
Dieser Leitfaden richtet sich an Entwickler, deren App-Nutzer hauptsächlich Kunden der Claude Platform sind. Du fügst deiner App eine Schaltfläche „Link your Claude organization“ hinzu. Dein Nutzer klickt darauf, meldet sich bei Claude an und genehmigt, dass deine App seiner Claude-Organisation die Claude API-Anfragen in Rechnung stellt, die du auf Anweisung des Kunden stellst. Deine App fügt dann den Anfragen, für die der Kunde bezahlt, ein billing_policy-Feld hinzu.
Berechtigte Kunden und Endpunkte
Berechtigte Kunden: Ein Kunde kann auf diese Weise nur abgerechnet werden, wenn seine Claude Platform-Organisation Anthropic direkt für ihre API-Nutzung bezahlt. Sowohl Prepaid-Guthaben als auch Abrechnung per Rechnung zählen dazu. Organisationen, die über einen Cloud-Marketplace (AWS, Google Cloud oder Azure) abgerechnet werden, können nicht über diese Integration abgerechnet werden. Dasselbe gilt für Organisationen, die nur einen Claude-Abonnementplan haben. Anfragen für sie werden mit 403 user_profile_not_billable abgelehnt.
Anfragen laufen in deiner Organisation, daher gelten deine Ratenlimits, dein Modellzugriff, deine Service-Stufe, deine Datenaufbewahrung und deine Verschlüsselungsschlüssel. Die eigenen Datenvereinbarungen deines Kunden gelten für diese Anfragen nicht, einschließlich „zero data retention“ (Null-Datenaufbewahrung), oder ZDR, eines „business associate agreement“ (Geschäftspartnervereinbarung), oder BAA, und „customer-managed encryption keys“ (kundenverwaltete Verschlüsselungsschlüssel), oder CMEK. Verknüpfe keine Kunden, die für diese Nutzung eine Abdeckung nach HIPAA, FERPA oder CMEK benötigen.
Unterstützte Endpunkte: billing_policy wird unterstützt auf:
/v1/messages- Bekannte Einschränkung: Eine Anfrage, die deinem Kunden in Rechnung gestellt wird (
bill_to: "user_profile"), kann keine kostenpflichtigen Code-Ausführungsfunktionen verwenden (die API gibt einen 400 zurück). Sende diese Anfragen daher mitbill_to: "self"oder ohnebilling_policy.
- Bekannte Einschränkung: Eine Anfrage, die deinem Kunden in Rechnung gestellt wird (
/v1/chat/completions/v1/messages/count_tokensakzeptiert das Feldbilling_policyund ignoriert es, sodass du Token genau für den Body zählen kannst, den du gleich senden wirst.
Message Batches (/v1/messages/batches) unterstützt es derzeit nicht, deinem Kunden Anfragen in Rechnung zu stellen. Sende die Anfragen in einem Batch mit bill_to: "self" oder ohne billing_policy, dann werden sie wie gewohnt dir in Rechnung gestellt. Eine Anfrage in einem Batch, die bill_to: "user_profile" setzt, wird abgelehnt: Ihr Ergebnis ist errored mit einem invalid_request_error, weder dir noch deinem Kunden wird sie in Rechnung gestellt, und die anderen Anfragen des Batches werden wie gewohnt ausgeführt.
Wenn du Unterstützung für einen anderen Endpunkt anfragen möchtest, wende dich an dein Anthropic-Account-Team.
Welches Guthaben bezahlen kann
Nicht jedes Guthaben kann eine Anfrage bezahlen, die eine Plattform einem Kunden in Rechnung stellt. Was bezahlen kann, hängt von der Organisation ab, der die Anfrage in Rechnung gestellt wird: dem Kunden, wenn du einem Kunden etwas in Rechnung stellst, oder deiner Organisation, wenn eine Plattform dir etwas in Rechnung stellt.
Guthaben, das in der Claude Console für diese Organisation gekauft wurde, kann diese Anfragen bezahlen. Wenn diese Organisation per Rechnung abgerechnet wird, erhält sie für diese Anfragen eine Rechnung.
Manches Aktionsguthaben von Anthropic kann diese Anfragen nicht bezahlen. Dazu gehört das monatliche API-Guthaben, das in den Plänen Claude Max, Ultra und Team enthalten ist. Guthaben aus den Partner-, VC- und Startup-Programmen von Anthropic ist nicht dafür zugelassen, diese Anfragen zu bezahlen.
Wenn nichts auf dem Konto dieser Organisation eine Anfrage bezahlen kann, kann die Claude API sie mit einem 402 ablehnen. Die Antwort gibt nicht an, ob fehlendes Guthaben oder ein Ausgabenlimit die Ablehnung verursacht hat. Siehe Erwartete Fehler.
Einrichtungsprozess
Diese drei Schritte führst du einmalig aus. Sie registrieren deine App bei Anthropic. Danach erklärt Welches Nutzerprofil verknüpft wird eine Regel, die du kennen musst, bevor du Nutzerprofile erstellst.
Schritt 1: Die App erstellen
Erstelle die OAuth-App in der Claude Console. Sie ist die Registrierung, die dein Produkt gegenüber Anthropic identifiziert: Sie verknüpft deine Redirect-URI mit einer Client-ID, und ihr Name ist das, was dein Nutzer auf der Genehmigungsseite sieht.
Ein Mitglied deiner Organisation mit der Rolle Admin öffnet die Seite OAuth apps in der Console und klickt auf Create. Gib den Namen deiner App und die Redirect-URI ein (die Adresse in deiner App, zu der der Browser nach der Genehmigung zurückkehrt). Wähle unter What the app can do die Option Bill and link to organizations.
Die Seite der neuen App öffnet sich. Kopiere die Client-ID, die die Console für die App anzeigt. Deine App sendet sie in Schritt 5, wenn sie eine Genehmigungsseite anfordert, in Schritt 6, wenn sie den Browser weiterleitet, und in Schritt 8, wenn sie den Code austauscht, damit Anthropic weiß, welche App anfragt. Die Client-ID ist öffentlich. Lege auf dem Tab Appearance den Namen, die Homepage und die Logo-URL deiner App fest.
Auf dem Tab Settings zeigt Who can link bei einer neuen App, die im Testmodus startet, Test users only an. Nachdem du deine App veröffentlicht hast und sie live ist, zeigt die Einstellung Any Claude user an.
Schritt 2: Client-Authentifizierung einrichten
Lege fest, wie dein Back-End gegenüber auth.claude.com nachweist, dass seine Anfragen von deiner App stammen. Dies ersetzt ein Client-Secret: Anthropic stellt für OAuth-Apps keine Client-Secrets aus.
Wähle auf dem Tab Client authentication der App deinen Identity provider aus (den Aussteller, der die Token deines Back-Ends signiert). Um einen hinzuzufügen, klicke auf Register a new issuer. Lege dann ein Subject pattern oder Claim-Bedingungen unter Advanced match options fest, denen diese Token entsprechen müssen. Nach dem Speichern zeigt der Tab die erwartete Audience an. Der aud-Claim deiner Client-Assertion muss genau diesem Wert entsprechen.
Schritt 3: Die Identität deines Back-Ends einrichten
Dein Back-End benötigt eine eigene Identität, um die Claude API aufzurufen. Erstelle zwei Dinge:
- Ein Service-Konto. Dies ist ein nicht-menschliches Konto in deiner Claude-Organisation. Dein Back-End authentifiziert sich als dieses Konto, wenn es die Claude API aufruft.
- Eine zweite Föderationsregel. Wie die Regel für die Client-Authentifizierung der App in Schritt 2 ermöglicht sie deinem Back-End, sich mit Token deines eigenen Identitätsanbieters zu authentifizieren.
Um sie in der Claude Console einzurichten, folge dem Leitfaden Workload Identity Federation.
Wähle dann auf dem Tab Client authentication der App dieses Service-Konto als Operator-Service-Konto der App aus. Nur dieses Service-Konto ist berechtigt, Inferenzanfragen zu senden und die Abrechnung den verknüpften Nutzerprofilen zuzuordnen. Ein Service-Konto kann nur Operator einer einzigen OAuth-App sein.
Standardmäßig kann jede als dieses Service-Konto authentifizierte Anfrage jedem verknüpften Kunden etwas in Rechnung stellen, indem sie den Nutzerprofil-Header und bill_to in der Messages API setzt. Wie du Authentifizierungstoken erhältst, die auf eine bestimmte Verbindung beschränkt sind, erfährst du unter OAuth-Token für jede Verbindung. Bevor du Kunden verknüpfst, lege einen Workspace für deine App fest. Schritt 8 gibt für jeden Kunden ein solches Token zurück und erfordert, dass die App einen Standard-Workspace in deiner Organisation festlegt, in dem die Inferenz ausgeführt wird. Wenn du Refresh-Token für jede Verbindung möchtest, aktiviere außerdem Offline access für deine App. Fordere dann im Autorisierungsablauf offline_access an, in Schritt 5, bevor du Kunden verknüpfst.
Welches Nutzerprofil verknüpft wird
Ein „user profile“ (Nutzerprofil) ist ein Datensatz in deiner eigenen Claude-Organisation, der einen deiner Kunden repräsentiert. Jede Anfrage, die dem Kunden in Rechnung gestellt wird, enthält die ID des Profils, damit Anthropic weiß, welchem Kunden sie in Rechnung gestellt werden soll. Was Profile darüber hinaus leisten, erfährst du unter Benutzerprofile für die Zuordnung zu Endkunden.
Lege fest, welches Nutzerprofil für jeden Kunden steht, bevor du deinen ersten Kunden verknüpfst. Innerhalb einer App sind Verbindungen eins zu eins:
- Die Claude-Organisation eines Kunden kann nur mit einem deiner Nutzerprofile verknüpft werden.
- Ein Nutzerprofil kann nur mit einer Claude-Organisation verknüpft werden.
Die Claude-Organisation des Kunden ist diejenige, die der Nutzer auswählt, wenn er deine App genehmigt. Wie die Teams eines Kunden Claude-Organisationen verwenden, erfährst du vom Kunden. So wendest du die Eins-zu-eins-Regel auf deine Kundendatensätze an:
- Mehrere Teams eines Kunden teilen sich eine Claude-Organisation: Verwende ein Nutzerprofil für alle Teams.
- Jedes Team hat seine eigene Claude-Organisation: Erstelle ein Nutzerprofil für jede Organisation.
Jedes aktive Nutzerprofil in deiner Organisation kann verknüpft werden, solange die Eins-zu-eins-Regel eingehalten wird. Das Verknüpfen ändert weder das Profil noch seine ID oder seinen Nutzungsverlauf. Wenn du ein zweites Nutzerprofil mit einer Claude-Organisation verknüpfst, die bereits verknüpft ist, wird die Genehmigung abgelehnt: siehe user_profile_already_linked.
Ein Nutzerprofil für jede Person
Möglicherweise hast du bereits ein Nutzerprofil für jede Person, die dein Produkt verwendet. Mehrere dieser Personen arbeiten möglicherweise für denselben Kunden. In diesem Fall empfiehlt Anthropic, ein weiteres Nutzerprofil für die Claude-Organisation des Kunden zu erstellen und dieses Profil zu verknüpfen.
Welche Profil-ID du sendest, hängt davon ab, wer für die Anfrage bezahlt:
- Anfragen, die du dem Kunden in Rechnung stellst: Sende die ID des Profils des Kunden. Um zusätzlich die Person bei einer
/v1/messages-Anfrage zu identifizieren, setzemetadata.user_idVorschau mit Links zur API-Referenz verfügbar – drücke Tab, bis der Fokus in die Karte wechselt, und Escape, um zurückzukehren. auf eine Kennung für diese Person. Diese Kennung ist optional und hilft Anthropic, Missbrauch durch eine einzelne Person zu erkennen. Verwende einen undurchsichtigen Wert, keinen Namen, keine E-Mail-Adresse und keine Telefonnummer. - Anfragen, die du bezahlst: Du kannst weiterhin die eigene Profil-ID der Person senden.
Jeden Kunden verknüpfen
Die Schritte 4 bis 8 führst du für jeden Kunden aus, der seine Organisation verknüpft. Die folgenden Python-Code-Snippets benötigen das Anthropic SDK und einige Standard-Importe; siehe Initialisierung der Code-Snippets. Die Beispiele in anderen Sprachen und die CLI beziehen ihre Anmeldedaten aus der Umgebung. Stelle sicher, dass ANTHROPIC_API_KEY nicht gesetzt ist, da sich deine App mit Workload Identity Federation authentifizieren muss.
Füge eine Schaltfläche „Link your Claude organization“ dort hinzu, wo deine Kunden in deinem Produkt Abrechnung oder Integrationen verwalten (HTML, Farben und Logo der Schaltfläche findest du unter Branding-Beispiele). Teile ihnen mit, dass sie zum Verknüpfen die Rolle Admin oder Billing in ihrer Claude-Organisation haben müssen.
Wenn du die Schritte zuerst selbst durchlaufen möchtest, siehe Als Kunde testen.
Schritt 4: Ein Nutzerprofil für den Kunden erstellen
Erstelle ein Nutzerprofil für die Claude-Organisation jedes Kunden und speichere die ID des Profils im Datensatz des Kunden in deinem Produkt.
Wenn du für die Claude-Organisation dieses Kunden bereits ein Nutzerprofil hast, überspringe diesen Schritt und verwende die ID dieses Profils. Wie du entscheidest, welches Profil das ist, erfährst du unter Welches Nutzerprofil verknüpft wird.
def create_user_profile(name: str, customer_id: str) -> str:
profile = client.user_profiles.create(
name=name,
external_user_details={"reference_id": customer_id},
)
return profile.id # "uprof_..."
user_profile_id = create_user_profile("Example Customer Inc.", "your-customer-id-123")Wenn deine Organisation API-Zugang weiterverkauft, sende beim Erstellen dieses Profils zusätzlich "access_type": "passthrough". Diese Beispiele lassen access_type weg, wodurch ein application-Profil erstellt wird. Zu den beiden Typen siehe Entscheiden, wer ein Profil erhält.
Die Antwort enthält die id des Profils, zum Beispiel uprof_01HV9Z.
Schritt 5: Eine Pushed-Authorization-Request-URL erstellen
Erstelle eine „pushed authorization request“ (übermittelte Autorisierungsanfrage), die auf das Nutzerprofil des Kunden aus Schritt 4 verweist. Die Antwort liefert dir eine request_uri. Im nächsten Schritt verwendest du sie, um deinen Nutzer zur Genehmigungsseite weiterzuleiten.
Bevor es die Anfrage sendet, erzeugt dein Back-End zwei Zufallswerte und speichert sie zur Browser-Sitzung und zum Kundendatensatz. Es verwendet beide erneut in Schritt 8:
- Einen
state-Wert, mit dem du prüfen kannst, dass der Browser, der zu deiner App zurückkehrt, derjenige ist, der diese Anfrage gestartet hat. - Einen PKCE-Code-Verifier, ein Geheimnis, das nur dein Back-End kennt. Die Anfrage enthält einen Hash davon (die Code-Challenge), und Schritt 8 sendet den Verifier selbst, sodass nur dein Back-End den zurückgegebenen Code verwenden kann.
def push_authorization_request(user_profile_id: str) -> dict:
state = secrets.token_urlsafe(32)
code_verifier = secrets.token_urlsafe(64)
code_challenge = create_s256_code_challenge(code_verifier)
response = httpx.post(
f"{AUTH}/v1/oauth/par",
json={
"response_type": "code",
"client_id": CLIENT_ID,
"redirect_uri": REDIRECT_URI,
"scope": "billing:attribution",
"connection_type": "organization_shared",
"connection_auth_target": "platform",
"user_profile_id": user_profile_id,
"state": state,
"code_challenge": code_challenge,
"code_challenge_method": "S256",
"client_assertion_type": JWT_BEARER,
"client_assertion": client_assertion(),
},
)
response.raise_for_status() # on an error, do not redirect the browser
return {
"state": state,
"code_verifier": code_verifier,
"request_uri": response.json()["request_uri"], # valid for 600 seconds
"user_profile_id": user_profile_id,
}
par = push_authorization_request(user_profile_id)auth.claude.com antwortet mit HTTP 201, einer request_uri und expires_in von 600 Sekunden. Die request_uri identifiziert die Genehmigungsseite für diese Anfrage. Der scope muss genau billing:attribution oder billing:attribution offline_access lauten. Details findest du unter Scopes für eine Abrechnungsverbindung. Die Beispiele senden billing:attribution. Wenn deine App diesen Scope nicht hat, füge ihn auf dem Tab Permissions der App unter Billing hinzu.
connection_auth_target muss platform sein: Inferenzanfragen laufen in deiner eigenen Organisation und authentifizieren sich als das Operator-Service-Konto, können aber dem Kunden in Rechnung gestellt werden.
user_profile_id muss die ID eines aktiven Nutzerprofils in deiner Organisation sein. Wenn der Pushed Authorization Request fehlschlägt, gibt auth.claude.com eine OAuth-Fehlerantwort an dein Back-End zurück. Leite den Browser in diesem Fall nicht weiter.
Schritt 6: Deinen Nutzer zur Claude-Genehmigungsseite schicken
Zeige deinem Nutzer zuerst, welches Konto in deinem Produkt er verknüpft, und bitte ihn, das Claude-Konto zu prüfen, das die Genehmigungsseite anzeigt. Die Seite zeigt an, welches Claude-Konto angemeldet ist, und lässt den Nutzer zu einem anderen wechseln. Die Genehmigungsseite bietet nur die Organisationen des Claude-Kontos an, das im Browser angemeldet ist, daher kann das falsche Konto die falsche Organisation verknüpfen. Die Organisation, die der Nutzer verknüpft, bezahlt.
Leite deinen Nutzer dann zum Autorisierungsendpunkt weiter, der eine Genehmigungsseite anzeigt. Füge nur deine client_id und die request_uri aus Schritt 5 hinzu.
def authorize_url(par: dict) -> str:
query = urlencode({"client_id": CLIENT_ID, "request_uri": par["request_uri"]})
return f"{AUTH}/oauth/authorize?{query}"
redirect_to = authorize_url(par) # answer the click with a 302 to this URLSchritt 7: Der Nutzer erteilt die Genehmigung
Deine App tut in diesem Schritt nichts. Der Nutzer durchläuft diese Schritte auf auth.claude.com:
- Der Nutzer meldet sich bei Claude an, es sei denn, der Browser ist bereits angemeldet.
- Die Genehmigungsseite zeigt die folgenden Bildschirme, jeweils mit dem Namen deiner App. Was der Nutzer auf jedem Bildschirm tut, erfährst du unter Verknüpfen.
- Select an organization, nur wenn der Nutzer eine Auswahl an Organisationen hat.
- How billing works.
- Set a monthly spend limit.
- Ein letzter Bildschirm mit der Schaltfläche Link and authorize.
- Wenn der Nutzer auf Link and authorize klickt, schickt
auth.claude.comden Browser zurück zu deiner App. Die Genehmigungsseite zeigt keinen Bestätigungsbildschirm.
Wenn der Nutzer abbricht oder die Genehmigung nicht erteilen kann, wird keine Verbindung hergestellt: siehe Wenn das Verknüpfen nicht abgeschlossen wird.
Schritt 8: Den Callback verarbeiten und die Verbindung speichern
Nach der Genehmigung schickt auth.claude.com den Browser mit einem einmaligen Code und deinem state-Wert zurück zu deiner Redirect-URI. Diese Anfrage an deine Redirect-URI wird „callback“ (Rückruf) genannt. Dein Back-End tauscht den Code gegen eine Verbindungs-ID aus und speichert sie im Datensatz des Kunden. Damit ist die Verbindung hergestellt. Der Callback kann einen error-Parameter und keinen Code enthalten. Dann wurde keine Verbindung hergestellt: siehe Wenn das Verknüpfen nicht abgeschlossen wird.
Prüfe, ob der state mit dem in Schritt 5 gespeicherten Wert übereinstimmt, und tausche den Code dann sofort von deinem Back-End aus, zusammen mit dem PKCE-Code-Verifier. Der Code ist nur einmal verwendbar und läuft nach 5 Minuten ab.
def handle_callback(par: dict, params: dict) -> str:
if not secrets.compare_digest(
params.get("state", "").encode(), par["state"].encode()
):
raise ValueError("state does not match")
if "error" in params: # for example access_denied
raise PermissionError(params["error"])
code = params["code"] # single-use, expires after 5 minutes
response = httpx.post(
f"{AUTH}/v1/oauth/token",
json={
"grant_type": "authorization_code",
"code": code,
"code_verifier": par["code_verifier"],
"redirect_uri": REDIRECT_URI,
"client_id": CLIENT_ID,
"client_assertion_type": JWT_BEARER,
"client_assertion": client_assertion(),
},
timeout=10, # a response that times out loses the tokens in it
)
response.raise_for_status()
tokens = response.json()
# Um die Tokens der Verbindung zu nutzen, speichere tokens["access_token"], dessen Ablauf-
# zeit (aus tokens["expires_in"]) und, mit offline_access,
# tokens["refresh_token"] hier als Secrets: Der Code kann nicht erneut eingetauscht werden.
# "ocon_..."; speichere es im Kundendatensatz
return tokens["connection_id"]Die Antwort enthält die Verbindungs-ID und das Access-Token der Verbindung, mit dem du dich authentifizieren und dem genehmigenden Kunden Anfragen in Rechnung stellen kannst. Wenn der Kunde offline_access genehmigt hat, enthält die Antwort außerdem ein Refresh-Token. Speichere connection_id und die Token jetzt: Der Austausch gibt die Token nur einmal zurück. Die Token speichern beschreibt die Antwort.
Die Beispiele auf dieser Seite, die die Claude API aufrufen, authentifizieren sich als das Service-Konto aus Schritt 3, nicht mit einem Token aus dieser Antwort. Claude mit dem Access-Token einer Verbindung aufrufen erklärt, wie du stattdessen das Token verwendest.
Die Antwort gibt nicht an, welche Claude-Organisation der Nutzer verknüpft hat.
Eine hergestellte Verbindung garantiert nicht, dass Anthropic dem Kunden etwas in Rechnung stellen kann. Zum Beispiel gehört die Organisation des Kunden möglicherweise nicht zu den berechtigten Kunden. Unter Aufrufe an Claude anpassen und Erwartete Fehler erfährst du, wie die Claude API dies prüft. Formuliere deine Erfolgsmeldung wegen dieser Prüfung als „verknüpft“ und nicht als „Abrechnung aktiv“.
Wenn der Austausch mit unauthorized_client abgelehnt wird, siehe Der Code-Austausch gibt unauthorized_client zurück.
Als Kunde testen
Um zu prüfen, ob das Verknüpfen funktioniert, verknüpfe eine eigene Organisation. Dafür brauchst du zuerst Folgendes:
- Eine zweite Claude-Organisation von dir, die als Kunde dient. Du kannst deine App nicht mit der Organisation verknüpfen, der sie gehört. Die Genehmigungsseite bietet diese Organisation nicht an. Die zweite Organisation muss zu den berechtigten Kunden gehören.
- Eine Person mit der Rolle Admin oder Billing in dieser Organisation, die die Verknüpfung genehmigt.
- Solange deine App nicht live ist, muss diese Person auf der Liste Test users deiner App stehen. Die Liste befindet sich auf dem Tab Settings der App unter Who can link. Füge die Person über die E-Mail-Adresse ihres Claude-Kontos hinzu und klicke auf Save changes. Solange sich deine App im Test befindet nennt die Ausgabenobergrenze, die gilt. Wenn du jemanden von der Liste entfernst, werden die Verknüpfungen beendet, die diese Person genehmigt hat.
Führe dann die Schritte 4 bis 8 aus und lass diese Person in Schritt 7 die Genehmigung erteilen. Wenn die Verknüpfung hergestellt ist, wird das Nutzerprofil auf deiner Seite User profiles in der Console als Linked angezeigt.
Wenn das Verknüpfen nicht abgeschlossen wird
Wenn der Nutzer die Genehmigung nicht abschließt oder auth.claude.com sie ablehnt, wird keine Verbindung hergestellt. Diese Einträge behandeln die Ergebnisse, die für Linked billing spezifisch sind. Alle anderen Fehler findest du unter Fehler in der OAuth-Referenz.
Deine Redirect-URI erhält error=access_denied
Die Anfrage enthält außerdem deinen state-Wert. Deine Redirect-URI erhält diesen Fehler beispielsweise in diesen Fällen:
- Der Nutzer klickt auf einem der Genehmigungsbildschirme auf Cancel.
- Die Genehmigungsseite kann dem Nutzer keine Organisation anbieten, und der Nutzer klickt auf die Schaltfläche, die zu deiner App zurückführt. Zum Beispiel:
- Der Nutzer hat in keiner Claude Platform-Organisation die Rolle Admin oder Billing.
- Die einzige Organisation des Nutzers ist diejenige, der deine App gehört. Siehe Als Kunde testen.
- Das Nutzerprofil ist bereits mit einer anderen Claude-Organisation verknüpft, und der Nutzer hat in dieser Organisation nicht die Rolle Admin oder Billing.
- Solange deine App nicht live ist, steht der Nutzer nicht auf ihrer Liste Test users.
In jedem Fall dieser Liste lautet die error_description the user declined the request, sie lässt also keine Unterscheidung zwischen ihnen zu.
Eine weitere Ursache liegt in den Einstellungen deiner App. Wenn deine App live ist und Who can link nur deine Organisation anzeigt, kann niemand außerhalb deiner Organisation die App verknüpfen. Wähle Any Claude user aus und klicke auf Save changes.
Teile dem Nutzer mit, dass das Verknüpfen nicht abgeschlossen wurde, und gehe nicht davon aus, dass er abgelehnt hat. Bitte ihn, zu prüfen, mit welchem Claude-Konto er sich angemeldet hat und welche Rolle er in der Organisation hat, die er verknüpfen möchte. Eine request_uri kann nicht erneut verwendet werden, nachdem der Nutzer abbricht oder zurückkehrt. Damit der Nutzer es erneut versuchen kann, beginne daher erneut bei Schritt 5.
Deine App erhält user_profile_already_linked
Die Claude-Organisation des Kunden ist bereits über ein anderes deiner Nutzerprofile mit deiner App verknüpft. auth.claude.com bittet den Nutzer, sich an dich zu wenden. Wenn der Nutzer zu deiner App zurückkehrt, erhält deine Redirect-URI error=user_profile_already_linked und deinen state-Wert. Der Token-Endpunkt kann diesen Fehler auch zurückgeben, wenn du den Code in Schritt 8 austauschst. Das passiert zum Beispiel, wenn die Organisation in der Zwischenzeit über ein anderes Nutzerprofil verknüpft wurde.
Anthropic teilt dir nicht mit, welche Claude-Organisation ein Kunde verknüpft, daher kannst du dies nicht im Voraus erkennen. Der Pushed Authorization Request in Schritt 5 ist erfolgreich, und auth.claude.com lehnt die Verbindung erst ab, wenn der Nutzer die Genehmigung erteilt.
Der Fehler nennt nicht das Nutzerprofil, das die Verbindung hält. Am wahrscheinlichsten hält sie ein anderes verknüpftes Profil dieses Kunden. Anthropic zeigt nicht an, mit welcher Organisation ein Profil verknüpft ist, kläre dies daher mit dem Kunden, bevor du handelst. Wenn dieses Profil die Verbindung hält, tu eines der Folgenden:
- Sende bei den Anfragen, die du diesem Kunden in Rechnung stellst, die ID dieses Nutzerprofils.
- Beende diese Verbindung, wie unter Die Verknüpfung eines Kunden aufheben beschrieben, und führe dann die Schritte 5 bis 8 mit dem abgelehnten Nutzerprofil erneut aus.
Wenn keines der Profile dieses Kunden verknüpft ist, hat der Nutzer möglicherweise eine Organisation ausgewählt, die einem anderen deiner Kunden gehört. Beginne erneut bei Schritt 5 und lass den Nutzer prüfen, welche Organisation er auswählt.
Deine Redirect-URI erhält nichts
Deine App kann diese beiden Fälle nicht erkennen:
- Der Nutzer schließt die Genehmigungsseite.
- Die
request_uriist abgelaufen oder wurde bereits verwendet. Die Genehmigungsseite zeigt dann einen Fehler an und schickt den Browser nicht zu deiner App zurück.
Wenn der Nutzer ohne Callback zu deinem Produkt zurückkehrt, beginne erneut bei Schritt 5. Eine nicht verwendete request_uri läuft 10 Minuten nach ihrer Erstellung ab.
Der Code-Austausch gibt unauthorized_client zurück
Deine App ist für diese Anfrage nicht eingerichtet. Bei einem Workspace-Problem nennt die error_description die Ursache. Bei einem fehlenden Operator-Service-Konto lautet sie nur the client is not registered for this grant. Die Ablehnung verbraucht den Code nicht, du kannst denselben Code also erneut austauschen, bis er abläuft. Prüfe zuerst Folgendes in der Claude Console:
| Prüfung | Wo | Behebung |
|---|---|---|
| Die App hat ein Operator-Service-Konto | Operator service account auf dem Tab Client authentication der App | Wähle eines aus und klicke auf Save. Schritt 3 beschreibt, wie du eines einrichtest. |
| Der Workspace der App fehlt nicht und ist nicht archiviert | Deine App einrichten | Wähle einen Workspace aus. Solange die App keinen hat, wird der Austausch ebenfalls mit unauthorized_client abgelehnt. |
Ein gespeichertes Service-Konto kann ein bis zwei Minuten brauchen, bis es auth.claude.com erreicht. Wenn der Austausch erneut abgelehnt wird, warte daher so lange und versuche es erneut. Wenn der Code bis dahin abgelaufen ist, lass den Nutzer erneut genehmigen (Schritte 5 bis 8). Die Ursachen, die error_description für die Token einer Verbindung nennt, findest du unter Die Token speichern und Die Token aktualisieren.
Wende dich in allen anderen Fällen an dein Anthropic-Account-Team. Tu dasselbe, wenn die Console anzeigt, dass das Service-Konto nicht mehr existiert.
Deine App veröffentlichen
Bis deine App live ist, können nur die Personen auf ihrer Liste Test users sie verknüpfen, deine Kunden also nicht. Um die App zu veröffentlichen, klicke auf der Seite der App in der Claude Console auf Publish app. Ein Dialogfeld öffnet sich.
- Wenn deine Organisation per Rechnung abgerechnet wird, ist die App live, sobald du in diesem Dialogfeld bestätigst.
- Andernfalls weist du in diesem Dialogfeld zuerst nach, dass du die Domain der App kontrollierst, und Anthropic prüft die App anschließend.
Der Domain-Nachweis: Die Domain ist die Domain der Homepage deiner App. Jede Redirect-URI muss auf dieser Domain oder auf einer ihrer Subdomains liegen, außer einer auf localhost, 127.0.0.1 oder [::1]. Der Nachweis ist ein DNS-TXT-Eintrag. DNS-Änderungen können bis zu 48 Stunden dauern, beginne also, bevor Kunden verknüpfen müssen. Wenn deine Organisation bereits eine Domain nachgewiesen hat, die die Homepage und diese Redirect-URIs abdeckt, überspringt das Dialogfeld den Nachweis. Eine nachgewiesene Domain deckt ihre Subdomains ab.
Du bestätigst im letzten Schritt des Dialogfelds. Wenn dieser Schritt ein Kontrollkästchen zum Akzeptieren der Linked Billing Terms anzeigt, aktiviere es. Klicke dann im Dialogfeld auf Publish app.
Die Prüfung: Während der Prüfung lautet der Status der App in der Console In review. Die App ist live, wenn Anthropic sie genehmigt. Wenn Anthropic sie nicht genehmigt, lautet der Status Not approved, und du kannst die App nicht selbst erneut veröffentlichen. Um Fragen zur Entscheidung zu stellen, wende dich an den Support.
Sofern deine Organisation nicht per Rechnung abgerechnet wird, schickt eine Änderung am Namen, am Logo, an der Homepage oder an den Redirect-URIs einer Live-App die App zurück in die Prüfung. Bereits verknüpfte Kunden bleiben verknüpft und behalten die Obergrenze, die sie gespeichert haben. Bis Anthropic die Änderung genehmigt, können nur die Personen auf der Liste Test users die App verknüpfen.
Aufrufe an Claude anpassen
Sende den Header anthropic-user-profile-id bei jedem Aufruf von /v1/messages und /v1/chat/completions für einen verknüpften Kunden. Bei einer Anfrage, die du dem Kunden in Rechnung stellst, ist der Wert des Headers die ID des Nutzerprofils, das die Verbindung dieses Kunden hält. Aufrufe, die billing_policy setzen, müssen außerdem den Beta-Header user-profiles-billing-2026-10-01 senden.
Jede Anfrage für einen verknüpften Kunden wird entweder dem Kunden oder dir in Rechnung gestellt, und du entscheidest bei jeder Anfrage, wem. Die folgenden Beispiele zeigen beides.
OAuth-Token für jede Verbindung beschreibt eine weitere Möglichkeit, die Anfragen eines Kunden zu authentifizieren: ein Access-Token, das nur diesem Kunden etwas in Rechnung stellen kann. Auf /v1/messages und /v1/chat/completions kann eine Anfrage mit einem solchen Token nicht dir in Rechnung gestellt werden. Sie wird diesem Kunden in Rechnung gestellt, auch ohne billing_policy oder den Header anthropic-user-profile-id, wo diese optional sind: siehe den Hinweis unter Claude mit dem Access-Token einer Verbindung aufrufen. Wenn sie ein anderes Nutzerprofil angibt oder bill_to: "self" setzt, wird sie abgelehnt. Verwende ein solches Token niemals für eine Anfrage, die du bezahlst.
Dein Kunde bezahlt
Füge dem Anfrage-Body billing_policy mit bill_to: "user_profile" hinzu und sende den Abrechnungs-Beta-Header sowie den Profil-ID-Header.
Setze bill_to: "user_profile" nur bei Anfragen, die du auf Anweisung des Kunden stellst: die Claude-Nutzung, die der Kunde und seine Nutzer in deinem Produkt verursachen. Stelle einem Kunden nicht deine eigene Nutzung in Rechnung, etwa für Tests, Evaluierungen oder Arbeit für andere Kunden. Die Claude API kann dies nicht für dich überprüfen, daher liegt es in deiner Verantwortung.
def message_billed_to_user(user_profile_id: str, prompt: str) -> BetaMessage:
return client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": prompt}],
betas=[BILLING_BETA],
extra_headers={"anthropic-user-profile-id": user_profile_id},
extra_body={
"billing_policy": {"type": "billing_policy", "bill_to": "user_profile"}
},
)Wenn die Anfrage abgelehnt wird, siehe Erwartete Fehler.
Du bezahlst
Um selbst zu bezahlen, lässt du billing_policy entweder ganz weg (in diesem Fall ist der Abrechnungs-Beta-Header optional):
def message_billed_to_you(user_profile_id: str, prompt: str) -> Message:
return client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": prompt}],
user_profile_id=user_profile_id,
)oder verwendest bill_to: "self":
def message_billed_to_self(user_profile_id: str, prompt: str) -> BetaMessage:
return client.beta.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[{"role": "user", "content": prompt}],
betas=[BILLING_BETA],
extra_headers={"anthropic-user-profile-id": user_profile_id},
extra_body={"billing_policy": {"type": "billing_policy", "bill_to": "self"}},
)OAuth-Token für jede Verbindung
Dein Back-End ruft die Claude API als Operator-Service-Konto deiner App auf (Schritt 3). Standardmäßig kann jede als dieses Service-Konto authentifizierte Anfrage jedem verknüpften Kunden etwas in Rechnung stellen, indem sie einen Nutzerprofil-ID-Header übergibt und bill_to in Messages API-Anfragen angibt. Dieser Standard heißt „operator-only tokenless authentication“ (tokenlose Authentifizierung nur für den Operator).
Um Single-Tenant-Bereitstellungen deines Produkts oder vom Kunden kontrollierte Sandbox-Umgebungen zu unterstützen, kannst du an eine Verbindung gebundene OAuth-Access- und Refresh-Token beziehen, anstatt die tokenlose Authentifizierung nur für den Operator zu verwenden.
Für jede Verbindung gibt der Code-Austausch in Schritt 8 das eigene Access-Token dieser Verbindung zurück. Das Token authentifiziert sich als dein Operator-Service-Konto, kann aber nur dem Kunden dieser Verbindung etwas in Rechnung stellen. Es läuft innerhalb von 1 Stunde ab.
Um jede Verbindung separat zu authentifizieren:
- Offline-Zugriff verwenden. Aktiviere Offline access für deine App und fordere in Schritt 5
offline_accessan. Jede Verbindung erhält dann zusätzlich ein Refresh-Token, mit dem dein Back-End neue Access-Token anfordert. Ohne dieses muss der Kunde erneut genehmigen, damit du ein neues Access-Token erhältst: Führe die Schritte 5 bis 8 mit demselbenscopeerneut aus. - Einen Standard-Workspace festlegen. Wähle einen Workspace in deiner Organisation, in dem Anfragen mit diesen Token ausgeführt werden.
- Optional die tokenlose Authentifizierung nur für den Operator deaktivieren. Standardmäßig kannst du einem verknüpften Kunden weiterhin als dein Operator-Service-Konto etwas in Rechnung stellen (indem du einen Nutzerprofil-Header und
bill_toübergibst), selbst nachdem das Access-Token des Kunden abgelaufen ist. Nachdem du die reine Operator-Authentifizierung deaktiviert hast, muss sich jede Anfrage, die einem Kunden etwas in Rechnung stellt, mit dem Access-Token dieses Kunden authentifizieren. billing:attributionverwenden. Nur dieser Scope gibt einer Verbindung eigene Token. Du kannst einem verknüpften Kunden weiterhin als dein Operator-Service-Konto etwas in Rechnung stellen, wie mitorg:billing_attribution, das abgekündigt ist. Siehe Scopes für eine Abrechnungsverbindung.
Deine App einrichten
Anfragen mit dem Access-Token einer Verbindung laufen in einem Workspace deiner Organisation. Jede App benötigt einen, auch wenn du diese Token nicht verwendest: Solange deine App keinen Workspace hat, wird der Code-Austausch in Schritt 8 mit unauthorized_client abgelehnt.
Ein Mitglied deiner Organisation mit der Rolle Admin öffnet den Tab Client authentication der App in der Console. Suche unter dem Operator-Service-Konto Default workspace for platform auth mode OAuth tokens (die Einstellung connection_token_workspace_id der App) und klicke auf Choose workspace. Wähle einen Workspace aus, in dem das Operator-Service-Konto (Schritt 3) Mitglied ist. Der Workspace darf nicht archiviert sein.
Um Refresh-Token zu erhalten, aktiviere Offline access auf dem Tab Permissions der App. Eine Änderung an den Scopes der App braucht einige Minuten, bis sie auth.claude.com erreicht.
Scopes für eine Abrechnungsverbindung
Sende in Schritt 5 scope als billing:attribution. Um zusätzlich ein „refresh token“ (Aktualisierungstoken) zu erhalten, sende billing:attribution offline_access.
Um die Scopes eines bereits verknüpften Kunden zu ändern, zum Beispiel um offline_access hinzuzufügen, führe die Schritte 5 bis 8 erneut mit dem bestehenden Nutzerprofil des Kunden und dem neuen scope aus. Du hebst die Verknüpfung vorher nicht auf. Der Code-Austausch gibt eine neue connection_id zurück, und die neue Verbindung ersetzt die vorherige. Siehe den Hinweis in Schritt 8.
Eine App kann gleichzeitig billing:attribution und das abgekündigte org:billing_attribution haben. Du fügst billing:attribution unter Billing auf dem Tab Permissions der App hinzu. Wenn du org:billing_attribution dort entfernst, kannst du es nicht erneut hinzufügen. Eine Verbindung, die ein Kunde mit org:billing_attribution genehmigt hat, rechnet weiterhin über dein Operator-Service-Konto ab, bis die Verbindung endet oder du die reine Operator-Authentifizierung deaktivierst.
Die Token speichern
Der Code-Austausch gibt die Token nur einmal zurück, speichere sie daher in Schritt 8. Die Antwort enthält access_token, expires_in (höchstens 1 Stunde, in Sekunden) und connection_id. Wenn der Kunde offline_access genehmigt hat, enthält sie außerdem refresh_token und refresh_token_expires_in. Ein Refresh-Token gilt höchstens 1 Jahr, und eine Aktualisierung verlängert diese Frist nicht. Danach musst du den Kunden erneut verknüpfen.
Speichere die Token und ihre Ablaufzeiten in einem Secret Store, den nur der Dienst lesen kann, der die Aktualisierung durchführt.
Wenn der Austausch mit unauthorized_client abgelehnt wird, gibt error_description die Ursache an, etwa einen fehlenden oder archivierten Workspace. Der Code ist dadurch nicht verbraucht: Behebe die Ursache und sende denselben Code erneut, bevor er abläuft.
Claude mit dem Access-Token einer Verbindung aufrufen
Sende das Access-Token der Verbindung als Bearer-Token im Header Authorization, anstelle der eigenen Anmeldedaten deines Operator-Service-Kontos. Sende keinen x-api-key-Header. Übergib das Token im Anthropic SDK als auth_token oder setze die Umgebungsvariable ANTHROPIC_AUTH_TOKEN.
Bei /v1/messages und /v1/chat/completions wird die Anfrage dem Kunden dieser Verbindung in Rechnung gestellt. Der Header anthropic-user-profile-id und billing_policy sind optional. Den Abrechnungs-Beta-Header benötigst du nur zusammen mit billing_policy.
Auf diesen beiden Endpunkten kannst du mit diesem Token keine Anfrage selbst bezahlen. Verwende das Token nur auf diesen beiden Endpunkten, /v1/messages/count_tokens und den Models-Endpunkten. Sende jede andere Anfrage und jede Anfrage, die du bezahlst, als dein Operator-Service-Konto von deinem eigenen Back-End aus. Dazu gehört auch eine Anfrage, die kostenpflichtige Code-Ausführungsfunktionen verwendet, da diese keinem Kunden in Rechnung gestellt werden kann.
Die Claude API lehnt diese Anfragen ab:
400 invalid_request_error, ohne Fehlercode: Die Anfrage hat ein anderes Nutzerprofil angegeben oderbill_to: "self"gesetzt.403 permission_error, ohne Fehlercode: Die Anfrage ging an einen Message Batches-Endpunkt.401 authentication_error: Das Token ist abgelaufen, eine Aktualisierung hat es ersetzt, oder seine Verbindung wurde beendet. Nachdem eine Verbindung beendet wurde, kann die Antwort auch403 user_profile_not_billablelauten.
Die Token aktualisieren
Um das Access-Token einer Verbindung zu erneuern, sende ihr Refresh-Token an den Token-Endpunkt https://auth.claude.com/v1/oauth/token, zusammen mit der Client-Authentifizierung deiner App. Sende keinen scope-Parameter.
connection_locks: defaultdict[str, threading.Lock] = defaultdict(threading.Lock)
def error_body(response: httpx.Response) -> dict:
try:
body = response.json()
except ValueError:
return {}
return body if isinstance(body, dict) else {}
def is_lost(response: httpx.Response) -> bool:
"""True for a 5xx response that can follow a refresh that took effect."""
if response.status_code < 500:
return False
# Ein 503 im Format der Claude API mit retry-after-Header ist eine Ablehnung,
# die den Refresh-Token nicht verbraucht. Jede andere 5xx-Antwort gilt als verloren.
paused = (
response.status_code == 503
and error_body(response).get("type") == "error"
and "retry-after" in response.headers
)
return not paused
def hold_error(connection_id: str, reason: str) -> RefreshOnHold:
return RefreshOnHold(
f"Connection {connection_id} is on hold. {reason} Don't send its refresh token"
' again: that can end the connection. See "Link a customer again" in the'
" Linked billing guide."
)
def refresh_connection(connection_id: str, *, force: bool = False) -> tuple[str, int]:
"""Refreshes the connection if its access token is close to its expiry.
Returns the current access token and its expiry time in Unix seconds. Call
this from your schedule, and pass force=True to refresh a token that isn't
close to its expiry. Raises RefreshOnHold when the refresh token can't be sent
again, now and on every later call, and httpx.HTTPStatusError for a refusal
that keeps the refresh token. After RefreshOnHold for a lost refresh, pause
your schedule. Resume with one connection, and resume the others only after
that refresh succeeds or gets a 4xx.
"""
# Dieser Lock wirkt innerhalb eines Prozesses. Hat der Dienst Replikas, verwende
# einen Lock, den alle gemeinsam nutzen.
with connection_locks[connection_id]:
tokens = load_tokens(connection_id)
if tokens.on_hold:
raise hold_error(
connection_id, "An earlier refresh might have used its refresh token."
)
if not force and tokens.expires_at - time.time() > REFRESH_MARGIN_SECONDS:
return tokens.access_token, tokens.expires_at # not close to expiry
request = {
"grant_type": "refresh_token",
"refresh_token": tokens.refresh_token,
"client_id": CLIENT_ID,
"client_assertion_type": JWT_BEARER,
"client_assertion": client_assertion(),
}
url = f"{AUTH}/v1/oauth/token"
# Setze die Verbindung auf Hold, bevor der Refresh-Token diesen Prozess verlässt.
# Stoppt der Prozess, bevor die neuen Tokens gespeichert sind, bleibt der Hold.
save_tokens(connection_id, replace(tokens, on_hold=True))
issued_at = int(time.time())
started = time.monotonic()
# httpx wiederholt nicht von selbst. Füge keine Retries hinzu: ein später Retry beendet die
# Verbindung.
try:
response = httpx.post(url, json=request, timeout=REQUEST_TIMEOUT)
lost = is_lost(response)
except (httpx.ConnectError, httpx.ConnectTimeout):
# Es kam keine Verbindung zustande, also hat der Refresh-Token den Prozess nie verlassen.
save_tokens(connection_id, tokens)
raise
except httpx.TransportError:
lost = True
if lost:
# Die erste Anfrage hat den Refresh-Token evtl. verwendet. Eine zweite Anfrage
# ist nur innerhalb des obigen Limits sicher, also sende sie sofort oder gar
# nicht.
if time.monotonic() - started > SECOND_REQUEST_DEADLINE_SECONDS:
raise hold_error(connection_id, "A refresh got no usable answer.")
try:
response = httpx.post(url, json=request, timeout=REQUEST_TIMEOUT)
except httpx.TransportError:
raise hold_error(
connection_id, "Two refreshes got no answer."
) from None
if response.status_code != 200:
# Nach jeder Antwort außer neuen Tokens weißt du nicht, ob die
# erste Anfrage gewirkt hat, und eine spätere Anfrage ist nicht sicher.
raise hold_error(connection_id, "The second refresh failed.")
if error_body(response).get("error") == "invalid_grant":
# Abgelaufen, bereits verwendet oder die Verbindung ist beendet. Erneutes Senden
# kann die Verbindung beenden.
raise hold_error(connection_id, "The refresh returned invalid_grant.")
if response.status_code != 200:
# Eine Ablehnung, die den Refresh-Token behält, also heb den Hold auf.
save_tokens(connection_id, tokens)
response.raise_for_status()
body = response.json()
tokens = ConnectionTokens(
refresh_token=body["refresh_token"],
access_token=body["access_token"],
expires_at=issued_at + body["expires_in"],
refresh_expires_at=issued_at + body["refresh_token_expires_in"],
)
# Schlägt das Schreiben fehl, versuch das Schreiben erneut. Kein erneuter Refresh.
for attempt in range(5):
try:
save_tokens(connection_id, tokens)
return tokens.access_token, tokens.expires_at
except OSError: # your secret store's error type
if attempt < 4:
time.sleep(2**attempt)
# Die neuen Tokens existieren nur in diesem Prozess, und der gespeicherte Refresh-Token
# ist verbraucht. Der gespeicherte Eintrag ist noch auf Hold. Der Fehler enthält die neuen
# Tokens, damit der Aufrufer sie speichern kann, sobald der Secret Store wieder da ist.
error = hold_error(
connection_id,
"The refresh succeeded, but the new tokens could not be saved.",
)
error.new_tokens = tokens
raise errorDie Antwort enthält ein neues access_token und ein neues refresh_token. Das Refresh-Token, das du gesendet hast, wird ersetzt: Sende es nicht erneut, außer wie es die folgende Liste der Fehlschläge beschreibt. Das vorherige Access-Token funktioniert innerhalb weniger Minuten nicht mehr. Initialisierung der OAuth-Token-Snippets definiert die Funktionen, die das Beispiel aufruft.
- Speichere das neue Refresh-Token, bevor du das neue Access-Token verwendest.
- Aktualisiere die Token jeder Verbindung von einem einzigen Dienst aus, jeweils eine Aktualisierung nach der anderen. Wenn der Dienst Replikate hat, verwende eine Sperre, die alle teilen. Ein verwendetes Refresh-Token, das mehr als 30 Sekunden nach seiner ersten Verwendung erneut eintrifft, beendet die Verbindung. Alle Token werden widerrufen, der Kunde wird als Unlinked angezeigt, und keine Anmeldedaten können ihm etwas in Rechnung stellen, bis er erneut verknüpft.
- Deaktiviere automatische Wiederholungen für die Aktualisierungsanfrage, in deinem HTTP-Client und in jedem Proxy.
Wenn die erste Anfrage mit einem Refresh-Token fehlschlägt:
- Die Anfrage konnte keine Verbindung herstellen: Das Refresh-Token wurde nicht gesendet. Versuche es später erneut.
- Eine abgebrochene Verbindung oder eine 5xx-Antwort außer dem
503in dieser Liste: Du kannst nicht erkennen, ob die Anfrage wirksam wurde, sende daher dasselbe Refresh-Token noch einmal.- Sende es sofort, und nur, wenn seit dem Senden der ersten Anfrage weniger als 30 Sekunden vergangen sind.
- Wenn sie neue Token zurückgibt, speichere sie und verwende nur diese. Wenn die erste Anfrage doch wirksam wurde, werden deren Token, die dich nie erreicht haben, widerrufen.
- Wenn sie etwas anderes zurückgibt oder keine Antwort erhält, oder wenn die 30 Sekunden vergangen sind, sende dieses Refresh-Token nicht erneut. Stoppe die Aktualisierung dieser Verbindung und verknüpfe den Kunden erneut.
- Ein Timeout: Die Anfrage läuft möglicherweise noch. Sende dieses Refresh-Token nicht erneut. Stoppe die Aktualisierung dieser Verbindung und verknüpfe den Kunden erneut.
429oder503mit einemretry-after-Header und"type": "error"auf oberster Ebene des Bodys: Nichts wurde widerrufen. Warte mindestens so lange, wie der Header angibt, und sende dasselbe Refresh-Token erneut.unauthorized_clientoderinvalid_client: Nichts wurde widerrufen.error_descriptiongibt die Ursache an, etwa einen fehlenden Workspace,offline_access, das für deine App nicht mehr registriert ist, oder eine fehlgeschlagene Client-Assertion. Behebe sie und sende dasselbe Refresh-Token erneut.invalid_scope: Die Anfrage hat einenscope-Parameter gesendet, oderbilling:attributionist für deine App nicht mehr registriert. Nichts wurde widerrufen. Behebe die Ursache und sende dasselbe Refresh-Token erneut.invalid_grant: Das Refresh-Token ist abgelaufen oder wurde bereits verwendet, die Verbindung wurde beendet, oder die Organisation des Kunden ist gesperrt. Stoppe die Aktualisierung dieser Verbindung und folge Einen Kunden erneut verknüpfen, das mit einer Prüfung auf eine Sperrung beginnt.
Wenn dich eine abgebrochene Verbindung, eine 5xx-Antwort oder ein Timeout dazu gebracht hat, die Aktualisierung einer Verbindung zu stoppen, pausiere auch die Aktualisierungen deiner anderen Verbindungen. Wenn du fortfährst, aktualisiere zuerst eine Verbindung und setze die anderen erst fort, nachdem diese Aktualisierung erfolgreich war oder eine 4xx-Antwort erhalten hat.
Einen Agenten in einer Sandbox ausführen
Gib einer Sandbox nur das Access-Token, niemals das Refresh-Token. Dein Back-End führt die Aktualisierung durch und sendet jedes neue Access-Token an die Sandbox. Es entscheidet anhand der eigenen Identität der Sandbox, etwa ihrer Pod-Identität, welchem Kunden eine Sandbox dient, und niemals anhand eines Werts, den die Sandbox sendet. Es sendet einer Sandbox nur das Token dieses Kunden. Die Sandbox darf kein JWT erhalten können, das einer deiner Föderationsregeln oder der Client-Authentifizierung deiner App entspricht. Gib ihr kein eingebundenes Identitätstoken und keinen Zugriff auf einen Cloud-Metadatenserver.
Claude Code, das Claude Agent SDK und das Anthropic SDK können das Token aus einer Anmeldedatendatei in einem Konfigurationsprofil lesen (siehe Profil-Konfigurationsdatei). Erstelle in der Sandbox ein Konfigurationsverzeichnis mit diesem Profil. Füge ihm keine client_id hinzu: Mit einer solchen versucht das SDK, das Token selbst zu aktualisieren.
{
"version": "1.0",
"authentication": {
"type": "user_oauth"
}
}Schreibe das Access-Token als credentials/customer.json in dasselbe Verzeichnis, bevor der Agent startet und nach jeder Aktualisierung. expires_at ist die Ablaufzeit in Unix-Sekunden. Schreibe eine neue Datei mit dem Modus 0600 und benenne sie so um, dass sie die alte ersetzt:
{
"type": "oauth_token",
"access_token": "sk-ant-oat01-...",
"expires_at": 1793635200
}Setze ANTHROPIC_CONFIG_DIR auf das Konfigurationsverzeichnis und ANTHROPIC_PROFILE auf customer. Entferne alle anderen Anmeldedaten in der Sandbox, etwa ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_OAUTH_TOKEN und die Claude Code-Einstellung apiKeyHelper, da jede davon Vorrang vor dem Profil haben kann. Der Agent liest die Datei in den letzten 2 Minuten vor expires_at und nach einer 401-Antwort erneut.
def write_credentials_file(
config_dir: Path, profile: str, token: str, expires_at: int
) -> None:
credentials_dir = config_dir / "credentials"
credentials_dir.mkdir(mode=0o700, parents=True, exist_ok=True)
body = {"type": "oauth_token", "access_token": token, "expires_at": expires_at}
# Benenne eine fertige Datei an ihren Platz um, damit der Agent nie eine halbe Datei liest.
# mkstemp setzt Modus 0600 mit dem aktuellen Benutzer als Owner, also führe dies als
# Benutzer des Agents aus.
handle, temporary_path = tempfile.mkstemp(dir=credentials_dir)
with os.fdopen(handle, "w") as temporary_file:
json.dump(body, temporary_file)
os.replace(temporary_path, credentials_dir / f"{profile}.json")Einen Kunden erneut verknüpfen
Verknüpfe einen Kunden in diesen Fällen erneut:
- Eine Aktualisierung hat
invalid_grantzurückgegeben. - Du hast ein Refresh-Token verloren, oder eines ist nach außen gelangt.
- Du hast die Antwort in Schritt 8 für
billing:attribution offline_accessverloren, oder Schritt 8 hat für eine solche Verbindunginvalid_grantzurückgegeben. - Ein Refresh-Token läuft bald ab.
Führe diese Schritte aus:
- Prüfe auf deiner Seite User profiles, ob der Kunde als Linked angezeigt wird. Frage nach
invalid_grantzuerst dein Anthropic-Account-Team, ob die Organisation des Kunden gesperrt ist: Nachdem eine Sperrung endet, funktioniert das Refresh-Token, das du besitzt, wieder. Wenn jede Verbindung gleichzeitiginvalid_grantzurückgibt, suche nach einer Ursache auf deiner Seite, etwa einem archivierten Workspace, bevor du die Verknüpfung von jemandem aufhebst. - Wenn der Kunde als Linked angezeigt wird, hebe seine Verknüpfung auf, wie unter Die Verknüpfung eines Kunden aufheben beschrieben. Das Aufheben der Verknüpfung widerruft die Token der Verbindung. Tu dies, wenn ein Administrator der Organisation des Kunden bereit ist, die Genehmigung zu erteilen, denn die Abrechnung über die Verbindung stoppt, bis er das tut.
- Führe die Schritte 5 bis 8 erneut mit dem bestehenden Nutzerprofil des Kunden aus. Speichere die neue Verbindungs-ID und die neuen Token anstelle der vorherigen.
Die reine Operator-Authentifizierung deaktivieren
Um zu verhindern, dass Anfragen, die sich nur als dein Operator-Service-Konto authentifizieren, Kunden in Rechnung gestellt werden, aktiviere Disable operator-only tokenless authentication (die App-Einstellung disable_operator_only_auth). Sie befindet sich auf dem Tab Client authentication der App, unter dem Operator-Service-Konto. Deine App muss die Scopes billing:attribution und offline_access sowie einen Workspace für ihre OAuth-Token haben. Bevor du sie aktivierst, stelle sicher, dass jeder verknüpfte Kunde billing:attribution offline_access genehmigt hat und dass deine Anfragen mit ihren Access-Token funktionieren. Solange sie aktiviert ist, kann nur das Access-Token einer billing:attribution-Verbindung dem Kunden dieser Verbindung etwas in Rechnung stellen. Eine Anfrage, die sich nur als das Service-Konto authentifiziert und bill_to: "user_profile" setzt, wird mit 403 user_profile_not_billable abgelehnt. Der Kunde wird weiterhin als Linked angezeigt, achte daher in deinen Logs auf diesen Fehler. Das Service-Konto kann weiterhin Nutzerprofile verwalten und die Anfragen senden, die du bezahlst. Du kannst die Einstellung wieder deaktivieren.
Initialisierung der OAuth-Token-Snippets
Die Beispiele in diesem Abschnitt teilen sich das folgende Setup. Es definiert:
- die Importe, zu denen das Paket
httpxgehört - die Client-ID deiner App und den Typ der Client-Assertion
ConnectionTokens, das die Token einer Verbindung, ihre Ablaufzeiten und ihreon_hold-Markierung enthältRefreshOnHold, den Fehler, denrefresh_connection()auslöst, wenn ein Refresh-Token nicht erneut gesendet werden darf: Es wurde möglicherweise bereits verwendet, oder der Token-Endpunkt hat mitinvalid_grantgeantwortet.refresh_connection()löst ihn auch bei jedem späteren Aufruf aus, bis duon_holdin den gespeicherten Token entfernst, zum Beispiel nachdem eine Sperrung endet. Wenn eine Aktualisierung erfolgreich war und nur dein Secret Store das Schreiben verweigert hat, enthält seinnew_tokensdie zu speichernden Token.client_assertion(), das das JWT deines Identitätsanbieters aus der Datei liest, dieANTHROPIC_IDENTITY_TOKEN_FILEangibt. Deraud-Claim des JWT muss der Audience in den Client-Authentifizierungseinstellungen deiner App entsprechen.load_tokens()undsave_tokens(), die du für deinen eigenen Secret Store schreibst
import json
import os
import tempfile
import threading
import time
from collections import defaultdict
from dataclasses import dataclass, field, replace
from pathlib import Path
import httpx
AUTH = "https://auth.claude.com"
# kopiere sie von platform.claude.com, nachdem du deine OAuth-App registriert hast.
CLIENT_ID = "YOUR_CLIENT_ID"
JWT_BEARER = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
REFRESH_MARGIN_SECONDS = 600
# Ein Refresh mit Timeout verliert hier seine neuen Tokens, also gib der Antwort
# 10 Sekunden. Eine Verbindung, die nicht zustande kommt, scheitert binnen 2.
REQUEST_TIMEOUT = httpx.Timeout(10, connect=2)
# Eine zweite Anfrage muss so bald nach der ersten starten oder gar nicht. Die
# Seite nennt 30 Sekunden, aber bleib unter dem Read-Timeout von REQUEST_TIMEOUT:
# eine Anfrage mit Timeout darf nicht erneut gesendet werden.
SECOND_REQUEST_DEADLINE_SECONDS = 4
@dataclass
class ConnectionTokens:
refresh_token: str = field(repr=False)
access_token: str = field(repr=False)
expires_at: int # the access token's expiry time, in Unix seconds
refresh_expires_at: int # the refresh token's expiry time, in Unix seconds
# True: Der Refresh-Token wurde evtl. verwendet. Sende ihn nicht erneut.
on_hold: bool = False
class RefreshOnHold(Exception):
"""The refresh token might have been used, so a person decides what to do next.
Don't catch this to try again. If new_tokens is set, the refresh succeeded and
only the write failed: store those tokens.
"""
new_tokens: ConnectionTokens | None = None
def client_assertion() -> str:
"""Reads your identity provider's JWT on every call, because its file rotates."""
return Path(os.environ["ANTHROPIC_IDENTITY_TOKEN_FILE"]).read_text().strip()
def load_tokens(connection_id: str) -> ConnectionTokens:
"""Reads the connection's newest tokens from your secret store."""
raise NotImplementedError("Read the tokens from your secret store.")
def save_tokens(connection_id: str, tokens: ConnectionTokens) -> None:
"""Writes the connection's newest tokens to your secret store."""
raise NotImplementedError("Write the tokens to your secret store.")Deine Verbindungen verwalten
Kunden in der Console anzeigen
Zusätzlich zur OAuth-Apps-Seite kannst du alle deine Nutzerprofile auf der Seite User profiles in der Console einsehen. In dieser Liste und auf der Detailseite jedes Nutzerprofils gibt Your spend deine eigenen Kosten für die Anfragen dieses Nutzerprofils an. Es sind die Kosten, bevor Anthropic etwaiges Guthaben anrechnet. Auf diesen Seiten wird eine Verbindung als Link bezeichnet: Bei einem Nutzerprofil mit aktiver Verbindung steht Linked, und bei einem, dessen Verbindung beendet wurde, steht Unlinked.
Klicke auf ein Nutzerprofil, um eine detailliertere Ansicht seiner Nutzung über die letzten 7, 28 oder 90 Tage zu erhalten.
Die Nutzung jedes Kunden überwachen
Die Claude Console und die Usage and Cost Analytics API melden beide die Nutzung für jedes Nutzerprofil. Beide zählen die Anfragen, die du bezahlst, und die Anfragen, die dein Kunde bezahlt. Keine von beiden zeigt, was der Kunde bezahlt hat, oder die Preise des Kunden.
In der Console listet die Seite User profiles Requests, Tokens und Your spend für jedes Nutzerprofil über die letzten 28 Tage auf. Eine Anfrage, die dein Kunde bezahlt, erhöht Requests und Tokens des Profils und fügt Your spend nichts hinzu.
Rufe die API mit Admin API-Anmeldedaten auf, etwa einem OAuth-Access-Token mit dem Scope org:admin oder einem Admin API-Key. Verwende nicht dein Operator-Service-Konto (Schritt 3). Seine Föderationsregel gewährt standardmäßig workspace:developer, nicht org:admin. Der Scope org:admin umfasst die gesamte Admin API, füge ihn daher nicht dem Operator-Service-Konto hinzu.
Um über die API nach Nutzerprofil auszuwerten, rufe ihren Usage-Endpunkt oder ihren Cost-Endpunkt auf. Um eine Zeile für jedes Nutzerprofil zu erhalten, gruppiere nur nach user_profile_id und lass time_bucket_width weg. Nur ein Nutzerprofil, das im angefragten Zeitraum Nutzung hat, erhält eine Zeile. Eine weitere Zeile hat eine user_profile_id von null. Sie enthält Nutzung, die kein Profil angegeben hat, und Nutzung, die außerhalb von Anfragen gemessen wird, etwa die Laufzeit von Code-Ausführungscontainern.
Beim Cost-Endpunkt fügt eine Anfrage, die dein Kunde bezahlt, amount 0 und list_amount ihren Listenpreis hinzu. Das Feld amount ist dasselbe Maß wie Your spend. Die API hat kein Feld, keinen Filter und keinen group_by[]-Wert dafür, wer bezahlt hat. Eine Zeile mit einem amount von 0 und einem list_amount über 0 bedeutet in der Regel, dass der Kunde jede Anfrage in dieser Zeile bezahlt hat.
Verwende diese Zahlen nicht, um die Nutzung eines Kunden bei einem von dir gewählten Betrag zu stoppen. Weder die Console noch die API berichten in Echtzeit. Die Zahlen der Console werden etwa einmal pro Stunde aktualisiert, und eine Anfrage kann einige Stunden brauchen, bis sie erscheint. Zur Verzögerung der API siehe Datenaktualität. Ausgabenobergrenzen beschreibt, was die eigenen Limits des Kunden bewirken.
Die Verknüpfung eines Kunden aufheben
Um die Verknüpfung eines Kunden in der Console aufzuheben, verwende die Liste auf der Seite User profiles oder die Schaltfläche Unlink oben rechts auf der Detailseite eines Nutzerprofils.
Um die Verknüpfung eines Kunden von deinem Back-End aus aufzuheben, sende die Verbindungs-ID, die du in Schritt 8 gespeichert hast, an den Widerrufsendpunkt, mit derselben Client-Authentifizierung wie beim Code-Austausch. Um die Verbindung stattdessen über ihr Nutzerprofil anzugeben, sende user_profile_id anstelle von connection_id.
def revoke_connection(connection_id: str) -> list[str]:
response = httpx.post(
f"{AUTH}/v1/oauth/revoke",
json={
"connection_id": connection_id,
"client_id": CLIENT_ID,
"client_assertion_type": JWT_BEARER,
"client_assertion": client_assertion(),
},
)
response.raise_for_status()
# IDs der Verbindungen, die diese Anfrage beendet hat. Die Liste ist leer, wenn die
# Verbindung bereits beendet war oder die ID unbekannt ist.
return response.json()["revoked_connection_ids"]auth.claude.com antwortet mit HTTP 200 und revoked_connection_ids, den IDs der Verbindungen, die diese Anfrage beendet hat. Die Liste ist leer, wenn die Verbindung bereits beendet wurde, du kannst eine Anfrage, die connection_id sendet, also gefahrlos wiederholen. Sie ist auch leer, wenn die ID unbekannt ist, eine leere Liste beweist also nicht, dass die Verbindung existiert hat. Die weiteren Parameter findest du unter Widerruf, siehe außerdem Fehler des Widerrufsendpunkts.
Nachdem die Verbindung beendet wurde, wird das Nutzerprofil als Unlinked angezeigt, und eine Anfrage, die für diesen Kunden bill_to: "user_profile" setzt, erhält user_profile_not_billable. Du kannst den Kunden weiterhin auf eigene Kosten mit bill_to: "self" bedienen. Nach dem Verknüpfen beschreibt, was dein Kunde sieht, und E-Mails zum Verknüpfen und Aufheben der Verknüpfung beschreibt, bei welcher Art des Aufhebens der Verknüpfung er eine E-Mail erhält.
Einen Kunden mit einer anderen Claude-Organisation verknüpfen
Um das Nutzerprofil eines Kunden mit einer anderen Claude-Organisation zu verknüpfen, hebe die Verknüpfung des Kunden auf und verknüpfe ihn dann erneut.
Nachdem du die Verknüpfung aufgehoben hast, werden Anfragen, die du diesem Kunden in Rechnung stellst, abgelehnt. Das dauert an, bis ein Nutzer für die andere Organisation die Genehmigung erteilt und du den Code in Schritt 8 austauschst. Führe diese Schritte aus, wenn dieser Nutzer bereit ist, die Genehmigung zu erteilen:
- Überspringe diesen Schritt, wenn dein Kunde die Verknüpfung mit deiner App bereits auf seiner Seite Linked platforms aufgehoben hat. Andernfalls hebe die Verknüpfung des Kunden auf, wie unter Die Verknüpfung eines Kunden aufheben beschrieben. Das Nutzerprofil wird dann auf deiner Seite User profiles als Unlinked angezeigt.
- Führe die Schritte 5 bis 8 erneut mit demselben Nutzerprofil aus. Für Schritt 7 benötigt der Nutzer ein Konto, das in der anderen Organisation die Rolle Admin oder Billing hat. Lass den Nutzer für diese Organisation die Genehmigung erteilen.
- Speichere die neue Verbindungs-ID anstelle der vorherigen. Wenn du die Token der Verbindung verwendest, tu dasselbe mit den neuen Token.
Bis die Verknüpfung des Kunden aufgehoben ist, lässt die Genehmigungsseite einen Nutzer nur für die Organisation genehmigen, die bereits verknüpft ist.
Eine Ausgabenobergrenze gehört zu einer Kundenorganisation und deiner App, daher wird die Obergrenze der ersten Organisation nicht übernommen. Ausgabenobergrenzen enthält die Regeln.
Erwartete Fehler
Wenn eine Anfrage bill_to: "user_profile" setzt, stellt Anthropic sie entweder deinem Kunden in Rechnung oder lehnt die Anfrage ab. Sie wird niemals stillschweigend stattdessen dir in Rechnung gestellt. Bei /v1/messages steht der Code aus der folgenden Liste in error.details.error_code. Bei /v1/chat/completions erhältst du denselben HTTP-Status und dieselbe Meldung im OpenAI-Format, ohne den Code:
403 permission_error, user_profile_not_billable: Anthropic kann diesem Kunden diese Anfrage nicht in Rechnung stellen, und die Antwort gibt keinen Grund an. Nicht wiederholbar, außer in den ersten 10 Sekunden nach einer neuen Verbindung. Bevor du den Kunden bittest, erneut zu verknüpfen, sieh dir Ursachen vonuser_profile_not_billablean: Ein erneutes Verknüpfen behebt nur einige davon. Du kannst den Kunden weiterhin auf eigene Kosten bedienen, indem du die Anfrage mitbill_to: "self"erneut sendest. Behandleuser_profile_not_billableim Anthropic SDK anhand der Fehlerklasse für den Status 403, alsoPermissionDeniedError. Diese trifft auch auf andere 403-Fehler zu, prüfe daher auch den Fehlercode.402 billing_error, linked_organization_billing_unavailable: Anthropic kann der Organisation des Kunden derzeit nichts in Rechnung stellen (zum Beispiel, weil sie gesperrt ist, oder weil ihr Guthaben aufgebraucht ist, nachdem Claude mit einer Antwort begonnen hat). Die Antwort gibt keinen Grund an. Ein Kunde, der beim Eintreffen der Anfrage kein Guthaben hat, erhält stattdessenlinked_organization_spend_limit_reached. Nicht wiederholbar. Bitte den Kunden, sein Claude Platform-Konto zu überprüfen. Du kannst ihn weiterhin auf eigene Kosten bedienen, indem du die Anfrage mitbill_to: "self"erneut sendest.402 billing_error, linked_organization_spend_limit_reached: Die Organisation des Kunden hat ein von ihr festgelegtes Ausgabenlimit erreicht. Das Limit ist entweder die Ausgabenobergrenze, die für deine App gilt, oder das monatliche Ausgabenlimit für die gesamte Organisation. Die Claude API sendet denselben Code, wenn die Organisation kein Guthaben hat, das die Anfrage bezahlen kann. Die Antwort gibt nicht an, welches davon. Die Anfrage wurde abgelehnt, bevor Claude mit einer Antwort begonnen hat. Nicht wiederholbar. Du kannst den Kunden weiterhin auf eigene Kosten bedienen, indem du die Anfrage mitbill_to: "self"erneut sendest. Bitte den Kunden, Folgendes in der Claude Console zu überprüfen:- Die Ausgabenobergrenze für deine App: Auf der Seite für deine App unter Linked platforms kann er die Ausgabenobergrenze festlegen oder erhöhen. Eine dort festgelegte Obergrenze ersetzt eine etwaige Standardobergrenze, die er für alle verknüpften Plattformen festgelegt hat.
- Das Monthly spend limit der Organisation: Unter Ausgabenlimits kann er es erhöhen.
- Das Guthaben: Auf seiner Seite Abrechnung kann er sein Guthaben einsehen und Guthaben kaufen. Manches Guthaben kann diese Anfragen nicht bezahlen: siehe Welches Guthaben bezahlen kann.
503 overloaded_error: Anthropic konnte gerade nicht bestätigen, ob dem Kunden etwas in Rechnung gestellt werden kann. Wiederhole die Anfrage mit Backoff und beachte denretry-after-Header. Die Anfrage wurde weder bedient noch abgerechnet.400 invalid_request_error, user_profile_required: Du hastbill_to: "user_profile"ohne den Headeranthropic-user-profile-idgesetzt. Eine solche Anfrage benötigt den Header, es sei denn, sie verwendet das Access-Token einer Verbindung und der Header ist optional. Ob der Header optional ist, erfährst du im Hinweis unter Claude mit dem Access-Token einer Verbindung aufrufen.400 invalid_request_error, ohne Fehlercode: Der Headeranthropic-user-profile-identhält eine ID, die fehlerhaft formatiert ist oder kein Nutzerprofil deiner Organisation ist.400 invalid_request_error, ohne Fehlercode: Die Anfrage hat sich mit dem Access-Token einer Verbindung authentifiziert und entwederbill_to: "self"gesetzt oder ein anderes Nutzerprofil angegeben als das, auf das das Token beschränkt ist. Siehe Claude mit dem Access-Token einer Verbindung aufrufen.
Bei /v1/messages und /v1/chat/completions kann das Access-Token einer Verbindung keine Anfrage senden, die du bezahlst. Um eine abgelehnte Anfrage mit bill_to: "self" erneut zu senden, authentifiziere dich von deinem eigenen Back-End aus mit den eigenen Anmeldedaten deines Operator-Service-Kontos. Claude mit dem Access-Token einer Verbindung aufrufen listet die Ablehnungen des Tokens selbst auf.
Eine erfolgreiche Antwort gibt nicht an, wem die Anfrage in Rechnung gestellt wurde. Führe daher selbst Buch darüber, welche Anfragen du mit bill_to: "user_profile" gesendet hast.
Ursachen von user_profile_not_billable
Prüfe diese der Reihe nach:
- Deine Anfrage. Die Anfrage muss sich als Operator-Service-Konto deiner OAuth-App authentifizieren (Schritt 3). Das Access-Token einer Verbindung authentifiziert sich ebenfalls als dieses Service-Konto. Eine Anfrage, die sich auf andere Weise authentifiziert, wird abgelehnt. Beispiele sind ein anderes Service-Konto und ein API-Key, der nicht an dieses Service-Konto gebunden ist. Wenn der Header
anthropic-user-profile-ideines deiner Profile angibt, das nicht verknüpft ist, wird die Anfrage abgelehnt. Wenn die Anmeldedaten oder der Header falsch sind, korrigiere die Anfrage. Eine neue Verbindung hilft nicht. - Die Verbindung. Der Kunde hat nicht über diese App verknüpft, oder die Verbindung wurde beendet: Ein Administrator seiner Organisation oder deiner Organisation hat sie beendet, oder dein Back-End hat es getan. Eine beendete Verbindung wird auf deiner Seite User profiles als Unlinked angezeigt. Ein Profil, das nur über deine Test-App verknüpft ist, ist nicht mit deiner Produktions-App verknüpft. Stelle diesem Kunden nichts mehr in Rechnung, bis er verknüpft. Das Access-Token einer Verbindung ist auf diese Verbindung beschränkt, verwende daher nach dem erneuten Verknüpfen des Kunden das Access-Token der neuen Verbindung. Wenn deine App die reine Operator-Authentifizierung deaktiviert hat, kannst du einem Kunden nur mit dem Access-Token seiner Verbindung etwas in Rechnung stellen. Ein Kunde, für den du kein funktionierendes Token einer
billing:attribution-Verbindung besitzt, wird dann als Linked angezeigt, muss aber erneut genehmigen, wie unter Einen Kunden erneut verknüpfen beschrieben. - Die Organisation des Kunden. Sie muss ein berechtigter Kunde sein. Das kannst du von deiner Seite aus nicht sehen, also frage dein Anthropic-Account-Team.
Eine neue Verbindung funktioniert in der Regel sofort, es kann aber nach dem Austausch in Schritt 8 etwa 10 Sekunden dauern. Wenn eine Anfrage in diesen 10 Sekunden mit user_profile_not_billable abgelehnt wird, sende sie erneut. Danach ändern Warten oder erneute Versuche nichts am Ergebnis. Protokolliere die gesamte error.message und den Antwort-Header request-id jeder abgelehnten Anfrage. Wenn ein Kunde, dessen Verbindung als Linked angezeigt wird, weiterhin abgelehnt wird und deine Anfrage korrekt ist, sende die request-id einer abgelehnten Anfrage an dein Anthropic-Account-Team, damit Anthropic nachsehen kann, warum sie abgelehnt wurde.
Die Ansicht deines Kunden
Verknüpfen
Dein Nutzer genehmigt die Verbindung auf auth.claude.com, nachdem deine App ihn in Schritt 6 weitergeleitet hat. Schritt 7 listet die Bildschirme der Genehmigungsseite auf. Jeder Bildschirm zeigt den Namen deiner App und hat eine Schaltfläche Cancel. Was der Nutzer auf jedem Bildschirm tut:
- Select an organization: Der Nutzer wählt aus, welche seiner Claude-Organisationen er verknüpft. Die Seite zeigt diesen Bildschirm nur an, wenn der Nutzer zwischen Organisationen wählen kann.
- How billing works: Der Nutzer liest den Bildschirm und klickt auf Continue.
- Set a monthly spend limit: Der Nutzer gibt ein Limit für deine App in ganzen US-Dollar ein und klickt auf Continue. Das Betragsfeld ist anfangs leer, die Seite wählt also kein Limit für den Nutzer. Continue without a limit speichert kein neues Limit, und eine Obergrenze oder ein Standardwert, den der Kunde früher gespeichert hat, gilt weiterhin. Das Limit, das der Nutzer eingibt, ist die Ausgabenobergrenze, die Ausgabenobergrenzen beschreibt. Dieser Bildschirm sieht anders aus, solange sich deine App im Test befindet: siehe Solange sich deine App im Test befindet.
- Der letzte Bildschirm: Dieser Bildschirm listet auf, was deine App tun können wird, einschließlich des Limits, das der Nutzer gewählt hat. Der Nutzer klickt auf Link and authorize.
Die Genehmigungsseite verwendet das Claude-Konto, das im Browser angemeldet ist, und bietet nur die Claude-Organisationen dieses Kontos an. Dieses Konto ist möglicherweise nicht das, das dein Nutzer erwartet, zum Beispiel ein privates statt eines beruflichen Kontos. Deine App kann das Konto nicht auswählen. Die OpenID Connect-Parameter prompt=select_account und login_hint ändern nicht, welches Konto die Seite verwendet.
Nach dem Verknüpfen
Deine Kunden verwalten ihre Verbindungen auf der Seite Linked platforms in der Claude Console. Sie können die Verknüpfung mit deiner App jederzeit aufheben. Anthropic benachrichtigt dich nicht, wenn sie das tun: Du erhältst weder ein Webhook-Ereignis noch eine E-Mail.
Nachdem ein Kunde die Verknüpfung aufgehoben hat, werden Anfragen, die du diesem Kunden in Rechnung stellst, mit 403 user_profile_not_billable abgelehnt (siehe Ursachen von user_profile_not_billable). Das Nutzerprofil des Kunden wird auf deiner Seite User profiles in der Console als Unlinked angezeigt. Um erneut zu verknüpfen, führe die Schritte 5 bis 8 mit dem bestehenden Nutzerprofil des Kunden erneut aus.
E-Mails zum Verknüpfen und Aufheben der Verknüpfung
Die E-Mails von Anthropic zum Verknüpfen und Aufheben der Verknüpfung gehen an die Mitglieder der Organisation deines Kunden, die die Rolle Admin oder Billing haben. Jede E-Mail verlinkt auf die Seite Linked platforms des Kunden. Ob Anthropic eine E-Mail sendet, hängt vom Ereignis ab:
- Wenn der Kunde deine App verknüpft: Anthropic sendet eine E-Mail, wenn du den Code in Schritt 8 austauschst. Für eine Genehmigung, deren Code du nie austauschst, sendet Anthropic nichts. Es sendet auch nichts, wenn ein Nutzer erneut genehmigt, während der Kunde noch verknüpft ist.
- Wenn der Kunde die Verknüpfung mit deiner App aufhebt: Anthropic sendet eine E-Mail. Sie nennt nicht die Person, die die Verknüpfung mit deiner App aufgehoben hat.
- Wenn du die Verknüpfung des Kunden von deinem Back-End aus aufhebst: Anthropic sendet eine E-Mail.
- Wenn du die Verknüpfung des Kunden in der Console aufhebst: Anthropic sendet keine E-Mail.
Anthropic garantiert nicht, dass eine E-Mail gesendet oder zugestellt wird. Informiere deinen Kunden selbst, wenn du seine Verknüpfung aufhebst. Verlass dich nicht auf diese E-Mails, um einem Kunden mitzuteilen, dass er verknüpft ist.
Ausgabenobergrenzen
Dein Kunde kann für deine App eine monatliche Ausgabenobergrenze in US-Dollar (USD) festlegen. Die Genehmigungsseite nennt diese Obergrenze ein monatliches Ausgabenlimit, und der Nutzer, der verknüpft, kann sie dort festlegen (siehe Verknüpfen). Sie ist unabhängig vom Monthly spend limit der Organisation, das für die gesamte Organisation gilt. Du kannst weder die Obergrenze eines Kunden einsehen noch wie viel davon er bereits verbraucht hat.
Wenn die Ausgaben des Kunden über deine App die Obergrenze erreichen, lehnt die Claude API die Anfragen, die du ihm in Rechnung stellst, mit einem 402 ab. Siehe Erwartete Fehler. Die Ablehnungen dauern bis 00:00 UTC am ersten Tag des nächsten Monats an oder bis der Kunde die Obergrenze erhöht oder entfernt. Eine Änderung der Obergrenze kann etwa eine Minute dauern, bis sie wirksam wird.
Nach dem Verknüpfen verwaltet ein Mitglied der Organisation des Kunden mit der Rolle Admin oder Billing die Obergrenzen auf der Seite Linked platforms in der Console:
- Eine Obergrenze festlegen oder ändern: Das Mitglied klickt auf deine App und dann auf Set spend cap oder Edit spend cap.
- Einen Standardwert festlegen: Das Mitglied klickt unter Default spend cap auf Set default oder Edit. Jede verknüpfte App ohne eigene Obergrenze kann jeden Monat bis zum Standardwert ausgeben. Die Apps teilen sich diesen nicht.
- Eine Obergrenze entfernen: Das Mitglied klickt auf deine App, auf Edit spend cap und dann auf Remove cap. Deine App verwendet dann den Standardwert. Wenn es keinen Standardwert gibt, hat deine App keine Obergrenze.
Die kleinste Obergrenze beträgt 0 $ USD, womit jede Anfrage abgelehnt wird, die du diesem Kunden in Rechnung stellst. Die Console akzeptiert ganze Dollarbeträge, ohne praktisches Maximum. Die Obergrenze zählt Token-Kosten und Websuchgebühren zu Listenpreisen, vor etwaigen ausgehandelten Rabatten. Die Rechnung des Kunden kann vom Betrag abweichen, den die Obergrenze zählt.
Eine Obergrenze kann höher sein als das Monthly spend limit der Organisation, das der Kunde unter Ausgabenlimits festlegt. Die Claude API lehnt die Anfragen, die du dem Kunden in Rechnung stellst, ab, sobald einer der beiden Werte erreicht ist.
Solange sich deine App im Test befindet
Diese Limits gelten immer, wenn jemand deine App verknüpft oder ihre Obergrenze ändert, während sich die App im Test oder in der Prüfung befindet oder nicht genehmigt ist:
| Im Test, in der Prüfung oder nicht genehmigt | Nachdem die App live ist | |
|---|---|---|
| Ein monatliches Ausgabenlimit auf der Genehmigungsseite | Erforderlich, 50 $ USD oder weniger | Optional |
| Das Betragsfeld auf der Genehmigungsseite | Beginnt bei 50 $ USD | Anfangs leer |
| Continue without a limit auf der Genehmigungsseite | Nicht angeboten | Angeboten |
| Entfernen der Obergrenze in der Console | Nicht möglich | Möglich |
| Die höchste Obergrenze, die ein Kunde festlegen kann | 50 $ USD | Kein praktisches Maximum |
Sobald deine App live ist, bleibt eine Obergrenze, die ein Kunde zuvor gespeichert hat, bestehen. Der Kunde kann sie dann erhöhen oder entfernen.
Deine Kunden unterstützen
Du unterstützt deine Kunden bei allem, was deine App betrifft, einschließlich der Claude-Nutzung, die du ihnen in Rechnung stellst. Anthropic stellt deinen Kunden die Genehmigungsseite und die Seite Linked platforms in der Claude Console bereit. Auf der Seite Linked platforms kann ein Mitglied mit der Rolle Admin oder Billing sehen, was deine App die Organisation in diesem Monat gekostet hat. Es kann außerdem eine monatliche Ausgabenobergrenze für deine App festlegen und die Verknüpfung mit ihr aufheben. Alle anderen Fragen zu deiner App sollten an dich gehen, also teile deinen Kunden mit, wie sie dich erreichen können.
Initialisierung der Code-Snippets
Die Python-Beispiele auf dieser Seite teilen sich das folgende Setup, das du einmal schreibst. Es definiert:
- die Importe
- die Client-ID und Redirect-URI deiner App
- den Wert des Abrechnungs-Beta-Headers
- einen Claude API-Client, der sich als dein Service-Konto authentifiziert
client_assertion, das die Client-Assertion zurückgibt, die dein Back-End anauth.claude.comsendet
# Die Python-Beispiele setzen die folgende Initialisierung und Variablen voraus
import secrets
from urllib.parse import urlencode
import anthropic
import httpx
from anthropic.lib.credentials import IdentityTokenFile
from anthropic.types import Message
from anthropic.types.beta import BetaMessage
from authlib.oauth2.rfc7636 import create_s256_code_challenge
AUTH = "https://auth.claude.com"
# aus platform.claude.com kopieren, nachdem du deine OAuth-App registriert hast.
CLIENT_ID = "YOUR_CLIENT_ID"
REDIRECT_URI = "https://app.example.com/claude/billing/callback"
JWT_BEARER = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
BILLING_BETA = "user-profiles-billing-2026-10-01"
# API-Client. Das SDK tauscht das Identitäts-JWT deines Workloads gegen ein Access-
# Token und erneuert es, sodass du "Bearer <access token>" nie selbst handhaben musst.
client = anthropic.Anthropic()
# Client-Assertion für auth.claude.com: das Identitäts-JWT selbst, bei jedem Aufruf
# neu gelesen, da die Datei rotiert. Wenn die Client-Authentifizierungseinstellungen
# deiner App eine andere Audience als deine Federation-Regel nennen, verweise hier auf
# eine zweite Token-Datei: IdentityTokenFile("/path/to/other/token").
client_assertion = IdentityTokenFile()War diese Seite hilfreich?