# Eingeschränkte API-Schlüssel

Verwenden Sie eingeschränkte API-Schlüssel, um den Zugriff Ihrer Anwendung auf die Stripe-API zu steuern.

Sie können einen eingeschränkten API-Schlüssel („Restricted API Key“, RAK) verwenden, um Ihren API-Schlüsseln bestimmte Stripe-API-Berechtigungen zuzuweisen. ‘’ Die Verwendung eines RAK begrenzt den möglichen Schaden für Ihr Unternehmen, wenn ein API-Schlüssel in die Hände eines böswilligen Akteurs gelangt. Wenn ein eingeschränkter API-Schlüssel nicht über die erforderlichen Berechtigungen verfügt, um eine API-Anfrage abzuschließen, gibt Stripe einen [Fehler durch ungültige Anfrage](https://docs.stripe.com/error-handling.md#invalid-request-errors) zurück.

## Was ist ein eingeschränkter API-Schlüssel?

Wenn Sie sich bei Stripe registrieren, erhalten Sie einen [geheimen API-Schlüssel](https://docs.stripe.com/keys.md#obtain-api-keys) (beginnt mit `sk_live_` oder `sk_test_`). Jede Person, jeder Agent oder jedes System mit Ihrem Geheimschlüssel kann *alles* in Ihrem Stripe-Konto tun: Zahlungen erstellen, Rückerstattungen ausstellen, Kundendaten lesen, Auszahlungen auslösen und vieles mehr.

Ein eingeschränkter API-Schlüssel (RAK) beginnt mit `rk_live_` oder `rk_test_` und kann nur das tun, was Sie möchten. Wenn Sie einen RAK im Stripe-Dashboard erstellen, wählen Sie aus, auf welche Stripe-Ressourcen der Schlüssel zugreifen kann und welche Berechtigungen für jede Ressource gelten: **Lesen**, **Schreiben** oder **Keine**. Alle Stripe-APIs unterstützen eingeschränkte API-Schlüssel.

Sie können RAKs als Schutzmaßnahme einsetzen, um Ihr Stripe-Konto zu sichern, falls Ihre Schlüssel offengelegt oder kompromittiert werden. Wenn ein böswilliger Akteur einen RAK erlangt, sind seine Zugriffsrechte auf die Berechtigungen dieses Schlüssels beschränkt. Sie könnten beispielsweise einen RAK erstellen, der ausschließlich Streitfalldaten lesen kann und sonst nichts. Würde ein böswilliger Akteur diesen Schlüssel erlangen, könnte er lediglich Streitfalldaten einsehen. Er könnte keine Belastungen vornehmen, nicht auf die Zahlungsmethoden der Kunden zugreifen und keine Auszahlungen veranlassen.

Stripe empfiehlt, stets RAKs anstelle von uneingeschränkten Geheimschlüsseln zu verwenden, insbesondere wenn Sie einem KI-Agenten einen Schlüssel zur Verfügung stellen. Nutzen Sie RAK-Berechtigungen, um die Aktionen eines Agenten in Ihrem Konto einzuschränken.

Beachten Sie bei der Verwendung von RAKs stets die [Best Practices](https://docs.stripe.com/keys-best-practices.md), um eine versehentliche Offenlegung oder Kompromittierung zu vermeiden. Behandeln Sie RAKs mit derselben Sorgfalt wie geheime API-Schlüssel.

## Warum eingeschränkte Schlüssel anstelle von Geheimschlüsseln verwenden?

|                                        | Geheimschlüssel (`sk_`)                                                                             | Eingeschränkter Schlüssel (`rk_`)                                                                                |
| -------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Umfang des Zugriffs**                | Vollständiger Zugriff auf jede API-Ressource                                                        | Nur die von Ihnen zugewiesenen Berechtigungen                                                                    |
| **Auswirkungen bei Kompromittierung**  | Ein/e böswillige/r Akteur/in kann in ihrem Konto alles tun                                          | Ein/e böswillige/r Akteur/in kann nur das tun, was der Schlüssel zulässt                                         |
| **Eignung für KI-Agenten**             | Ein Agent könnte in Ihrem Konto Aktionen ausführen, die Sie nicht wünschen                          | Sie legen die Berechtigungen des Agenten ausdrücklich fest                                                       |
| **Drittanbieterfreigabe**              | Gefährlich: gibt der dritten Partei die volle Kontrolle                                             | Sicherer: Sie geben nur den Zugriff weiter, den die dritte Partei benötigt                                       |
| **Grundsatz des geringsten Privilegs** | Nicht möglich mit eingeschränkten Schlüsseln                                                        | Sie können Schlüsseln minimale Berechtigungen erteilen                                                           |
| **Compliance**                         | Sie können steuern, wer auf Ihre Schlüssel zugreifen kann, aber nicht, was die Schlüssel tun können | Sie können steuern, wer auf Ihre Schlüssel zugreifen kann, und Sie kontrollieren, was diese Schlüssel tun können |
| **Stripe-Empfehlung**                  | Sparsam verwenden und aggressiv schützen                                                            | **Bevorzugt**: Verwenden Sie eingeschränkte Schlüssel, wo immer dies möglich ist                                 |

## Einen eingeschränkten API-Schlüssel erstellen

1. Führen Sie unter der Registerkarte [API-Schlüssel](https://dashboard.stripe.com/test/apikeys) eine der folgenden Aktionen aus:
   - Um einen neuen eingeschränkten Schlüssel zu erstellen, klicken Sie auf **Eingeschränkten Schlüssel erstellen**.
   - Um einen bestehenden Schlüssel zu klonen, klicken Sie in der Zeile mit dem Schlüssel, den Sie klonen möchten, auf das Überlaufmenü (⋯) und wählen Sie dann **Schlüssel duplizieren** aus. In diesem Fall ist der Standardwert für jede Berechtigung der Wert von dem geklonten Schlüssel.
1. Wenn Sie einen neuen Schlüssel erstellen, können Sie aus einem vorkonfigurierten Satz von Berechtigungen wählen oder ohne Berechtigungen beginnen.
1. Geben Sie im Feld **Schlüsselname** einen Namen ein. Wenn Sie einen bestehenden Schlüssel geklont haben, ist der Standardname der Name des geklonten Schlüssels.
1. Wählen Sie für jede Ressource, auf die Sie mit dem neuen Schlüssel zugreifen möchten, die entsprechende Berechtigung aus : **Keine**, **Lesen** oder **Schreiben**. Wenn Sie Connect verwenden, können Sie auch die Berechtigung für diesen Schlüssel auswählen, um auf verbundene Konten zuzugreifen. Der Standardwert für alle Berechtigungen ist **Keine**.
1. Klicken Sie auf **Schlüssel erstellen**.
1. Schließen Sie im Dialogfeld die Zwei-Faktor-Verifizierung ab, die wir Ihnen senden.
1. Klicken Sie auf den Schlüsselwert, um ihn zu kopieren.
1. Speichern Sie den Schlüsselwert. Sie können ihn später nicht abrufen.
1. Geben Sie in das Feld **Notiz hinzufügen** den Speicherort ein, an dem Sie den Schlüssel gespeichert haben, und klicken Sie dann auf **Fertig**.

## Von einem Geheimschlüssel zu einem eingeschränkten Schlüssel migrieren

Eingeschränkte API-Schlüssel sind in Ihrer Server-Umgebung ein direkter Ersatz für geheime API-Schlüssel. Um einen eingeschränkten API-Schlüssel zu verwenden, stellen Sie ihn Ihrem Code auf die gleiche Weise bereit wie Ihren Geheimschlüssel. Befolgen Sie die [Best Practices](https://docs.stripe.com/keys-best-practices.md), um zu vermeiden, dass der Schlüssel versehentlich offengelegt wird. Jede Stripe-API unterstützt eingeschränkte API-Schlüssel. Sie müssen die Berechtigungen jedes eingeschränkten Schlüssels konfigurieren, um die Vorteile zu nutzen.

In den folgenden Abschnitten finden Sie einen Schritt-für-Schritt-Ansatz für die Migration von einem Geheimschlüssel zu einem eingeschränkten Schlüssel. Unter [Berechtigungen für einen eingeschränkten API-Schlüssel zuweisen](https://docs.stripe.com/keys/restricted-api-keys.md#assign-permissions) erfahren Sie, wie Sie die Berechtigungen eines eingeschränkten Schlüssels reduzieren können.

### Einen eingeschränkten API-Schlüssel in einer Sandbox erstellen

Erstellen Sie einen eingeschränkten API-Schlüssel in einer [Sandbox](https://docs.stripe.com/keys.md#test-live-modes), bevor Sie einen Live-Schlüssel erstellen.

1. Klicken Sie auf der [API-Schlüssel-Seite](https://dashboard.stripe.com/apikeys) im Stripe-Dashboard auf **Eingeschränkten Schlüssel erstellen**.
1. Geben Sie dem neuen Schlüssel einen aussagekräftigen Namen, z. B. `billing-service-test`.
1. Weisen Sie dem Schlüssel noch keine Berechtigungen zu. Sie legen die Berechtigungen fest, nachdem Sie die bestehende Nutzung des Geheimschlüssels geprüft haben.

### API-Nutzung des Geheimschlüssels prüfen

Verwenden Sie die bestehende API-Nutzung des Geheimschlüssels als Ausgangspunkt, um die Berechtigungen für einen RAK festzulegen.

- Prüfen Sie Ihren Code und alle Integrationen von Drittanbietern, um die von Ihnen verwendeten Stripe-Produkte und die API-Aufrufe, die Sie derzeit mit Ihrem Geheimschlüssel durchführen, zu katalogisieren.
- Prüfen Sie die [Anfrage-Logs](https://docs.stripe.com/keys.md#view-request-logs) des Geheimschlüssels, um erfolgreiche API-Anfragen einzusehen.

Verwenden Sie die folgende Tabelle, um erfolgreiche API-Anfragen den Berechtigungen zuzuordnen, die Ihr RAK benötigt. Legen Sie für jede Ressource die Berechtigung auf **Keine**, **Lesen** oder **Schreiben** fest, je nach der beobachteten API-Nutzung. Schreibberechtigungen schließen Leseberechtigungen ein: Jeder Schlüssel, der eine API-Ressource schreiben kann, kann diese Ressource auch lesen.

| HTTP-Methode | RAK-Berechtigungstyp |
| ------------ | -------------------- |
| GET          | lesen                |
| POST         | schreiben            |
| LÖSCHEN      | schreiben            |

Wenn Sie beispielsweise mit Ihrem Geheimschlüssel erfolgreiche Aufrufe an `GET /v1/customers` sehen, müssen Sie dem Ersatz-RAK Leseberechtigungen für die Ressource [Kundin/Kunde](https://docs.stripe.com/api/customers.md) hinzufügen.

### Ihre Staging-Umgebung so konfigurieren, dass sie den eingeschränkten Schlüssel verwendet

Ersetzen Sie in Ihrer Test- oder Staging-Anwendung den Geheimschlüssel mit dem eingeschränkten Schlüssel in Ihrer Server-Umgebung (z. B. in einem [Geheimnisspeicher](https://docs.stripe.com/keys-best-practices.md#use-a-secrets-vault) oder einer Umgebungsvariable, falls Ihre Plattform keine Geheimnisspeicher bereitstellt). Das Stripe-SDK und HTTP-Aufrufe, die Ihren Schlüssel verwenden, funktionieren identisch. Der einzige Unterschied ist der Schlüsselwert.

### Anfrage-Logs des eingeschränkten Schlüssels auf Fehler prüfen und Berechtigungen anpassen

Prüfen Sie die Logs des eingeschränkten Schlüssels im Test-Modus in der [Schlüsselliste](https://dashboard.stripe.com/apikeys), indem Sie auf das Überlaufmenü (⋯) neben dem Schlüssel klicken und **Anfrage-Logs anzeigen** auswählen.

Wenn Sie Fehlermeldungen wie `403 ERR` finden, bearbeiten Sie die Berechtigungen des eingeschränkten Schlüssels, um die fehlgeschlagenen Aktionen hinzuzufügen:

1. Klicken Sie neben dem Schlüssel auf das Überlaufmenü (⋯).
1. Wählen Sie **Schlüssel bearbeiten** aus.
1. Wiederholen Sie Ihre Tests in einer Sandbox, um zu bestätigen, dass Sie dem eingeschränkten Schlüssel die richtigen Berechtigungen zugewiesen haben.

Überprüfen Sie Ihre Anwendungs-Logs auf Stripe-API-Fehler. Wenn der mit einer Anfrage gesendete eingeschränkte Schlüssel nicht über die richtigen Berechtigungen verfügt, enthält der Antworttext eine Fehlermeldung. Diese erläutert, welche Berechtigungen hinzugefügt werden sollen.

### Einen eingeschränkt Schlüssel im Live-Modus erstellen

Erstellen Sie einen neuen eingeschränkten Schlüssel im Live-Modus mit Berechtigungen, die mit dem von Ihnen getesteten Test-Modus-Schlüssel übereinstimmen.

### Ihre Produktionsumgebung für die Verwendung des eingeschränkten Schlüssels konfigurieren

Verwenden Sie den neuen Schlüssel in Ihrer Produktionsumgebung auf die gleiche Weise, wie Sie den Testschlüssel in Ihrer Staging-Umgebung konfiguriert haben.

### Den alten Geheimschlüssel zurücksetzen

Wenn Sie sicher sind, dass alles im Test-Modus funktioniert, können Sie Ihren alten Geheimschlüssel im Dashboard [rotieren](https://docs.stripe.com/keys.md#rolling-keys) oder [ablaufen lassen](https://docs.stripe.com/keys.md#delete-secret-key). So wird sichergestellt, dass ihn in Zukunft niemand mehr verwenden kann. Sie können ein verzögertes Ablaufdatum (bis zu 7 Tagen) festlegen, wenn Sie ein Sicherheitsfenster wünschen, in dem Sie noch auf den Geheimschlüssel zurückgreifen können.

## Einem eingeschränkten API Schlüssel Berechtigungen zuweisen

Sie können eingeschränkte Schlüssel gemäß dem Prinzip des geringsten Privilegs so konfigurieren, dass sie zu Ihren spezifischen Use Cases passen: Ein Schlüssel sollte über die Mindestberechtigungen verfügen, die für seine Arbeit erforderlich sind, und nicht mehr. Hier sind einige praktische Ansätze zum Zuweisen von Berechtigungen.

### Logs für Audit-Anfragen prüfen, um Berechtigungen zu ermitteln

1. Rufen Sie im Dashboard die Seite [API-Schlüssel](https://dashboard.stripe.com/apikeys) auf.
1. Suchen Sie den eingeschränkten Schlüssel, den Sie konfigurieren.
1. Klicken Sie neben dem Schlüssel auf das Überlaufmenü (⋯).
1. Klicken Sie auf **Anfrage-Logs anzeigen**, um alle mit diesem Schlüssel getätigten Anfragen anzuzeigen.

Prüfen Sie die API-Endpoints Ihrer Anwendung, die während Ihres Tests mit dem eingeschränkten Schlüssen verwendet wurden, um genau zu sehen, welche Ressourcen Ihre Anwendung verwendet hat und ob es sich um Lese- oder Schreibvorgänge handelt:

- `GET-`-Anfragen sind Lesevorgänge
- `POST`- und `DELETE`-Anfragen sind Schreibvorgänge.

Wenn Ihre Anwendung bei Ihren Tests ordnungsgemäß funktioniert hat, führen Sie eine Liste der erfolgreichen Aufrufe in den Anfrage-Logs durch und vergleichen Sie die Liste dann mit den Berechtigungen, die Sie dem eingeschränkten Schlüssel gewährt haben. Sie können alle Berechtigungen entfernen, die Ihr Schlüssel nicht verwendet hat. So bearbeiten Sie die Berechtigungen des Schlüssels:

1. Klicken Sie auf das Überlaufmenü (⋯).
1. Klicken Sie auf **Schlüssel bearbeiten**.

Wenn Ihre Anwendung nicht ordnungsgemäß funktioniert, können Sie die Anfrage-Logs des Schlüssels filtern, um fehlgeschlagene Anfragen anzuzeigen. Dann können Sie die Berechtigungen des Schlüssels im Schlüsselmenü bearbeiten, um die entsprechenden Stripe-API-Berechtigungen hinzuzufügen.

### Ihren Code prüfen

Sie können eine Liste der erforderlichen Berechtigungen erstellen, indem Sie Ihre Codebasis nach Stripe-SDK-Aufrufen durchsuchen. Ordnen Sie jeden Aufruf im Dashboard der entsprechenden Berechtigung zu. Beispiel:

- `PaymentIntent.create(...)` → **PaymentIntents: Schreiben**
- `Customer.retrieve(...)` → **Kundinnen/Kunden: Lesen**
- `Dispute.list(...)` → **Anfechtungen: Lesen**

Konfigurieren Sie dann die Berechtigungen Ihres eingeschränkten Schlüssels so, dass sie nur mit dem übereinstimmen, was Sie gefunden haben.

### Mit allgemeinen Berechtigungen beginnen und dann entfernen, was Sie nicht benötigen

Sie können einem eingeschränkten Schlüssel zunächst allgemeine Berechtigungen erteilen und dann alle überschüssigen Berechtigungen entfernen, nachdem Sie überprüft haben, wie der Schlüssel verwendet wird.

Erstellen Sie in einer Sandbox einen eingeschränkten Schlüssel aus dem Menü API-Schlüssel. Die verfügbaren Berechtigungen sind in Kategorien gruppiert. Wenn Sie wissen, dass Ihre Stripe-API-Nutzung keine bestimmte Kategorie enthält, wie z. B. Stripe Billing, können Sie für diese Kategorie **Keine** auswählen. Wählen Sie andernfalls **Schreiben** für Kategorien aus, die für Ihre Stripe-API-Nutzung relevant sind. **Schreib**-Berechtigungen enthalten **Lese**-Berechtigungen: Wenn ein Schlüssel eine API-Ressource schreiben kann, kann er diese Ressource auch lesen.

Testen Sie Ihre Anwendung mit dem eingeschränkten Schlüssel im Test-Modus wie oben beschrieben, damit Ihre Anwendung den Schlüssel für Stripe-API-Anfragen verwendet. Testen Sie jede Komponente Ihrer Anwendung, die Stripe-APIs verwendet.

## Einen eingeschränkten Schlüssel pro Dienst oder Use Case verwenden

Wenn Sie mehrere Dienste nutzen, die Stripe-APIs verwenden (z. B. einen Abrechnungsdienst, einen Berichterstellungsdienst und einen Webhook-Handler), erstellen Sie für jeden Dienst einen separaten eingeschränkten Schlüssel und erteilen Sie jedem Schlüssel nur die Stripe-API-Berechtigungen, die der jeweilige Dienst benötigt. Durch die Erteilung separater Berechtigungen können Sie die potenziellen Auswirkungen einer Schlüsselübernahme begrenzen, wenn einer Ihrer Dienste kompromittiert wird.