---
title: Linked billing
url: https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections
description: 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.
---

<Warning>
  Claude Platform OAuth ist ein Beta Service: Vorabversions-Software, die im Rahmen deiner Vereinbarung mit Anthropic bereitgestellt wird, etwa den [Commercial Terms of Service](https://www.anthropic.com/legal/commercial-terms), und den [Service Specific Terms](https://www.anthropic.com/legal/service-specific-terms). Endpunkte, Parameter und Verhalten können sich während der Beta ändern. Es ist möglicherweise nicht für den Produktiveinsatz geeignet.
</Warning>

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`](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#step-3-update-calls-to-claude)-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](https://platform.claude.com/docs/de/manage-claude/api-and-data-retention#zero-data-retention-zdr-scope), 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](https://platform.claude.com/docs/de/about-claude/pricing#code-execution-tool) verwenden (die API gibt einen 400 zurück). Sende diese Anfragen daher mit `bill_to: "self"` oder ohne `billing_policy`.
* `/v1/chat/completions`
* `/v1/messages/count_tokens` akzeptiert das Feld `billing_policy` und ignoriert es, sodass du Token genau für den Body zählen kannst, den du gleich senden wirst.

[Message Batches](https://platform.claude.com/docs/de/build-with-claude/batch-processing) (`/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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#expected-errors).

## Einrichtungsprozess

Diese drei Schritte führst du einmalig aus. Sie registrieren deine App bei Anthropic. Danach erklärt [Welches Nutzerprofil verknüpft wird](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#which-user-profile-to-link) 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](https://platform.claude.com/settings/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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#publish-your-app) und sie live ist, zeigt die Einstellung **Any Claude user** an.

<Note>
  Eine Organisation kann mehrere OAuth-Apps registrieren, zum Beispiel eine für die Produktion und eine zum Testen. Jede App hat ihre eigenen Verbindungen: Ein Kunde, der deine Test-App verknüpft, ist nicht mit deiner Produktions-App verknüpft. Behalte Linked billing für die gesamte Lebensdauer deiner Integration auf einer einzigen Produktions-App.
</Note>

### 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.

<Note>
  Deine App authentifiziert sich an den PAR-, Token- und Widerrufsendpunkten mit einer Variante der Methode `private_key_jwt` (RFC 7523): Mit jeder Anfrage sendet dein Back-End eine „client assertion“ (Client-Assertion), ein JWT, das dein Identitätsanbieter ausstellt. `auth.claude.com` prüft die Signatur des Tokens mit den für diesen Aussteller registrierten Schlüsseln und gleicht es mit den hier festgelegten Subject- oder Claim-Bedingungen ab. Welche Claims eine Client-Assertion enthalten muss, findest du unter [Claims der Client-Assertion](https://platform.claude.com/docs/de/manage-claude/oauth-apps/oauth-reference#client-assertion-claims).
</Note>

### 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](https://platform.claude.com/docs/de/manage-claude/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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection). Bevor du Kunden verknüpfst, [lege einen Workspace](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens) 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](https://platform.claude.com/docs/de/manage-claude/user-profiles).

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`](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#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, setze [`metadata.user_id`](https://platform.claude.com/docs/de/api/messages/create) 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#code-snippet-initialization). 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/branding-samples#buttons)). 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#test-as-a-customer).

<Frame>
  ![Sequenzdiagramm der Schritte 5 bis 8: die Genehmigungsanfrage, die Genehmigung durch den Nutzer und der Austausch gegen eine „connection ID“ (Verbindungs-ID)](https://platform.claude.com/docs/de/images/oauth-apps-billing-connection-flow.svg)
</Frame>

### 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#which-user-profile-to-link).

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/user_profiles \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "anthropic-version: 2026-10-21" \
    -H "content-type: application/json" \
    -d '{
      "name": "Example Customer Inc.",
      "external_user_details": {"reference_id": "your-customer-id-123"}
    }'
  ```

  ```bash CLI
  ant user-profiles create \
    --name "Example Customer Inc." \
    --external-user-details.reference-id your-customer-id-123
  ```

  ```python Python
  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")
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const profile = await client.userProfiles.create({
    name: "Example Customer Inc.",
    external_user_details: { reference_id: "your-customer-id-123" }
  });

  console.log(profile.id); // "uprof_..."
  ```

  ```csharp C#
  AnthropicClient client = new();

  var profile = await client.UserProfiles.Create(
      new()
      {
          Name = "Example Customer Inc.",
          ExternalUserDetails = new() { ReferenceID = "your-customer-id-123" },
      }
  );

  Console.WriteLine(profile.ID);
  ```

  ```go Go
  client := anthropic.NewClient()

  profile, err := client.UserProfiles.New(context.Background(), anthropic.UserProfileNewParams{
  	Name: anthropic.String("Example Customer Inc."),
  	ExternalUserDetails: anthropic.UserProfileExternalUserDetailsParams{
  		ReferenceID: anthropic.String("your-customer-id-123"),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Println(profile.ID)
  ```

  ```java Java
  import com.anthropic.models.userprofiles.UserProfileCreateParams;
  import com.anthropic.models.userprofiles.UserProfileExternalUserDetailsParams;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      var params = UserProfileCreateParams.builder()
          .name("Example Customer Inc.")
          .externalUserDetails(UserProfileExternalUserDetailsParams.builder()
              .referenceId("your-customer-id-123")
              .build())
          .build();
      var profile = client.userProfiles().create(params);

      IO.println(profile.id());
  }
  ```

  ```php PHP
  $client = new Client();

  $profile = $client->userProfiles->create(
      name: 'Example Customer Inc.',
      externalUserDetails: ['referenceID' => 'your-customer-id-123'],
  );

  echo $profile->id, PHP_EOL;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  profile = client.user_profiles.create(
    name: "Example Customer Inc.",
    external_user_details: { reference_id: "your-customer-id-123" }
  )

  puts(profile.id)
  ```
</CodeGroup>

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](https://platform.claude.com/docs/de/manage-claude/user-profiles#decide-who-gets-a-profile).

Die Antwort enthält die `id` des Profils, zum Beispiel `uprof_01HV9Z`.

<Note>
  Jede Erstellungsanfrage legt ein neues Profil an, selbst mit derselben `reference_id` (deiner eigenen ID für den Kunden). Verwende daher die gespeicherte ID wieder, anstatt bei jedem Verbindungsversuch ein Profil zu erstellen.
</Note>

### 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.

<CodeGroup exclude="shell:CLI, typescript, csharp, go, java, php, ruby">
  ```bash cURL
  curl https://auth.claude.com/v1/oauth/par \
    -H "content-type: application/json" \
    -d '{
      "response_type": "code",
      "client_id": "YOUR_CLIENT_ID",
      "redirect_uri": "https://app.example.com/claude/billing/callback",
      "scope": "billing:attribution",
      "connection_type": "organization_shared",
      "connection_auth_target": "platform",
      "user_profile_id": "uprof_01HV9Z",
      "state": "RANDOM_STATE",
      "code_challenge": "BASE64URL_SHA256_OF_VERIFIER",
      "code_challenge_method": "S256",
      "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
      "client_assertion": "YOUR_CLIENT_ASSERTION_JWT"
    }'
  ```

  ```python Python
  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)
  ```
</CodeGroup>

`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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#scopes-for-a-billing-connection). 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.

<Note>
  Die Person, die die Genehmigung erteilt, muss Administrator der Claude-Organisation des Kunden sein: ein Mitglied mit der Rolle Admin oder Billing.
</Note>

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.

```python
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 URL
```

### Schritt 7: Der Nutzer erteilt die Genehmigung

Deine App tut in diesem Schritt nichts. Der Nutzer durchläuft diese Schritte auf `auth.claude.com`:

1. Der Nutzer meldet sich bei Claude an, es sei denn, der Browser ist bereits angemeldet.

2. 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#connecting).

   1. **Select an organization**, nur wenn der Nutzer eine Auswahl an Organisationen hat.
   2. **How billing works**.
   3. **Set a monthly spend limit**.
   4. Ein letzter Bildschirm mit der Schaltfläche **Link and authorize**.

3. Wenn der Nutzer auf **Link and authorize** klickt, schickt `auth.claude.com` den 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#if-linking-doesnt-complete).

<Note>
  Die Verbindung gehört der gesamten Claude-Organisation, nicht dem Nutzer, der sie genehmigt hat. Wenn dieser Nutzer die Organisation verlässt, bleibt die Verbindung aktiv. Jeder Administrator der Organisation des Kunden oder deiner Organisation kann die Verbindung jederzeit beenden, und dein Back-End kann das ebenfalls.
</Note>

### 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#if-linking-doesnt-complete).

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.

<CodeGroup exclude="shell:CLI, typescript, csharp, go, java, php, ruby">
  ```bash cURL
  curl https://auth.claude.com/v1/oauth/token \
    -H "content-type: application/json" \
    -d '{
      "grant_type": "authorization_code",
      "code": "AUTH_CODE",
      "code_verifier": "ORIGINAL_CODE_VERIFIER",
      "redirect_uri": "https://app.example.com/claude/billing/callback",
      "client_id": "YOUR_CLIENT_ID",
      "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
      "client_assertion": "YOUR_CLIENT_ASSERTION_JWT"
    }'
  ```

  ```python Python
  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"]
  ```
</CodeGroup>

Die Antwort enthält die Verbindungs-ID und [das Access-Token der Verbindung](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection), 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#keep-the-tokens-from-step-8) 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#call-claude-with-a-connections-access-token) 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#eligible-customers-and-endpoints). Unter [Aufrufe an Claude anpassen](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#step-3-update-calls-to-claude) und [Erwartete Fehler](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#expected-errors) 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#code-exchange-unauthorized-client).

<Note>
  Ein Nutzer kann für ein bereits verknüpftes Nutzerprofil erneut die Genehmigung erteilen. Das Ergebnis hängt von den Scopes ab:

  * Erneute Genehmigung für dasselbe Nutzerprofil und dieselben Scopes: Die Verbindung bleibt bestehen, und die Token-Antwort gibt dieselbe `connection_id` und ein neues Access-Token zurück. Die Ausnahme ist eine Verbindung mit `billing:attribution offline_access`: Der Code-Austausch gibt `invalid_grant` zurück, die Verbindung bleibt unverändert, und [Einen Kunden erneut verknüpfen](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again) beschreibt, was zu tun ist.
  * Erneute Genehmigung für dasselbe Nutzerprofil mit anderen Scopes, zum Beispiel `billing:attribution offline_access` nach `billing:attribution`: Dein Austausch des neuen Codes erstellt eine neue Verbindung mit einer neuen `connection_id`, die an die Stelle der früheren tritt. Die Token einer früheren `billing:attribution`-Verbindung werden widerrufen. Speichere die neue `connection_id` anstelle der früheren. Wenn der Austausch mit einer 5xx-Antwort fehlschlägt, führe die Schritte 5 bis 8 erneut aus. [Scopes für eine Abrechnungsverbindung](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#scopes-for-a-billing-connection) erklärt, wann du das brauchst.
  * Nachdem eine Verbindung widerrufen wurde, kannst du dasselbe Nutzerprofil erneut verknüpfen.
</Note>

### 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#eligible-customers-and-endpoints) 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#while-your-app-is-in-testing) 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](https://platform.claude.com/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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/oauth-reference#errors) 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:

1. Der Nutzer klickt auf einem der Genehmigungsbildschirme auf **Cancel**.

2. 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#test-as-a-customer).
   * 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#disconnecting-a-customer) 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_uri` ist 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens) | 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#keep-the-tokens-from-step-8) und [Die Token aktualisieren](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#refresh-the-connection).

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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection) 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#call-claude-with-a-connections-access-token). 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.

<Warning>
  Prüfe, dass der Header das Profil des Kunden angibt, für den die Anfrage bestimmt ist. Standardmäßig können die eigenen Anmeldedaten deines Operator-Service-Kontos jedem Kunden etwas in Rechnung stellen, der über diese App verknüpft ist. Wenn eine Anfrage mit diesen Anmeldedaten ein anderes über diese App verknüpftes Profil angibt, stellt Anthropic die Anfrage der Organisation dieses Profils in Rechnung, und kein Fehler weist dich darauf hin. Das [Access-Token einer Verbindung](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection) kann nur seinem eigenen Kunden etwas in Rechnung stellen.
</Warning>

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.

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: user-profiles-billing-2026-10-01" \
    -H "anthropic-user-profile-id: uprof_01HV9Z" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-5-5",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Hello, Claude"}],
      "billing_policy": {"type": "billing_policy", "bill_to": "user_profile"}
    }'
  ```

  ```bash CLI
  ant beta:messages create \
    --beta user-profiles-billing-2026-10-01 \
    --user-profile-id uprof_01HV9Z \
    --model claude-sonnet-5-5 \
    --max-tokens 1024 \
    --message '{role: user, content: "Hello, Claude"}' <<'YAML'
  billing_policy:
    type: billing_policy
    bill_to: user_profile
  YAML
  ```

  ```python Python
  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"}
          },
      )
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const message = await client.beta.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    betas: ["user-profiles-billing-2026-10-01"],
    user_profile_id: "uprof_01HV9Z",
    // @ts-expect-error: billing_policy isn't in the SDK's types yet
    billing_policy: { type: "billing_policy", bill_to: "user_profile" }
  });

  console.log(message.content);
  ```

  ```csharp C#
  using Anthropic.Models.Beta.Messages;
  using System.Text.Json;
  using Model = Anthropic.Models.Messages.Model;

  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeSonnet5_5,
      MaxTokens = 1024,
      Messages = [new BetaUserMessageParam { Content = "Hello, Claude" }],
      Betas = ["user-profiles-billing-2026-10-01"],
      UserProfileID = "uprof_01HV9Z",
  };
  // billing_policy ist noch nicht in den Typen des SDK enthalten
  var body = new Dictionary<string, JsonElement>(parameters.RawBodyData)
  {
      ["billing_policy"] = JsonSerializer.SerializeToElement(
          new { type = "billing_policy", bill_to = "user_profile" }
      ),
  };

  var message = await client.Beta.Messages.Create(
      MessageCreateParams.FromRawUnchecked(parameters.RawHeaderData, parameters.RawQueryData, body)
  );

  Console.WriteLine(string.Join("\n", message.Content));
  ```

  ```go Go
  client := anthropic.NewClient()

  params := anthropic.BetaMessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet5_5,
  	MaxTokens: 1024,
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude")),
  	},
  	Betas:         []anthropic.AnthropicBeta{"user-profiles-billing-2026-10-01"},
  	UserProfileID: anthropic.String("uprof_01HV9Z"),
  }
  params.SetExtraFields(map[string]any{
  	"billing_policy": map[string]string{
  		"type":    "billing_policy",
  		"bill_to": "user_profile",
  	},
  })

  message, err := client.Beta.Messages.New(context.Background(), params)
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Printf("%+v\n", message.Content)
  ```

  ```java Java
  import com.anthropic.core.JsonValue;
  import com.anthropic.models.beta.messages.MessageCreateParams;
  import com.anthropic.models.messages.Model;
  import java.util.Map;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      var params = MessageCreateParams.builder()
          .model(Model.CLAUDE_SONNET_5_5)
          .maxTokens(1024)
          .addUserMessage("Hello, Claude")
          .addBeta("user-profiles-billing-2026-10-01")
          .userProfileId("uprof_01HV9Z")
          .putAdditionalBodyProperty("billing_policy", JsonValue.from(Map.of(
              "type", "billing_policy",
              "bill_to", "user_profile")))
          .build();
      var message = client.beta().messages().create(params);

      IO.println(message.content());
  }
  ```

  ```php PHP
  use Anthropic\Messages\Model;

  $client = new Client();

  $message = $client->beta->messages->create(
      maxTokens: 1024,
      messages: [['role' => 'user', 'content' => 'Hello, Claude']],
      model: Model::CLAUDE_SONNET_5_5,
      betas: ['user-profiles-billing-2026-10-01'],
      userProfileID: 'uprof_01HV9Z',
      requestOptions: [
          'extraBodyParams' => [
              'billing_policy' => ['type' => 'billing_policy', 'bill_to' => 'user_profile'],
          ],
      ],
  );

  echo $message;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message = client.beta.messages.create(
    model: Anthropic::Model::CLAUDE_SONNET_5_5,
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    betas: ["user-profiles-billing-2026-10-01"],
    user_profile_id: "uprof_01HV9Z",
    request_options: {
      extra_body: { billing_policy: { type: "billing_policy", bill_to: "user_profile" } }
    }
  )

  puts(message.content)
  ```
</CodeGroup>

Wenn die Anfrage abgelehnt wird, siehe [Erwartete Fehler](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#expected-errors).

### Du bezahlst

Um selbst zu bezahlen, lässt du `billing_policy` entweder ganz weg (in diesem Fall ist der Abrechnungs-Beta-Header optional):

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-user-profile-id: uprof_01HV9Z" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-opus-5-5",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Hello, Claude"}]
    }'
  ```

  ```bash CLI
  ant messages create \
    --user-profile-id uprof_01HV9Z \
    --model claude-sonnet-5-5 \
    --max-tokens 1024 \
    --message '{role: user, content: "Hello, Claude"}'
  ```

  ```python Python
  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,
      )
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const message = await client.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    user_profile_id: "uprof_01HV9Z"
  });

  console.log(message.content);
  ```

  ```csharp C#
  AnthropicClient client = new();

  var message = await client.Messages.Create(
      new MessageCreateParams
      {
          Model = Model.ClaudeSonnet5_5,
          MaxTokens = 1024,
          Messages = [new UserMessageParam { Content = "Hello, Claude" }],
          UserProfileID = "uprof_01HV9Z",
      }
  );

  Console.WriteLine(string.Join("\n", message.Content));
  ```

  ```go Go
  client := anthropic.NewClient()

  message, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet5_5,
  	MaxTokens: 1024,
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, Claude")),
  	},
  	UserProfileID: anthropic.String("uprof_01HV9Z"),
  })
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Printf("%+v\n", message.Content)
  ```

  ```java Java
  import com.anthropic.models.messages.MessageCreateParams;
  import com.anthropic.models.messages.Model;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      var params = MessageCreateParams.builder()
          .model(Model.CLAUDE_SONNET_5_5)
          .maxTokens(1024)
          .addUserMessage("Hello, Claude")
          .userProfileId("uprof_01HV9Z")
          .build();
      var message = client.messages().create(params);

      IO.println(message.content());
  }
  ```

  ```php PHP
  use Anthropic\Messages\Model;

  $client = new Client();

  $message = $client->messages->create(
      maxTokens: 1024,
      messages: [['role' => 'user', 'content' => 'Hello, Claude']],
      model: Model::CLAUDE_SONNET_5_5,
      userProfileID: 'uprof_01HV9Z',
  );

  echo $message;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message = client.messages.create(
    model: Anthropic::Model::CLAUDE_SONNET_5_5,
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    user_profile_id: "uprof_01HV9Z"
  )

  puts(message.content)
  ```
</CodeGroup>

oder verwendest `bill_to: "self"`:

<CodeGroup>
  ```bash cURL
  curl https://api.anthropic.com/v1/messages \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: user-profiles-billing-2026-10-01" \
    -H "anthropic-user-profile-id: uprof_01HV9Z" \
    -H "content-type: application/json" \
    -d '{
      "model": "claude-sonnet-5-5",
      "max_tokens": 1024,
      "messages": [{"role": "user", "content": "Hello, Claude"}],
      "billing_policy": {"type": "billing_policy", "bill_to": "self"}
    }'
  ```

  ```bash CLI
  ant beta:messages create \
    --beta user-profiles-billing-2026-10-01 \
    --user-profile-id uprof_01HV9Z \
    --model claude-sonnet-5-5 \
    --max-tokens 1024 \
    --message '{role: user, content: "Hello, Claude"}' <<'YAML'
  billing_policy:
    type: billing_policy
    bill_to: self
  YAML
  ```

  ```python Python
  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"}},
      )
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const message = await client.beta.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    betas: ["user-profiles-billing-2026-10-01"],
    user_profile_id: "uprof_01HV9Z",
    // @ts-expect-error: billing_policy isn't in the SDK's types yet
    billing_policy: { type: "billing_policy", bill_to: "self" }
  });

  console.log(message.content);
  ```

  ```csharp C#
  using Anthropic.Models.Beta.Messages;
  using System.Text.Json;
  using Model = Anthropic.Models.Messages.Model;

  AnthropicClient client = new();

  var parameters = new MessageCreateParams
  {
      Model = Model.ClaudeSonnet5_5,
      MaxTokens = 1024,
      Messages = [new BetaUserMessageParam { Content = "Hello, Claude" }],
      Betas = ["user-profiles-billing-2026-10-01"],
      UserProfileID = "uprof_01HV9Z",
  };
  // billing_policy ist noch nicht in den Typen des SDK enthalten
  var body = new Dictionary<string, JsonElement>(parameters.RawBodyData)
  {
      ["billing_policy"] = JsonSerializer.SerializeToElement(
          new { type = "billing_policy", bill_to = "self" }
      ),
  };

  var message = await client.Beta.Messages.Create(
      MessageCreateParams.FromRawUnchecked(parameters.RawHeaderData, parameters.RawQueryData, body)
  );

  Console.WriteLine(string.Join("\n", message.Content));
  ```

  ```go Go
  client := anthropic.NewClient()

  params := anthropic.BetaMessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet5_5,
  	MaxTokens: 1024,
  	Messages: []anthropic.BetaMessageParam{
  		anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Hello, Claude")),
  	},
  	Betas:         []anthropic.AnthropicBeta{"user-profiles-billing-2026-10-01"},
  	UserProfileID: anthropic.String("uprof_01HV9Z"),
  }
  params.SetExtraFields(map[string]any{
  	"billing_policy": map[string]string{
  		"type":    "billing_policy",
  		"bill_to": "self",
  	},
  })

  message, err := client.Beta.Messages.New(context.Background(), params)
  if err != nil {
  	log.Fatal(err)
  }

  fmt.Printf("%+v\n", message.Content)
  ```

  ```java Java
  import com.anthropic.core.JsonValue;
  import com.anthropic.models.beta.messages.MessageCreateParams;
  import com.anthropic.models.messages.Model;
  import java.util.Map;

  void main() {
      AnthropicClient client = AnthropicOkHttpClient.fromEnv();

      var params = MessageCreateParams.builder()
          .model(Model.CLAUDE_SONNET_5_5)
          .maxTokens(1024)
          .addUserMessage("Hello, Claude")
          .addBeta("user-profiles-billing-2026-10-01")
          .userProfileId("uprof_01HV9Z")
          .putAdditionalBodyProperty("billing_policy", JsonValue.from(Map.of(
              "type", "billing_policy",
              "bill_to", "self")))
          .build();
      var message = client.beta().messages().create(params);

      IO.println(message.content());
  }
  ```

  ```php PHP
  use Anthropic\Messages\Model;

  $client = new Client();

  $message = $client->beta->messages->create(
      maxTokens: 1024,
      messages: [['role' => 'user', 'content' => 'Hello, Claude']],
      model: Model::CLAUDE_SONNET_5_5,
      betas: ['user-profiles-billing-2026-10-01'],
      userProfileID: 'uprof_01HV9Z',
      requestOptions: [
          'extraBodyParams' => [
              'billing_policy' => ['type' => 'billing_policy', 'bill_to' => 'self'],
          ],
      ],
  );

  echo $message;
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  message = client.beta.messages.create(
    model: Anthropic::Model::CLAUDE_SONNET_5_5,
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello, Claude" }],
    betas: ["user-profiles-billing-2026-10-01"],
    user_profile_id: "uprof_01HV9Z",
    request_options: {
      extra_body: { billing_policy: { type: "billing_policy", bill_to: "self" } }
    }
  )

  puts(message.content)
  ```
</CodeGroup>

## 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**](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens) für deine App und fordere in Schritt 5 `offline_access` an. 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 demselben `scope` erneut aus.
* **Einen Standard-Workspace festlegen.** [Wähle einen Workspace](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens) 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#turn-off-operator-only-authentication), muss sich jede Anfrage, die einem Kunden etwas in Rechnung stellt, mit dem Access-Token dieses Kunden authentifizieren.
* **`billing:attribution` verwenden.** 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 mit `org:billing_attribution`, das abgekündigt ist. Siehe [Scopes für eine Abrechnungsverbindung](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#scopes-for-a-billing-connection).

### 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.

<Note>
  Das Archivieren des Standard-Workspace widerruft jedes Token, das darin läuft, und kann nicht rückgängig gemacht werden. Um zu einem anderen Workspace zu wechseln, lege den neuen fest und warte einige Minuten. Ein Refresh, bevor die Änderung `auth.claude.com` erreicht, kann Token zurückgeben, die noch im früheren Workspace laufen. Aktualisiere dann jede Verbindung, die ein Refresh-Token hat, und archiviere erst dann den früheren Workspace. Wenn du einen Workspace zuerst archivierst, stoppe die Aktualisierung seiner Verbindungen, bevor du einen anderen festlegst: Ein späterer Refresh beendet die Verbindung.

  Ändere oder archiviere das Operator-Service-Konto der App nicht, solange ein Kunde verknüpft ist. Nachdem du es geändert oder archiviert hast, lehnt `auth.claude.com` jeden Refresh ab, und die Token, die du besitzt, können Kunden bald nichts mehr in Rechnung stellen. Jeder Kunde, dessen Token du verwendest, muss dann erneut verknüpfen: Wenn du Hilfe brauchst, [wende dich an den Support](https://support.claude.com/en/articles/9015913-how-to-get-support).
</Note>

### 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#turn-off-operator-only-authentication).

### 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again).

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

<Note>
  Frage während der Beta dein Anthropic-Account-Team, ob Claude API-Anfragen mit dem Access-Token einer Verbindung für deine Organisation aktiviert sind. Solange das nicht der Fall ist, schlägt jede solche Anfrage fehl, unabhängig davon, was sie sendet. Frage außerdem, ob der Header `anthropic-user-profile-id` und `billing_policy` optional sind. Solange das nicht der Fall ist, sende jede Anfrage an `/v1/messages` und `/v1/chat/completions`, die das Access-Token einer Verbindung verwendet, so wie unter [Dein Kunde bezahlt](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#your-customer-pays) gezeigt, mit dem Header, `bill_to: "user_profile"` und dem Abrechnungs-Beta-Header.
</Note>

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` (typescript, php: `authToken`; java: `.authToken()`; csharp: `AuthToken`; go: `option.WithAuthToken()`) 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](https://platform.claude.com/docs/de/about-claude/pricing#code-execution-tool) 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 oder `bill_to: "self"` gesetzt.
* `403 permission_error`, ohne Fehlercode: Die Anfrage ging an einen [Message Batches](https://platform.claude.com/docs/de/build-with-claude/batch-processing)-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 auch `403 user_profile_not_billable` lauten.

### 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/oauth-reference#client-authentication) deiner App. Sende keinen `scope`-Parameter.

<CodeGroup exclude="shell:CLI, typescript, csharp, go, java, php, ruby">
  ```bash cURL
  curl https://auth.claude.com/v1/oauth/token \
    -H "content-type: application/json" \
    -d @- <<JSON
  {
    "grant_type": "refresh_token",
    "refresh_token": "$CONNECTION_REFRESH_TOKEN",
    "client_id": "YOUR_CLIENT_ID",
    "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
    "client_assertion": "$CLIENT_ASSERTION"
  }
  JSON
  ```

  ```python Python
  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 error
  ```
</CodeGroup>

Die 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#oauth-token-snippet-initialization) 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 `503` in dieser Liste: Du kannst nicht erkennen, ob die Anfrage wirksam wurde, sende daher dasselbe Refresh-Token noch einmal.

  1. Sende es sofort, und nur, wenn seit dem Senden der ersten Anfrage weniger als 30 Sekunden vergangen sind.
  2. 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.
  3. 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again).

* 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again).

* `429` oder `503` mit einem `retry-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_client` oder `invalid_client`: Nichts wurde widerrufen. `error_description` gibt 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 einen `scope`-Parameter gesendet, oder `billing:attribution` ist 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again), 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](https://code.claude.com/docs/en/agent-sdk/overview) und das Anthropic SDK können das Token aus einer Anmeldedatendatei in einem Konfigurationsprofil lesen (siehe [Profil-Konfigurationsdatei](https://platform.claude.com/docs/de/manage-claude/wif-reference#profile-configuration-file)). 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.

```json configs/customer.json
{
  "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:

```json credentials/customer.json
{
  "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.

```python
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_grant` zurü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_access` verloren, oder Schritt 8 hat für eine solche Verbindung `invalid_grant` zurückgegeben.
* Ein Refresh-Token läuft bald ab.

Führe diese Schritte aus:

1. Prüfe auf deiner Seite [User profiles](https://platform.claude.com/user-profiles), ob der Kunde als **Linked** angezeigt wird. Frage nach `invalid_grant` zuerst 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 gleichzeitig `invalid_grant` zurückgibt, suche nach einer Ursache auf deiner Seite, etwa einem archivierten Workspace, bevor du die Verknüpfung von jemandem aufhebst.
2. Wenn der Kunde als **Linked** angezeigt wird, hebe seine Verknüpfung auf, wie unter [Die Verknüpfung eines Kunden aufheben](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#disconnecting-a-customer) 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.
3. 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

<Note>
  Frage während der Beta dein Anthropic-Account-Team, ob diese Einstellung für deine Organisation verfügbar ist. Solange das nicht der Fall ist, kannst du sie nicht aktivieren.
</Note>

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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#settings-for-a-connections-oauth-tokens) 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 `httpx` gehört
* die Client-ID deiner App und den Typ der Client-Assertion
* `ConnectionTokens`, das die Token einer Verbindung, ihre Ablaufzeiten und ihre `on_hold`-Markierung enthält
* `RefreshOnHold`, den Fehler, den `refresh_connection()` auslöst, wenn ein Refresh-Token nicht erneut gesendet werden darf: Es wurde möglicherweise bereits verwendet, oder der Token-Endpunkt hat mit `invalid_grant` geantwortet. `refresh_connection()` löst ihn auch bei jedem späteren Aufruf aus, bis du `on_hold` in 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 sein `new_tokens` die zu speichernden Token.
* `client_assertion()`, das das JWT deines Identitätsanbieters aus der Datei liest, die `ANTHROPIC_IDENTITY_TOKEN_FILE` angibt. Der `aud`-Claim des JWT muss der Audience in den Client-Authentifizierungseinstellungen deiner App entsprechen.
* `load_tokens()` und `save_tokens()`, die du für deinen eigenen Secret Store schreibst

```python
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](https://platform.claude.com/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](https://platform.claude.com/docs/de/manage-claude/usage-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](https://platform.claude.com/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](https://platform.claude.com/docs/de/manage-claude/admin-api#authentication) 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](https://platform.claude.com/docs/de/manage-claude/usage-cost-analytics-api#usage-endpoint) oder ihren [Cost-Endpunkt](https://platform.claude.com/docs/de/manage-claude/usage-cost-analytics-api#cost-endpoint) 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](https://platform.claude.com/docs/de/manage-claude/usage-cost-analytics-api#data-freshness). [Ausgabenobergrenzen](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#spend-caps) 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](https://platform.claude.com/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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/oauth-reference#revocation), mit derselben Client-Authentifizierung wie beim Code-Austausch. Um die Verbindung stattdessen über ihr Nutzerprofil anzugeben, sende `user_profile_id` anstelle von `connection_id`.

<CodeGroup exclude="shell:CLI">
  ```bash cURL
  curl https://auth.claude.com/v1/oauth/revoke \
    -H "content-type: application/json" \
    -d @- <<'JSON'
  {
    "connection_id": "ocon_01HV9Z",
    "client_id": "YOUR_CLIENT_ID",
    "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
    "client_assertion": "YOUR_CLIENT_ASSERTION_JWT"
  }
  JSON
  ```

  ```python Python
  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"]
  ```

  ```typescript TypeScript
  // Kein SDK deckt auth.claude.com ab, daher ruft dieses Beispiel es direkt auf.
  import { readFile } from "node:fs/promises";

  // Die Verbindungs-ID, die du in Schritt 8 gespeichert hast.
  const connectionId = "ocon_01HV9Z";

  // Die Client-Assertion: das JWT in der Identity-Token-Datei. Lies es bei jeder Anfrage neu, da die Datei rotiert.
  // Erwartet die Client-Authentifizierung deiner App eine andere Audience als die des JWT, verwende eine zweite Token-Datei.
  const clientAssertion = (
    await readFile(process.env.ANTHROPIC_IDENTITY_TOKEN_FILE!, "utf8")
  ).trim();

  const response = await fetch("https://auth.claude.com/v1/oauth/revoke", {
    method: "POST",
    redirect: "error",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      connection_id: connectionId,
      client_id: "YOUR_CLIENT_ID",
      client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
      client_assertion: clientAssertion
    })
  });
  if (!response.ok) {
    throw new Error(`revoke failed: ${response.status}`);
  }

  const { revoked_connection_ids: revokedConnectionIds } = (await response.json()) as {
    revoked_connection_ids: string[];
  };
  console.log(revokedConnectionIds); // IDs of the connections this request ended. The list is empty if the connection had already ended or the ID is unknown.
  ```

  ```csharp C#
  // Kein SDK deckt auth.claude.com ab, daher ruft dieses Beispiel es direkt auf.
  using System.Net.Http.Json;
  using System.Text.Json;

  // Die Verbindungs-ID, die du in Schritt 8 gespeichert hast.
  var connectionId = "ocon_01HV9Z";

  // Die Client-Assertion: das JWT in der Identity-Token-Datei. Lies es bei jeder Anfrage neu, da die Datei rotiert.
  // Erwartet die Client-Authentifizierung deiner App eine andere Audience als die des JWT, verwende eine zweite Token-Datei.
  var tokenFile = Environment.GetEnvironmentVariable("ANTHROPIC_IDENTITY_TOKEN_FILE")!;
  var clientAssertion = (await File.ReadAllTextAsync(tokenFile)).Trim();

  using var http = new HttpClient();
  using var response = await http.PostAsJsonAsync(
      "https://auth.claude.com/v1/oauth/revoke",
      new Dictionary<string, string>
      {
          ["connection_id"] = connectionId,
          ["client_id"] = "YOUR_CLIENT_ID",
          ["client_assertion_type"] = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
          ["client_assertion"] = clientAssertion,
      }
  );
  response.EnsureSuccessStatusCode();

  var result = await response.Content.ReadFromJsonAsync<JsonElement>();
  Console.WriteLine(result.GetProperty("revoked_connection_ids")); // IDs of the connections this request ended. The list is empty if the connection had already ended or the ID is unknown.
  ```

  ```go Go
  // Kein SDK deckt auth.claude.com ab, daher ruft dieses Beispiel es direkt auf.

  import (
  	"bytes"
  	"encoding/json"
  	"fmt"
  	"net/http"
  	"os"
  	"strings"
  )

  func main() {
  	// Die Verbindungs-ID, die du in Schritt 8 gespeichert hast.
  	connectionID := "ocon_01HV9Z"

  	// Die Client-Assertion: das JWT in der Identity-Token-Datei. Lies sie bei jeder Anfrage neu, da die Datei rotiert.
  	// Erwartet die Client-Authentifizierung deiner App eine andere Audience als die des JWT, verwende eine zweite Token-Datei.
  	token, err := os.ReadFile(os.Getenv("ANTHROPIC_IDENTITY_TOKEN_FILE"))
  	if err != nil {
  		panic(err)
  	}

  	body, err := json.Marshal(map[string]string{
  		"connection_id":         connectionID,
  		"client_id":             "YOUR_CLIENT_ID",
  		"client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
  		"client_assertion":      strings.TrimSpace(string(token)),
  	})
  	if err != nil {
  		panic(err)
  	}

  	response, err := http.Post("https://auth.claude.com/v1/oauth/revoke", "application/json", bytes.NewReader(body))
  	if err != nil {
  		panic(err)
  	}
  	defer response.Body.Close()
  	if response.StatusCode < 200 || response.StatusCode > 299 {
  		panic(fmt.Sprintf("revoke failed: %d", response.StatusCode))
  	}

  	var result struct {
  		RevokedConnectionIDs []string `json:"revoked_connection_ids"`
  	}
  	if err := json.NewDecoder(response.Body).Decode(&result); err != nil {
  		panic(err)
  	}
  	fmt.Println(result.RevokedConnectionIDs) // IDs of the connections this request ended. The list is empty if the connection had already ended or the ID is unknown.
  }
  ```

  ```java Java
  // Kein SDK deckt auth.claude.com ab, daher ruft dieses Beispiel es direkt auf. Das Java-SDK bringt Jackson mit.
  import com.fasterxml.jackson.databind.ObjectMapper;
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;
  import java.nio.file.Files;
  import java.nio.file.Path;

  void main() throws Exception {
      // Die Verbindungs-ID, die du in Schritt 8 gespeichert hast.
      String connectionId = "ocon_01HV9Z";

      // Die Client-Assertion: das JWT in der Identity-Token-Datei. Lies sie bei jeder Anfrage neu, da die Datei rotiert.
      // Erwartet die Client-Authentifizierung deiner App eine andere Audience als die des JWT, verwende eine zweite Token-Datei.
      String clientAssertion = Files.readString(
          Path.of(System.getenv("ANTHROPIC_IDENTITY_TOKEN_FILE"))).strip();

      var mapper = new ObjectMapper();
      String body = mapper.createObjectNode()
          .put("connection_id", connectionId)
          .put("client_id", "YOUR_CLIENT_ID")
          .put("client_assertion_type", "urn:ietf:params:oauth:client-assertion-type:jwt-bearer")
          .put("client_assertion", clientAssertion)
          .toString();

      var request = HttpRequest.newBuilder(URI.create("https://auth.claude.com/v1/oauth/revoke"))
          .header("content-type", "application/json")
          .POST(HttpRequest.BodyPublishers.ofString(body))
          .build();
      var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
      if (response.statusCode() / 100 != 2) {
          throw new IllegalStateException("revoke failed: " + response.statusCode());
      }

      // IDs der von dieser Anfrage beendeten Verbindungen. Die Liste ist leer, wenn die Verbindung bereits beendet war oder die ID unbekannt ist.
      IO.println(mapper.readTree(response.body()).get("revoked_connection_ids"));
  }
  ```

  ```php PHP
  // Kein SDK deckt auth.claude.com ab, daher ruft dieses Beispiel es direkt auf.

  // Die Verbindungs-ID, die du in Schritt 8 gespeichert hast.
  $connectionId = 'ocon_01HV9Z';

  // Die Client-Assertion: das JWT in der Identity-Token-Datei. Lies sie bei jeder Anfrage neu, da die Datei rotiert.
  // Erwartet die Client-Authentifizierung deiner App eine andere Audience als die des JWT, verwende eine zweite Token-Datei.
  $clientAssertion = trim(
      file_get_contents((string) getenv('ANTHROPIC_IDENTITY_TOKEN_FILE'))
          ?: throw new \RuntimeException('the file named by ANTHROPIC_IDENTITY_TOKEN_FILE cannot be read or is empty')
  );

  $body = json_encode([
      'connection_id' => $connectionId,
      'client_id' => 'YOUR_CLIENT_ID',
      'client_assertion_type' => 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
      'client_assertion' => $clientAssertion,
  ], JSON_THROW_ON_ERROR);

  $context = stream_context_create(['http' => [
      'method' => 'POST',
      'header' => 'content-type: application/json',
      'content' => $body,
  ]]);
  $response = file_get_contents('https://auth.claude.com/v1/oauth/revoke', context: $context);
  if ($response === false) {
      throw new \RuntimeException('revoke failed');
  }

  /** @var array{revoked_connection_ids: list<string>} $result */
  $result = json_decode($response, associative: true, flags: JSON_THROW_ON_ERROR);
  // IDs der Verbindungen, die diese Anfrage beendet hat. Die Liste ist leer, wenn die Verbindung bereits beendet war oder die ID unbekannt ist.
  echo implode(', ', $result['revoked_connection_ids']), PHP_EOL;
  ```

  ```ruby Ruby
  # Kein SDK deckt auth.claude.com ab, daher ruft dieses Beispiel es direkt auf.
  require "json"
  require "net/http"

  # Die Verbindungs-ID, die du in Schritt 8 gespeichert hast.
  connection_id = "ocon_01HV9Z"

  # Die Client-Assertion: das JWT in der Identity-Token-Datei. Lies es bei jeder Anfrage neu, da die Datei rotiert.
  # Erwartet die Client-Authentifizierung deiner App eine andere Audience als die des JWT, verwende eine zweite Token-Datei.
  client_assertion = File.read(ENV.fetch("ANTHROPIC_IDENTITY_TOKEN_FILE")).strip

  response = Net::HTTP.post(
    URI("https://auth.claude.com/v1/oauth/revoke"),
    {
      connection_id: connection_id,
      client_id: "YOUR_CLIENT_ID",
      client_assertion_type: "urn:ietf:params:oauth:client-assertion-type:jwt-bearer",
      client_assertion: client_assertion
    }.to_json,
    "content-type" => "application/json"
  )
  response.value # raises on an error

  # IDs der Verbindungen, die diese Anfrage beendet hat. Die Liste ist leer, wenn die Verbindung bereits beendet war oder die ID unbekannt ist.
  puts(JSON.parse(response.body).fetch("revoked_connection_ids"))
  ```
</CodeGroup>

`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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/oauth-reference#revocation), siehe außerdem [Fehler des Widerrufsendpunkts](https://platform.claude.com/docs/de/manage-claude/oauth-apps/oauth-reference#errors-from-the-revocation-endpoint).

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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#after-connecting) beschreibt, was dein Kunde sieht, und [E-Mails zum Verknüpfen und Aufheben der Verknüpfung](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#emails-to-your-customer) 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:

1. Überspringe diesen Schritt, wenn dein Kunde die Verknüpfung mit deiner App bereits auf seiner Seite [Linked platforms](https://platform.claude.com/linked-platforms) aufgehoben hat. Andernfalls hebe die Verknüpfung des Kunden auf, wie unter [Die Verknüpfung eines Kunden aufheben](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#disconnecting-a-customer) beschrieben. Das Nutzerprofil wird dann auf deiner Seite [User profiles](https://platform.claude.com/user-profiles) als **Unlinked** angezeigt.
2. Führe die [Schritte 5 bis 8](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#runtime-step-2) erneut mit demselben Nutzerprofil aus. Für [Schritt 7](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#the-administrator-approves) 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.
3. 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#spend-caps) 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 von `user_profile_not_billable`](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#user-profile-not-billable) an: Ein erneutes Verknüpfen behebt nur einige davon. Du kannst den Kunden weiterhin auf eigene Kosten bedienen, indem du die Anfrage mit `bill_to: "self"` erneut sendest. Behandle `user_profile_not_billable` im Anthropic SDK anhand der [Fehlerklasse](https://platform.claude.com/docs/de/api/errors#sdk-error-types) für den Status 403, also `PermissionDeniedError` (java, php: `PermissionDeniedException`; csharp: `AnthropicForbiddenException`; go: `apierr.StatusCode == http.StatusForbidden`). 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 stattdessen `linked_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 mit `bill_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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#spend-caps), 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 mit `bill_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](https://platform.claude.com/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](https://platform.claude.com/settings/billing#spend-limits) kann er es erhöhen.
  * **Das Guthaben:** Auf seiner Seite [Abrechnung](https://platform.claude.com/settings/billing) kann er sein Guthaben einsehen und Guthaben kaufen. Manches Guthaben kann diese Anfragen nicht bezahlen: siehe [Welches Guthaben bezahlen kann](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#which-credits-can-pay).

* `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 den `retry-after`-Header. Die Anfrage wurde weder bedient noch abgerechnet.

* `400 invalid_request_error, user_profile_required`: Du hast `bill_to: "user_profile"` ohne den Header `anthropic-user-profile-id` gesetzt. 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#call-claude-with-a-connections-access-token).

* `400 invalid_request_error`, ohne Fehlercode: Der Header `anthropic-user-profile-id` enthä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 entweder `bill_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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#call-claude-with-a-connections-access-token).

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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#call-claude-with-a-connections-access-token) 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#oauth-tokens-for-each-connection) 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-id` eines 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](https://platform.claude.com/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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#turn-off-operator-only-authentication), 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#connect-a-customer-again) beschrieben.
* **Die Organisation des Kunden.** Sie muss ein [berechtigter Kunde](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#eligible-customers-and-endpoints) 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#the-administrator-approves) 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#spend-caps) beschreibt. Dieser Bildschirm sieht anders aus, solange sich deine App im Test befindet: siehe [Solange sich deine App im Test befindet](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#while-your-app-is-in-testing).
* **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](https://platform.claude.com/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`](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#user-profile-not-billable)). Das Nutzerprofil des Kunden wird auf deiner Seite [User profiles](https://platform.claude.com/user-profiles) in der Console als **Unlinked** angezeigt. Um erneut zu verknüpfen, führe die [Schritte 5 bis 8](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#runtime-step-2) 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#connecting)). 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#expected-errors). 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](https://platform.claude.com/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](https://platform.claude.com/settings/billing#spend-limits) 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](https://platform.claude.com/docs/de/manage-claude/oauth-apps/organization-billing-connections#spend-caps) 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 an `auth.claude.com` sendet

```python
# 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()
```
