OAuth-Referenz
Endpunkte, Client-Authentifizierung, Anfrageparameter, Scopes, Token-Antworten, Widerruf, Lebensdauern, Regeln für Redirect-URIs und Fehler.
Diese Seite fasst die Endpunkte, Parameter, Validierungsregeln und Fehlerzuordnungen für Claude Platform OAuth zusammen. Eine Schritt-für-Schritt-Anleitung findest du unter Linked billing.
Endpunkte
| Endpunkt | URL |
|---|---|
| Issuer (Aussteller) | https://identity.anthropic.com/users |
| Discovery-Dokument | https://identity.anthropic.com/users/.well-known/openid-configuration |
| Signaturschlüssel (JWKS) | Die jwks_uri im Discovery-Dokument, gehostet auf identity.anthropic.com |
| Autorisierungsendpunkt (Anmelde- und Zustimmungsseite) | https://auth.claude.com/oauth/authorize |
| Endpunkt für „pushed authorization requests“ (PAR) | https://auth.claude.com/v1/oauth/par |
| Token-Endpunkt | https://auth.claude.com/v1/oauth/token |
| Widerrufsendpunkt | https://auth.claude.com/v1/oauth/revoke |
| Claude API (Benutzerprofile und Anfragen, die einem Kunden in Rechnung gestellt werden) | https://api.anthropic.com |
Lies die Signaturschlüssel aus dem Discovery-Dokument aus, statt sie fest zu codieren. Das Discovery-Dokument führt weder den PAR-Endpunkt noch den Widerrufsendpunkt auf, verwende daher die URLs aus dieser Tabelle.
Werte des Discovery-Dokuments
| Feld | Wert |
|---|---|
issuer | https://identity.anthropic.com/users |
authorization_endpoint | https://auth.claude.com/oauth/authorize |
token_endpoint | https://auth.claude.com/v1/oauth/token |
jwks_uri | https://identity.anthropic.com/users/jwks.json |
response_types_supported | code |
grant_types_supported | authorization_code, refresh_token |
code_challenge_methods_supported | S256 |
token_endpoint_auth_methods_supported | private_key_jwt |
id_token_signing_alg_values_supported | ES256 |
scopes_supported | openid, email |
subject_types_supported | public, pairwise |
auth.claude.com gibt für Linked billing nur dann ein Refresh-Token zurück, wenn der Kunde offline_access zusammen mit billing:attribution genehmigt hat: siehe OAuth-Tokens für eine Abrechnungsverbindung.
Client-Authentifizierung
auth.claude.com authentifiziert einen vertraulichen Client mit der Methode private_key_jwt (RFC 7523). Sende diese Parameter bei jeder Anfrage an den PAR-Endpunkt, den Token-Endpunkt und den Widerrufsendpunkt. Sende niemals Anmeldedaten in einem URL-Query-String: auth.claude.com lehnt sie ab.
| Parameter | Wert |
|---|---|
client_id | Die Client-ID deiner OAuth-App |
client_assertion_type | urn:ietf:params:oauth:client-assertion-type:jwt-bearer |
client_assertion | Ein JWT von deinem Identitätsanbieter mit den Claims aus Claims der Client-Assertion |
Claims der Client-Assertion
Eine „client assertion“ (Client-Assertion) muss alle folgenden Claims enthalten, und ihr Header muss die kid eines Schlüssels in deinem JWKS enthalten.
| Claim | Anforderung |
|---|---|
iss | Die Issuer-URL deines Identitätsanbieters, genau so, wie sie über Workload Identity Federation registriert wurde |
sub | Ein Wert, der dem Subject-Muster in den Client-Authentifizierungseinstellungen deiner App entspricht, falls du eines festgelegt hast |
aud | Genau eine Audience: der Wert in den Client-Authentifizierungseinstellungen deiner App. auth.claude.com lehnt eine Assertion ab, die mehr als eine Audience aufführt. |
iat | Der Zeitpunkt, zu dem dein Identitätsanbieter das JWT ausgestellt hat |
exp | Der Ablaufzeitpunkt, höchstens 1 Stunde nach iat. Verwende nach Möglichkeit eine kürzere Lebensdauer: Wer eine Assertion abfängt, kann sie bis zu ihrem Ablauf verwenden. |
Beispiel-Payload einer Assertion:
{
"iss": "https://idp.example.com",
"sub": "workload:prod:claude-integration-backend",
"aud": "YOUR_CONFIGURED_AUDIENCE",
"iat": 1791230000,
"exp": 1791230300
}Gestalte das Subject-Muster und die Claim-Bedingungen so eng, wie es dein Back-End zulässt. auth.claude.com akzeptiert jedes JWT deines Identitätsanbieters, das ihnen entspricht, als Authentifizierung für deine App.
Parameter der Autorisierungsanfrage
Sende diese Parameter, mit Ausnahme von request_uri, im JSON-Body einer Pushed Authorization Request.
| Parameter | Linked billing | Beschreibung |
|---|---|---|
response_type | Erforderlich | Der Wert code |
client_id | Erforderlich | Die Client-ID deiner OAuth-App |
redirect_uri | Erforderlich | Eine URI, die exakt einer registrierten Redirect-URI entspricht, bis zu 2048 Zeichen |
scope | Erforderlich | Für eine Abrechnungsverbindung billing:attribution oder billing:attribution offline_access. Siehe Scopes. |
state | Erforderlich | Ein zufälliger, einmalig verwendbarer Wert mit bis zu 2048 Zeichen, den du beim Callback prüfst |
code_challenge | Erforderlich | BASE64URL(SHA256(code_verifier)), wobei der code_verifier 43 bis 128 Zeichen lang ist |
code_challenge_method | Erforderlich | Der Wert S256 |
connection_type | Erforderlich | Der Wert organization_shared. Dieser Wert fordert eine Organisationsverbindung für die Abrechnung an. |
connection_auth_target | Erforderlich | An welche Organisation die Anfragen der Verbindung weitergeleitet werden. Sende für Linked billing platform (der Eigentümer der OAuth-App). |
user_profile_id | Erforderlich | Die ID eines aktiven Benutzerprofils in deiner Organisation, das den Kunden repräsentiert |
request_uri | Erforderlich | Der Wert, den der PAR-Endpunkt zurückgegeben hat. Sende ihn zusammen mit client_id und ohne weitere Parameter an den Autorisierungsendpunkt. |
Der PAR-Endpunkt gibt HTTP 201 mit request_uri und expires_in (600 Sekunden) zurück.
Scopes
| Kategorie | Scope | Beschreibung | Verbindungstyp | Client-Typ |
|---|---|---|---|---|
| Allgemein | offline_access | Gibt der App ein Refresh-Token, das die anderen angeforderten Scopes repräsentiert. Sende ihn bei einer organization_shared-Verbindung nur zusammen mit billing:attribution. | organization_shared | Vertraulich |
| Abrechnung | billing:attribution | Eine Verbindung, über die du der Claude-Organisation eines Kunden die Claude API-Anfragen in Rechnung stellen kannst, die du auf Anweisung des Kunden stellst. Sende ihn allein oder zusammen mit offline_access, um zusätzlich ein Refresh-Token zu erhalten. Siehe OAuth-Tokens für eine Abrechnungsverbindung. | organization_shared | Vertraulich |
| Abrechnung | org:billing_attribution | Abgekündigt: Verwende billing:attribution. | organization_shared | Vertraulich |
Token-Anfrage und -Antwort
Sende Token-Anfragen mit einem JSON-Body an https://auth.claude.com/v1/oauth/token.
| Parameter | Wert |
|---|---|
grant_type | authorization_code |
code | Der Code aus dem Callback |
redirect_uri | Dieselbe redirect_uri, die du in der Autorisierungsanfrage gesendet hast |
code_verifier | Der PKCE-Code-Verifier |
client_id, client_assertion_type, client_assertion | Wie unter Client-Authentifizierung |
Die Token-Antwort enthält diese Felder:
| Antwortfeld | Linked billing |
|---|---|
access_token | Das Zugriffstoken der Verbindung |
token_type | Bearer |
expires_in | Höchstens 3600 |
scope | workspace:inference |
connection_id | Die Verbindungs-ID, zum Beispiel ocon_EXAMPLE. Speichere sie. |
refresh_token | Wird nur zurückgegeben, wenn der Kunde offline_access genehmigt hat |
refresh_token_expires_in | Sekunden bis zum Ablauf von refresh_token. Nicht vorhanden, wenn es kein refresh_token gibt. |
Zum Aktualisieren sendest du grant_type mit dem Wert refresh_token, dein refresh_token und die Parameter aus Client-Authentifizierung. Eine Aktualisierung einer Abrechnungsverbindung folgt den Regeln unter OAuth-Tokens für eine Abrechnungsverbindung.
OAuth-Tokens für eine Abrechnungsverbindung
Bei einer Abrechnungsverbindung gibt der Token-Endpunkt das Zugriffstoken der Verbindung zurück. Das Token authentifiziert sich als Operator-Servicekonto deiner App, in dem Workspace, den die Einstellung connection_token_workspace_id der App angibt. Bei /v1/messages und /v1/chat/completions wird eine Anfrage damit dem Kunden dieser Verbindung in Rechnung gestellt und keinem anderen. Wenn der Kunde zusätzlich offline_access genehmigt hat, gibt der Token-Endpunkt auch ein Refresh-Token zurück, und der refresh_token-Grant erneuert beide Tokens. Die Einrichtung und eine Schritt-für-Schritt-Anleitung findest du unter OAuth-Token für jede Verbindung auf der Seite zu Linked billing.
Beide Grants verwenden die Parameter aus Token-Anfrage und -Antwort, mit Client-Authentifizierung. Eine Aktualisierung darf keinen scope-Parameter senden. Die Token-Antwort enthält diese Felder:
| Antwortfeld | Wert |
|---|---|
access_token | Das Zugriffstoken der Verbindung |
token_type | Bearer |
expires_in | Sekunden bis zum Ablauf des Zugriffstokens, höchstens 3600 |
scope | Immer workspace:inference |
connection_id | Die Verbindungs-ID, zum Beispiel ocon_EXAMPLE. Nur der authorization_code-Grant gibt sie zurück. |
refresh_token | Das Refresh-Token der Verbindung. Wird nur zurückgegeben, wenn der Kunde offline_access genehmigt hat. |
refresh_token_expires_in | Sekunden bis zum Ablauf von refresh_token |
Jede Aktualisierung gibt ein neues access_token und ein neues refresh_token zurück. Das Refresh-Token, das du gesendet hast, wird ersetzt, und das frühere Zugriffstoken funktioniert innerhalb weniger Minuten nicht mehr. Du kannst das ersetzte Refresh-Token noch ein weiteres Mal senden, innerhalb von 30 Sekunden nach der Aktualisierung, die es ersetzt hat, um eine Anfrage zu wiederholen, deren Antwort dir verloren gegangen ist. Diese zweite Anfrage gibt ein weiteres neues Paar zurück und widerruft das Paar aus der verlorenen Antwort: Verwende nur das neueste Paar. Eine dritte Anfrage mit dem ersetzten Token erhält invalid_grant, ebenso eine zweite Anfrage, die nach den 30 Sekunden eingeht. Innerhalb der 30 Sekunden widerruft eine solche Anfrage nichts. Nach den 30 Sekunden widerruft sie jedes Token der Verbindung und beendet die Verbindung. Die Token aktualisieren beschreibt die Regeln und Fehler einer Aktualisierung.
Jedes dieser Ereignisse widerruft die Tokens der Verbindung, einschließlich des aktuellen Zugriffstokens:
- Der Kunde oder du hebt die Verknüpfung auf.
- Der Kunde genehmigt eine neue Autorisierungsanfrage mit anderen Scopes für dasselbe Benutzerprofil, und du tauschst den Code dieser Genehmigung ein. Die neue Verbindung tritt an die Stelle der früheren.
- Der Workspace, in dem die Tokens laufen, wird archiviert.
Wie die Claude API eine Anfrage mit dem Zugriffstoken einer Verbindung abrechnet, erfährst du unter Claude mit dem Access-Token einer Verbindung aufrufen.
Widerruf
Sende Widerrufsanfragen mit einem JSON- oder formularcodierten Body an https://auth.claude.com/v1/oauth/revoke. Der Endpunkt folgt RFC 7009 und akzeptiert außerdem Verbindungs- und Benutzerprofil-IDs.
Sende die Parameter aus Client-Authentifizierung und genau einen der Parameter aus dieser Tabelle. Das aud der Client-Assertion ist der Wert in den Client-Authentifizierungseinstellungen deiner App, nicht die Widerrufs-URL.
| Parameter | Was er beendet |
|---|---|
connection_id | Eine der Verbindungen deiner App, angegeben als ocon_-ID |
user_profile_id | Alle Verbindungen deiner App auf einem Benutzerprofil, angegeben als uprof_-ID |
token | Sende bei Linked billing stattdessen connection_id oder user_profile_id: Das Senden eines Zugriffstokens beendet die Verbindung möglicherweise nicht. |
auth.claude.com akzeptiert token_type_hint und ignoriert ihn.
Der Endpunkt gibt HTTP 200 und die IDs der Verbindungen zurück, die die Anfrage beendet hat:
{
"revoked_connection_ids": ["ocon_EXAMPLE"]
}Die Liste ist leer, wenn das Token oder die ID unbekannt ist oder zu einer anderen App gehört, wenn die Verbindung bereits beendet wurde oder wenn die Anfrage ein Token, aber keine Verbindung beendet hat. Die Antwort gibt nicht an, welches davon zutrifft.
Nachdem eine Abrechnungsverbindung beendet wurde, lehnt die Claude API Anfragen, die diesem Kunden in Rechnung gestellt werden, mit user_profile_not_billable ab, und die OAuth-Tokens der Verbindung funktionieren nicht mehr. Verlasse dich danach nicht auf ein Zugriffstoken aus einer Verbindung, die mit dem abgekündigten Scope org:billing_attribution genehmigt wurde: Es funktioniert möglicherweise sofort nicht mehr oder bis zu seinem Ablauf weiter.
Lebensdauern
| Element | Lebensdauer |
|---|---|
request_uri vom PAR-Endpunkt | 10 Minuten, einmalig verwendbar |
| Autorisierungscode | 5 Minuten, einmalig verwendbar |
access_token | Bis zu 1 Stunde |
refresh_token | Bis zu 1 Jahr ab dem Code-Austausch. Eine Aktualisierung verlängert diese Dauer nicht. |
Dies sind die aktuellen Werte. Lies expires_in und refresh_token_expires_in aus jeder Antwort aus, statt dich auf feste Werte zu verlassen.
Regeln für Redirect-URIs
- Jede
redirect_urimuss exakt einer in deiner App registrierten URI entsprechen.auth.claude.comverwendet keinen Wildcard- oder Präfixabgleich. - Jede Redirect-URI muss HTTPS verwenden und darf kein Fragment enthalten. URIs für die lokale Entwicklung auf
localhost,127.0.0.1oder[::1]dürfen HTTP verwenden. - Eine URI für die lokale Entwicklung, die mit einem Sternchen als Port registriert ist, etwa
http://localhost:*/callback, passt zu jedem Port. - Du kannst pro App bis zu 10 Redirect-URIs registrieren.
auth.claude.comsendet Fehler nur dann an deine Redirect-URI, wenn dieredirect_urieiner registrierten URI entspricht. Bei jeder anderenredirect_urileitetauth.claude.comden Browser nicht weiter.
Fehler
Fehler bei der Weiterleitung
auth.claude.com gibt Fehler als Query-Parameter error, error_description und state an deiner Redirect-URI zurück. Es handelt sich um Standardfehler von OAuth 2.0 (RFC 6749), mit Ausnahme von user_profile_already_linked, der spezifisch für Anthropic ist.
| Fehler | Wann | Was du deinem Benutzer anzeigen solltest |
|---|---|---|
access_denied | Die Person hat abgelehnt oder kann diese Anfrage nicht genehmigen. Bei einer Abrechnungsverbindung muss die Person Administrator einer Claude-Organisation sein. | Erkläre, dass die Verbindung nicht abgeschlossen wurde, und gehe nicht davon aus, dass die Person abgelehnt hat. Bei einer Abrechnungsverbindung gehe vor wie unter Deine Redirect-URI erhält error=access_denied im Leitfaden zu Linked billing beschrieben, der die Ursachen auflistet und angibt, was du der Person mitteilen solltest. Andernfalls bitte die Person, dich zu kontaktieren. |
server_error | auth.claude.com konnte die Anfrage nicht verarbeiten. | Bitte den Benutzer, es erneut zu versuchen. |
user_profile_already_linked | Nur bei Linked billing. Die Organisation des Kunden ist bereits über ein anderes Benutzerprofil mit deiner App verknüpft. Jede Kundenorganisation kann eine Verbindung zu deiner App haben. auth.claude.com hat den Administrator bereits gebeten, dich zu kontaktieren. | Erkläre, dass die Organisation bereits mit deiner App verknüpft ist. |
Wenn die request_uri abgelaufen ist oder du sie bereits verwendet hast, zeigt auth.claude.com eine Fehlerseite an und leitet den Browser nicht zu deiner App zurück. Starte den Ablauf mit einer neuen Pushed Authorization Request erneut.
Fehler vom PAR- und Token-Endpunkt
Diese Endpunkte geben einen JSON-Body mit error und error_description zurück.
| Fehler | Wann |
|---|---|
invalid_request | Ein erforderlicher Parameter fehlt oder ist ungültig, zum Beispiel ein fehlender state oder eine fehlende PKCE-Challenge oder eine user_profile_id, die nicht die ID eines aktiven Benutzerprofils in deiner Organisation ist. |
invalid_client | auth.claude.com konnte deine App nicht authentifizieren: Die Client-ID ist unbekannt oder die Client-Assertion hat die Überprüfung nicht bestanden. Prüfe iss, sub und aud der Assertion anhand der Client-Authentifizierungseinstellungen deiner App und prüfe, ob dein Identitätsanbieter sie mit einem Schlüssel aus deinem JWKS signiert hat. |
invalid_scope | Der angeforderte Scope ist für diese App oder diesen Verbindungstyp nicht zulässig. Bei den Tokens einer Abrechnungsverbindung bedeutet dies auch, dass eine Aktualisierung einen scope-Parameter gesendet hat, den sie nicht akzeptiert, oder dass billing:attribution für deine App nicht mehr registriert ist. Beim Code-Austausch verbraucht diese zweite Ursache den Code. |
invalid_grant | Der Code ist abgelaufen, du hast ihn bereits verwendet oder er passt nicht zur redirect_uri oder zum code_verifier. Bei einer Aktualisierung ist das Refresh-Token abgelaufen oder nicht mehr gültig: gehe vor wie unter Die Token aktualisieren beschrieben. |
unauthorized_client | Deine App ist für diese Anfrage nicht eingerichtet. Prüfe bei Linked billing zuerst das Operator-Servicekonto der App und dessen Workspace: siehe Der Code-Austausch gibt unauthorized_client zurück. Bei den Tokens einer Abrechnungsverbindung nennt error_description die Ursache, zum Beispiel einen fehlenden Workspace. Diese Ablehnung verbraucht keinen Code und widerruft kein Refresh-Token. |
user_profile_already_linked | Nur bei Linked billing, vom Token-Endpunkt. Zwischen der Genehmigung und dieser Anfrage wurde das Benutzerprofil über eine andere Kundenorganisation mit deiner App verknüpft, oder die Organisation des Kunden wurde über ein anderes Benutzerprofil verknüpft. |
Wenn auth.claude.com eine Anfrage aufgrund eines Ratenlimits ablehnt, einen Ausfall hat oder einen unbekannten grant_type oder einen Parameter erhält, der länger als das zulässige Limit ist, gibt es einen Fehler in einem anderen Format zurück, das möglicherweise kein JSON ist. Wiederhole Anfragen nur bei HTTP-429- und 5xx-Antworten, mit Backoff. Behandle jeden anderen Status als Fehler in der Anfrage. Bei einer Aktualisierung einer Abrechnungsverbindung gehe statt mit einem allgemeinen Backoff so vor, wie unter Die Token aktualisieren beschrieben. Wenn die Antwort einen retry-after-Header enthält, warte mindestens so lange. Sende die nächste Anfrage aus deinem eigenen Code und verlasse dich nicht auf die automatischen Wiederholungen einer HTTP-Client-Bibliothek: Sie werden bei einer solchen Antwort möglicherweise nicht ausgeführt. Die Token aktualisieren beschreibt auch, wann eine Wiederholung sicher ist, denn ein bereits verwendetes Refresh-Token kann die Verbindung beenden, wenn du es erneut sendest.
Fehler vom Widerrufsendpunkt
Bei den meisten Anfragen, die auth.claude.com ablehnt, gibt der Widerrufsendpunkt HTTP 400 und einen JSON-Body mit error und error_description zurück.
| Fehler | Wann |
|---|---|
invalid_request | Ein erforderlicher Parameter fehlt oder ist ungültig, zum Beispiel eine fehlende client_id. Die Anfrage sendet keinen von token, connection_id und user_profile_id oder mehr als einen davon. Eine ID ist fehlerhaft, zum Beispiel hat sie das falsche Präfix. Anmeldedaten oder ein token stehen im URL-Query-String. Das Benutzerprofil hat zu viele Verbindungen für eine Anfrage: Die Anfrage hat möglicherweise einige davon beendet, beende daher die übrigen mit connection_id. |
invalid_client | auth.claude.com konnte deine App nicht authentifizieren. Was zu prüfen ist, findest du unter invalid_client in Fehler vom PAR- und Token-Endpunkt. |
unauthorized_client | Deine App ist für diese Anfrage nicht eingerichtet. Wende dich an dein Anthropic-Account-Team. |
Die Antworten in der nächsten Tabelle verwenden ein anderes Format, das möglicherweise kein JSON ist. Wenn der Body JSON ist, ist error ein Objekt, kein String.
| Status | Wann | Was zu tun ist |
|---|---|---|
| 400 | Ein Parameter ist länger als sein Limit. | Korrigiere die Anfrage. Wiederhole sie nicht. |
| 429 | Zu viele fehlgeschlagene Anfragen kamen von deiner IP-Adresse. | Wiederhole die Anfrage mit Backoff. |
| 500 | auth.claude.com konnte die Anfrage nicht verarbeiten. | Wiederhole die Anfrage mit Backoff. Wenn das weiterhin auftritt, wende dich an dein Anthropic-Account-Team. |
| 501 | Anthropic hat diesen Endpunkt für deine Organisation nicht aktiviert. | Wiederhole die Anfrage nicht. Wende dich an dein Anthropic-Account-Team. |
| 503 | Die Anfrage wurde nicht abgeschlossen. Alles, was sie beendet hat, bleibt beendet. | Wiederhole die Anfrage mit Backoff, mit denselben Parametern und einer neuen Client-Assertion. Die Wiederholung schließt den Rest ab, und ihre Liste lässt Verbindungen weg, die die frühere Anfrage beendet hat. Wenn du user_profile_id gesendet hast, wiederhole sie innerhalb eines Tages: Danach kann eine Wiederholung 200 mit einer leeren Liste zurückgeben und nichts abschließen. Eine Wiederholung mit jeder connection_id funktioniert jederzeit. |
Abrechnungsfehler
Diese gelten für Claude API-Anfragen, die billing_policy.bill_to auf "user_profile" setzen oder sich mit dem Zugriffstoken einer Abrechnungsverbindung authentifizieren. Die Claude API stellt für eine abgelehnte Anfrage keiner der beiden Organisationen etwas in Rechnung. Keine der 402- und 403-Antworten kann wiederholt werden, mit Ausnahme einer user_profile_not_billable-Ablehnung in den ersten 10 Sekunden nach einer neuen Verbindung.
| Status | Fehlertyp und -code | Wann |
|---|---|---|
| 400 | invalid_request_error | Die Anfrage sendet billing_policy ohne den Beta-Header user-profiles-billing-2026-10-01. Oder dem billing_policy-Objekt fehlt ein Feld oder es enthält ein ungültiges Feld. Mit dem Zugriffstoken einer Abrechnungsverbindung kann bill_to weggelassen werden. Oder die Anfrage verwendet Code-Ausführung außerhalb der zulässigen Kombination. |
| 400 | invalid_request_error, user_profile_required | bill_to ist "user_profile", die Anfrage enthält keine Benutzerprofil-ID, und sie authentifiziert sich nicht mit dem Zugriffstoken einer Abrechnungsverbindung. |
| 400 | invalid_request_error, ohne Fehlercode | Die Anfrage authentifiziert sich mit dem Zugriffstoken einer Abrechnungsverbindung und setzt entweder bill_to auf "self" oder nennt ein anderes Benutzerprofil als das, auf das das Token beschränkt ist. Jede dieser beiden Ablehnungen gibt in error.message an, was falsch ist. |
| 401 | authentication_error | Die Anfrage authentifiziert sich mit dem Zugriffstoken einer Abrechnungsverbindung, das abgelaufen ist, durch eine Aktualisierung ersetzt wurde oder dessen Verbindung beendet wurde. Die Meldung gibt an, ob das Token abgelaufen ist oder widerrufen wurde. Sende die Anfrage erneut mit dem aktuellen Zugriffstoken, oder verknüpfe den Kunden erneut, wenn die Verbindung beendet wurde. Nachdem eine Verbindung beendet wurde, kann jede neue Anfrage mit ihrem Zugriffstoken diesen 401 oder einen 403 user_profile_not_billable erhalten, in keiner festen Reihenfolge. |
| 402 | billing_error, linked_organization_spend_limit_reached | Die Kundenorganisation hat ein von ihr festgelegtes Ausgabenlimit erreicht, entweder für deine OAuth-App oder für die gesamte Organisation. Die Claude API sendet denselben Code, wenn die Organisation kein Guthaben hat, mit dem die Anfrage bezahlt werden kann. Die Antwort gibt nicht an, was davon zutrifft. Bitte den Kunden, beide Limits und sein Guthaben zu überprüfen. Der Abschnitt Erwartete Fehler zu Linked billing beschreibt, wo jedes Limit festgelegt wird und was zu ändern ist. |
| 402 | billing_error, linked_organization_billing_unavailable | Anthropic kann der Kundenorganisation derzeit keine Rechnung stellen, weil es ein Problem mit dem eigenen Anthropic-Konto dieser Organisation gibt. Derselbe Code beendet eine Antwort, die Claude bereits begonnen hat, wenn das Guthaben der Organisation aufgebraucht ist. Bitte den Kunden, seinen Abrechnungsstatus bei Anthropic zu prüfen. |
| 403 | permission_error, ohne Fehlercode | Anthropic stellt deiner Organisation nicht direkt Rechnungen, daher kann es Kunden nicht in deinem Namen Rechnungen stellen. |
| 403 | permission_error, user_profile_not_billable | Das Benutzerprofil hat keine Verbindung zu einer Kundenorganisation, ein Administrator oder dein Back-End hat die Verbindung beendet, die Kundenorganisation zahlt Anthropic nicht direkt für ihre API-Nutzung (Prepaid-Guthaben und Abrechnung per Rechnung zählen beide), oder die Anfrage authentifiziert sich nicht als Servicekonto deiner App. Die Antwort gibt nicht an, welches davon zutrifft. Auch das Zugriffstoken einer Verbindung kann diesen Fehler erhalten, nachdem die Verbindung beendet wurde. Der Abschnitt Ursachen von user_profile_not_billable beschreibt, was jeweils zu prüfen ist. |
| 503 | overloaded_error | Die Claude API kann vorübergehend nicht bestätigen, ob sie dem Kunden eine Rechnung stellen kann. Wiederhole die Anfrage. Wenn die Antwort einen retry-after-Header enthält, warte so lange, bevor du es erneut versuchst. |
Bei /v1/messages steht der Fehlercode in error.details.error_code. Bei /v1/chat/completions ist error.type immer invalid_request_error, error.code enthält den Anthropic-Fehlertyp (zum Beispiel permission_error oder billing_error), und die Antwort hat keinen Fehlercode. Gleiche daher den HTTP-Status und error.code ab.
Standards
| Standard | Wo er gilt |
|---|---|
| OAuth 2.0 (RFC 6749) | Autorisierungscode-Ablauf, Token-Endpunkt und Fehlerantworten |
| PKCE (RFC 7636) | Mit S256 bei jeder Autorisierungsanfrage erforderlich |
| Pushed Authorization Requests (RFC 9126) | Erforderlich für Linked billing. |
| Token-Widerruf (RFC 7009) | Der Widerrufsendpunkt, der außerdem Verbindungs- und Benutzerprofil-IDs akzeptiert und die IDs der Verbindungen zurückgibt, die er beendet hat |
| JWT-Client-Authentifizierung (RFC 7523) | Die private_key_jwt-Client-Authentifizierung am PAR-, Token- und Widerrufsendpunkt sowie der Token-Austausch des Servicekontos für Anfragen, die einem Kunden in Rechnung gestellt werden |
Auf diesen Seiten verwendete Begriffe
Die folgenden Bedeutungen gelten nur für Claude Platform OAuth.
| Begriff | Bedeutung |
|---|---|
| Claude-Organisation | Ein Organisationskonto bei Anthropic. Dein Unternehmen hat eines, ebenso jeder Kunde, der seine Organisation für die Abrechnung verknüpft. |
| Administrator | Ein Mitglied einer Claude-Organisation mit der Rolle Admin oder Abrechnung. |
| OAuth-App | Die Registrierung in deiner Claude-Organisation, die dein Produkt gegenüber auth.claude.com identifiziert. Sie hat eine Client-ID, einen Namen, ein Logo, eine Homepage-URL, Redirect-URIs und die unterstützten Verbindungstypen. |
| Verbindungstyp | Wer eine Verbindung genehmigt: ein Administrator im Namen einer ganzen Organisation (organization_shared, für Linked billing). |
| Identitätsanbieter | Der Dienst in deiner eigenen Infrastruktur, der kurzlebige JWTs für dein Back-End signiert und seine öffentlichen Schlüssel als JSON Web Key Set (JWKS) veröffentlicht, etwa der Workload-Identity-Dienst deines Cloud-Anbieters oder dein eigener OIDC-konformer Issuer. Auf diesen Seiten bezeichnet „dein Identitätsanbieter“ immer diesen Dienst, nicht Anthropic. |
| Client-Assertion | Ein kurzlebiges JWT, das dein Identitätsanbieter signiert und dein Back-End sendet, um deine OAuth-App zu authentifizieren. Dies ist die Client-Authentifizierungsmethode private_key_jwt (RFC 7523). |
| Pushed Authorization Request (PAR) | Eine Anfrage, bei der dein Back-End die Autorisierungsparameter direkt an auth.claude.com sendet und eine request_uri erhält, die bei der Browser-Weiterleitung verwendet wird (RFC 9126). |
| Workload Identity Federation | Die Funktion der Claude Console, über die deine Organisation deinen Identitätsanbieter registriert, sodass Anthropic JWTs akzeptiert, die mit den Schlüsseln in deinem JWKS signiert sind. |
| Discovery-Dokument | Das OIDC-Dokument, das den Issuer, die Endpunkte und die Signaturschlüssel von Anthropic auflistet. |
| Benutzerprofil | Ein Datensatz, den du in deiner eigenen Claude-Organisation erstellst, um einen deiner Kunden zu repräsentieren. Eine Abrechnungsverbindung verknüpft ein Benutzerprofil mit der Claude-Organisation des Kunden. |
| Servicekonto | Ein nicht-menschliches Konto in deiner Claude-Organisation. Bei Linked billing ist deine OAuth-App mit einem Servicekonto verknüpft, ihrem Operator-Servicekonto, und dein Back-End authentifiziert sich als dieses Servicekonto, wenn es eine Anfrage sendet, die einem Kunden in Rechnung gestellt wird. |
| OAuth-Tokens der Verbindung | Das Zugriffstoken, das auth.claude.com für eine Abrechnungsverbindung zurückgibt, und das Refresh-Token, das es zurückgibt, wenn der Kunde zusätzlich offline_access genehmigt hat. Das Zugriffstoken authentifiziert sich als Operator-Servicekonto und kann nur über das Benutzerprofil dieser Verbindung abrechnen. Siehe OAuth-Tokens für eine Abrechnungsverbindung. |
War diese Seite hilfreich?