# 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. Wenn Sie einen solchen RAK verwenden, wird der potenzielle Schaden für Ihr Unternehmen begrenzt, wenn ein API-Schlüssel einer/einem böswilligen Akteur/in in die Hände fällt. Wenn ein eingeschränkter API-Schlüssel nicht über die richtigen 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 eingeschränkte Schlüssel als Abwehrmaßnahme verwenden, um Ihr Stripe-Konto zu schützen, falls Ihre Schlüssel offengelegt oder kompromittiert werden. Wenn ein/e böswillige/r Akteur/in einen eingeschränkten API-Schlüssel erhält, ist er/sie auf die Berechtigungen dieses Schlüssels beschränkt. Sie könnten beispielsweise einen eingeschränkten Schlüssel erstellen, der nur die Daten von Zahlungsanfechtungen lesen kann und sonst nichts. Wenn ein/e böswillige/r Akteur/in diesen Schlüssel erhalten würde, könnte er/sie nur Daten von Zahlungsanfechtungen lesen. Er/sie könnte weder Zahlungen erstellen, noch auf Zahlungsmethoden der Kundinnen und Kunden zugreifen oder Auszahlungen auslösen.

Stripe empfiehlt, immer eingeschränkte Schlüssel anstelle nicht eingeschränkter Geheimschlüssel zu verwenden. Befolgen Sie bei der Verwendung eingeschränkter Schlüssel immer die Best Practices, um eine versehentliche Offenlegung oder Kompromittierung zu vermeiden. Siehe [Best Practices für die Verwaltung geheimer API-Schlüssel](https://docs.stripe.com/keys-best-practices.md).

## 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         |
| **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                           |
| **Stripe-Empfehlung**                  | Sparsam verwenden und aggressiv schützen                   | **Bevorzugt**: Verwenden Sie eingeschränkte Schlüssel, wo immer dies möglich ist |

### Gründe für den Wechsel zu eingeschränkten API-Schlüsseln

- **Auswirkungen begrenzen, falls der Schlüssel in falsche Hände fällt**: Wenn ein eingeschränkter Schlüssel kompromittiert wird, kann ein/e böswillige/r Akteur/in nur auf die spezifischen Ressourcen zugreifen, auf die Sie diesem Schlüssel Zugriff gewährt haben.

- **Schlüssel sicher an Dritte weitergeben**: Stripe rät in den meisten Fällen von der Weitergabe von Schlüsseln ab, aber bei bestimmten Integrationen von Drittanbietern müssen Sie möglicherweise einen Schlüssel weitergeben. Wenn ein Anbieter beispielsweise Ihre Anfechtungen überwachen muss, geben Sie ihm einen eingeschränkten Schlüssel mit schreibgeschütztem Zugriff auf Anfechtungen und nicht Ihren uneingeschränkten Geheimschlüssel. Wenn Sie mit einem Drittanbieter zusammenarbeiten, stellen Sie sicher, dass dieser die [Best Practices](https://docs.stripe.com/keys-best-practices.md) für einen sicheren Umgang mit dem Schlüssel befolgt, wie z. B. die Verwendung einer IP-Zulassungsliste, wenn möglich, um das Risiko einer Kompromittierung des Schlüssels zu minimieren, und um den Schlüssel ablaufen zu lassen, wenn die Beziehung endet.

- **Compliance-Erwartungen erfüllen**: Viele Sicherheitsprüfungen und Compliance-Frameworks erwarten, dass Sie dem Prinzip des geringsten Privilegs folgen. Eingeschränkte Schlüssel machen dies einfach.

- **Mit IP-Einschränkungen kombinieren**: Sie können jeden eingeschränkten Schlüssel für eine bestimmte Reihe von IP-Adressen sperren, um eine zusätzliche Verteidigungsebene zu schaffen.

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

Eingeschränkte API-Schlüssel sind 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 und 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.

Im Folgenden 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.

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

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 des Geheimschlüssels in Workbench](https://dashboard.stripe.com/workbench/logs). In der folgenden Tabelle können Sie erfolgreiche API-Anfragen den benötigten RAK-Berechtigungen zuordnen.

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

Wenn Sie beispielsweise erfolgreiche Aufrufe von `GET /v1/customers` sehen, müssen Sie den Berechtigungen eines Ersatz-RAKs schreibgeschützte Berechtigungen für die [Kundenressource](https://docs.stripe.com/api/customers.md) hinzufügen.

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

Stripe empfiehlt, einen eingeschränkten Schlüssel in einer Stripe-Sandbox zu erstellen, bevor Sie einen Live-Modus-Schlüssel erstellen.

1. Rufen Sie im Stripe-Dashboard die [API-Schlüsselseite](https://dashboard.stripe.com/apikeys) auf.
1. Klicken Sie auf **Eingeschränkten Schlüssel erstellen**.
1. Geben Sie einen aussagekräftigen Namen an, z. B. `billing-service-test`.
1. Legen Sie für jede Ressource die Berechtigung auf **Keine**, **Lesen** oder **Schreiben** fest, je nachdem, welche API-Nutzung Sie zuvor beobachtet haben.

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

Ersetzen Sie in Ihrer Staging-Anwendung den Geheimschlüssel mit dem eingeschränkten Schlüssel in Ihrer Server-Umgebung (z. B. in einer Umgebungsvariable oder einem Geheimnistresor). 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.