API-Schlüssel

Stripe authentifiziert Ihre API-Anfragen mithilfe der API-Schlüssel Ihres Kontos. Wenn eine Anfrage keinen gültigen Schlüssel enthält, gibt Stripe einen Fehler aufgrund einer ungültigen Anfrage zurück. Wenn eine Anfrage einen gelöschten oder abgelaufenen Schlüssel enthält, gibt Stripe einen Authentifizierungsfehler zurück.

Verwenden Sie das Entwickler-Dashboard, um API-Schlüssel zu erstellen, offenzulegen, zu löschen und zu rotieren. Sie können auf Ihre v1 API-Schlüssel über die Registerkarte API-Schlüssel zugreifen.

Schlüsseltypen

Standardmäßig verfügen alle Konten über insgesamt vier API-Schlüssel:

Ihre geheimen und für die Veröffentlichung freigegebenen Schlüssel finden Sie auf der Registerkarte API-Schlüssel im Dashboard. Sollten Sie Ihre API-Schlüssel nicht einsehen können, bitten Sie die Inhaberin oder den Inhaber Ihres Stripe-Kontos, Sie mit den entsprechenden Berechtigungen zu ihrem bzw. seinem Team hinzuzufügen.

Wenn Sie bei Stripe angemeldet sind, werden in unserer Dokumentation Code-Beispiele mit Ihren Test-API-Schlüsseln angezeigt. Nur Sie können diese Werte einsehen. Wenn Sie nicht angemeldet sind, enthalten unsere Code-Beispiele zufällig generierte API-Schlüssel, die Sie durch Ihre Testschlüssel ersetzen können. Alternativ können Sie sich anmelden, um die Code-Beispiele mit Ihren Test-API-Schlüsseln anzuzeigen.

Beispiel für API-Schlüssel

Die folgende Tabelle zeigt zufällig generierte Beispiele für geheime und für die Veröffentlichung freigegebene Schlüssel:

Schützen Sie Ihre Schlüssel

Jeder kann Ihren Geheimschlüssel für den Live-Modus verwenden, um einen beliebigen API-Aufruf im Namen Ihres Kontos durchzuführen, z. B. um eine Zahlung zu erstellen oder eine Rückerstattung durchzuführen. Bewahren Sie Ihre Schlüssel sicher auf, indem Sie die folgenden Best Practices befolgen:

• Speichern Sie Geheimschlüssel in einem Geheimschlüsseltresor oder in verschlüsselten Umgebungsvariablen. Speichern Sie keine Schlüssel im Quellcode oder in Konfigurationsdateien, die in die Versionsverwaltung eingecheckt wurden.
• Verwenden Sie nach Möglichkeit eingeschränkte API Schlüssel anstelle von Geheimschlüsseln. Eingeschränkte Schlüssel beschränken den Zugriff auf die spezifischen API-Referenzen, die Ihre Integration benötigt. So können die Auswirkungen eines kompromittierten Schlüssels verringert werden.
• Beschränken Sie Schlüssel auf bestimmte IP-Adressen, damit sie nur von Ihren bekannten Servern aus verwendet werden können.
• Rotieren Sie Schlüssel, wenn Teammitglieder mit Zugriff auf die Schlüssel Ihre Organisation verlassen.
• Teilen Sie keine Schlüssel per E-Mail, Chat oder andere unverschlüsselte Kanäle.

Weitere Informationen finden Sie unter Best Practices für die Verwaltung geheimer API-Schlüssel.

Sandbox im Vergleich zum Live-Modus

Alle Stripe-API-Anfragen erfolgen entweder in der Sandbox oder im Live-Modus. Verwenden Sie eine Sandbox, um auf Testdaten zuzugreifen, und den Live-Modus, um auf tatsächliche Kontodaten zuzugreifen. Jeder Modus verfügt über einen eigenen Satz API-Schlüssel. Objekte in einem Modus sind nicht gleichzeitig zugänglich. Zum Beispiel kann ein Sandbox-Produktobjekt im Live-Modus nicht Teil einer Zahlung sein.

In den Live-Modus wechseln

Wenn Sie bereit sind, echte Zahlungen zu akzeptieren, ersetzen Sie bitte Ihre Sandbox-API-Schlüssel (Test) durch Ihre Live-Modus-Schlüssel. Dies ist dieselbe Schlüsselseite im Dashboard – Sie können zwischen Test-Modus und Live-Modus wechseln, indem Sie den Schalter in der oberen rechten Ecke des Entwickler-Dashboards betätigen.

1. Deaktivieren Sie im Entwickler-Dashboard den Test-Modus, indem Sie den Modus-Schalter oben rechts umschalten. Die Seite zeigt jetzt Ihre API-Schlüssel für den Live-Modus an.
2. Kopieren Sie Ihren veröffentlichbaren Schlüssel im Live-Modus (beginnt mit pk_live_) und ersetzen Sie den Schlüssel pk_test_ in Ihrem clientseitigen Code.
3. Zeigen Sie Ihren geheimen Schlüssel im Live-Modus (beginnt mit sk_live_) an und kopieren Sie ihn und ersetzen Sie in Ihrem serverseitigen Code den Schlüssel sk_test_. Speichern Sie ihn sicher – Sie können ihn nur einmal anzeigen.
4. Wenn Sie Webhooks verwenden, aktualisieren Sie die URL jedes Webhook-Endpoints und kopieren Sie das neue Signaturgeheimnis aus dem Abschnitt Webhooks des Dashboards.

API-Schlüssel der Organisation

Wenn Sie mehrere Stripe-Unternehmenskonten in einer Organisation haben, können Sie einen einzelnen API-Schlüssel auf Organisationsebene konfigurieren. API-Schlüssel auf Organisationsebene bieten die folgenden Funktionen:

• Zugriff auf jedes Konto: Sie können API-Schlüssel der Organisation verwenden, um auf Ressourcen eines beliebigen Kontos innerhalb der Organisation zuzugreifen.

• Granulare Berechtigungen: Beschränken Sie die API-Schlüssel der Organisation, um nur bestimmten Ressourcen Lese- oder Schreibberechtigungen zu gewähren.
• Zentrale Verwaltung: Erstellen und verwalten Sie API-Schlüssel der Organisation unter der Registerkarte API-Schlüssel im Dashboard Ihrer Organisation.

Verhalten

API-Schlüssel der Organisation verhalten sich anders als API-Schlüssel auf Kontoebene. Dazu zählt unter anderem:

• Sie haben keinen veröffentlichbaren Schlüssel. Behandeln Sie alle API-Schlüssel der Organisation als geheime Schlüssel.
• Sie haben alle das gleiche sk_org-Präfix, unabhängig von ihrer Berechtigungsstufe.
• Alle API-Anfragen, die mit einem Organisations-API-Schlüssel gestellt werden, müssen den Stripe-Context-Header enthalten, um das betroffene Konto zu identifizieren.
• Alle API-Anfragen, die mit einem Organisations-API-Schlüssel gestellt werden, müssen den Stripe-Version-Header enthalten, um Konsistenz und Vorhersehbarkeit über alle Integrationen Ihres Unternehmens hinweg zu gewährleisten.

API-Schlüssel der Organisation verwenden

Wenn Sie einen Organisationsschlüssel für die API verwenden, müssen Sie außerdem folgende Schritte ausführen:

• Geben Sie eine API-Version an, indem Sie einen Stripe-Version-Header einfügen. Bei Verwendung eines Stripe-SDK legt das SDK automatisch die API-Version fest.
• Identifizieren Sie das von der API-Anfrage betroffene Konto, indem Sie den Stripe-Context-Header einfügen.

Zum Beispiel bei folgender Organisationsstruktur:

Organization (org_6SD3oI0eSQemPzdmaGLJ5j6)
  ├── Platform account  (acct_1R3fqDP6919yCiFv)
  |   └── Connected account (acct_1032D82eZvKYlo2C)
  └── Standalone account (acct_1aTnTtAAB0hHJ26p)

Sie können den Schlüssel der Organisations-API verwenden, um auf das Guthaben des eigenständigen Kontos zuzugreifen. Sie können denselben Schlüssel auch verwenden, um denselben Aufruf für das verbundene Plattformkonto zu tätigen.

curl https://api.stripe.com/v1/balance \
  -u {{ORG_SECRET_KEY}}: \
  -H "Stripe-Version: {{STRIPE_API_VERSION}}" \
  -H "Stripe-Context: 
{{CONTEXT}}
"

Ersetzen Sie im vorherigen Codebeispiel {{CONTEXT}} durch den entsprechenden Wert:

• Verwenden Sie acct_1aTnTtAAB0hHJ26p für das eigenständige Konto.
• Verwenden Sie für das verbundene Konto einen Pfad, der sowohl die Plattform als auch das verbundene Konto identifiziert, und zwar im Format acct_1R3fqDP6919yCiFv/acct_1032D82eZvKYlo2C.

Sie müssen das betreffende Konto über den Kontext und die API-Version in jeder API-Anfrage mit einem Organisationsschlüssel angeben.

Organizations haben keine veröffentlichbaren API-Schlüssel, weil sie keine Zahlungen akzeptieren können. Sie können Ihren Organisations-API-Schlüssel verwenden, um PaymentIntent für jedes Konto in Ihrer Organisation zu erstellen. Für die clientseitigen Operationen müssen Sie jedoch bestehende kontospezifische, veröffentlichbare Schlüssel verwenden.

Verwaltete API-Schlüssel

Einige Plattformen von Drittanbietern, wie beispielsweise Vercel, können API-Schlüssel in Ihrem Auftrag erstellen und verwalten, wenn Sie deren Integration installieren. Diese Schlüssel werden als verwaltete API-Schlüssel bezeichnet und werden von der Plattform programmgesteuert erstellt, anstatt dass Sie sie manuell im Dashboard erstellen müssen.

Verwaltete API-Schlüssel werden zusammen mit Ihren anderen Schlüsseln auf der Registerkarte API-Schlüssel angezeigt und mit dem Namen der Verwaltungsplattform gekennzeichnet.

Die folgende Tabelle fasst die Unterschiede zwischen nicht verwalteten und verwalteten Schlüsseln zusammen.

Zugriff auf verwaltete Schlüssel widerrufen

Sie können einen verwalteten API-Schlüssel jederzeit widerrufen, indem Sie eine der folgenden Maßnahmen ergreifen:

• Schlüssel ablaufen lassen: Klicken Sie auf der Registerkarte API-Schlüssel auf das Überlaufmenü () für den verwalteten Schlüssel und lassen Sie ihn ablaufen. Dadurch wird der Zugriff der Plattform sofort widerrufen, ohne die Integration zu entfernen.
• Deinstallieren Sie die Integration: Deinstallieren Sie die App der Plattform aus Ihrem Stripe-Konto. Wenn Sie eine App deinstallieren, können Sie wählen, ob die verwalteten Schlüssel sofort ablaufen oder aktiv bleiben sollen.

Geheime und eingeschränkte Schlüssel

Verwenden Sie das Dashboard, um geheime und eingeschränkte Schlüssel zu erstellen, offenzulegen, zu ändern, zu löschen und zu rotieren.

API-Schlüssel erstellen

Sie können einen geheimen API-Schlüssel oder einen eingeschränkten API-Schlüssel erstellen. Ein eingeschränkter API-Schlüssel lässt nur die von Ihnen angegebene Zugriffsebene zu.

So erstellen Sie einen geheimen API-Schlüssel

1. Klicken Sie auf der Registerkarte API-Schlüssel auf Geheimschlüssel erstellen.
2. Geben Sie im Dialogfeld den Verifizierungscode ein, den Stripe Ihnen per E-Mail oder Textnachricht zusendet. Wenn das Dialogfeld nicht automatisch fortgesetzt wird, klicken Sie auf Weiter.
3. Geben Sie einen Namen in das Feld Schlüsselname ein und klicken Sie dann auf Erstellen.
4. Klicken Sie auf den Schlüsselwert, um ihn zu kopieren.
5. Speichern Sie den Schlüsselwert. Sie können ihn später nicht abrufen.
6. 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.

So erstellen Sie einen eingeschränkten API-Schlüssel

1. Führen Sie unter der Registerkarte API-Schlüssel eine der folgenden Aktionen aus:
   • Um einen neuen eingeschränkten Schlüssel zu erstellen, klicken Sie auf Eingeschränkten Schlüssel erstellen. Der Standardwert für alle Berechtigungen ist Keine.
   • 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.
2. 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.
3. 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.
4. Klicken Sie auf Schlüssel erstellen.
5. Geben Sie im Dialogfeld den Verifizierungscode ein, den Stripe Ihnen per E-Mail oder Textnachricht zusendet. Wenn das Dialogfeld nicht automatisch fortgesetzt wird, klicken Sie auf Weiter.
6. Klicken Sie auf den Schlüsselwert, um ihn zu kopieren.
7. Speichern Sie den Schlüsselwert. Sie können ihn später nicht abrufen.
8. 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.

Einen API-Schlüssel offenlegen

In einer Sandbox oder im Live-Modus können Sie einen geheimen API-Schlüssel oder einen eingeschränkten API-Schlüssel offenlegen.

Aus Sicherheitsgründen zeigt Stripe Ihnen im Live-Modus den API-Schlüssel nur einmal an. Bewahren Sie den Schlüssel an einem sicheren Ort auf, an dem Sie ihn nicht verlieren können. Damit Sie sich leichter merken können, wo Sie ihn aufbewahren, können Sie eine Notiz zum Schlüssel im Dashboard hinterlassen. Wenn Sie den Schlüssel verlieren, können Sie ihn neu generieren oder löschen und einen neuen erstellen.

So legen Sie einen geheimen API-Schlüssel in einer Sandbox offen

1. Klicken Sie unter der Registerkarte API-Schlüssel in der Liste Standardschlüssel in der Zeile Geheimschlüssel auf Testschlüssel offenlegen. Sie können den geheimen API-Schlüssel beliebig oft offenlegen.
2. Klicken Sie auf den Schlüsselwert, um ihn zu kopieren.
3. Speichern Sie den Schlüsselwert.
4. Klicken Sie auf Test-Schlüssel ausblenden.

Einen geheimen oder eingeschränkten API-Schlüssel für den Live-Modus offenlegen

1. Klicken Sie unter der Registerkarte API-Schlüssel im Live-Modus in der Liste Standardschlüssel oder Eingeschränkte Schlüssel auf Live-Schlüssel offenlegen für den Schlüssel, den Sie offenlegen möchten.
2. Klicken Sie auf den Schlüsselwert, um ihn zu kopieren.
3. Speichern Sie den Schlüsselwert.
4. Klicken Sie auf Test-Schlüssel ausblenden.
5. Klicken Sie auf das Überlaufmenü () und wählen Sie dann Schlüssel bearbeiten aus.
6. Geben Sie in das Feld Notiz den Ort ein, an dem Sie den Schlüssel gespeichert haben, und klicken Sie dann auf Speichern.

API-Schlüssel auf bestimmte IP-Adressen beschränken

Sie können einen geheimen API-Schlüssel oder einen eingeschränkten API-Schlüssel auf eine Auswahl von IP-Adressen oder eine oder mehrere bestimmte IP Adressen beschränken. Stripe empfiehlt, IP-Einschränkungen für alle Schlüssel im Live-Modus zu aktivieren, um die Verwendung von nicht autorisierten Standorten zu verhindern. Verwenden Sie ggf. separate IP-Zulassungslisten für separate Schlüssel (z. B. um zwischen Staging- und Produktionsumgebungen zu unterscheiden).

Die IP-Adressen müssen das IPv4-Protokoll verwenden. Sie können jeden gültigen CIDR-Bereich angeben. Ein gültiger Bereich wäre zum Beispiel 100.10.38.0 - 100.10.38.255, angegeben als 100.10.38.0/24. Alle IP-Adressen in dem Bereich müssen mit 100.10.38 beginnen.

1. Klicken Sie auf der Registerkarte API-Schlüssel in der Liste Standardschlüssel oder Eingeschränkte Schlüssel auf das Überlaufmenü () für den Schlüssel, den Sie offenlegen möchten.

2. Wählen Sie IP-Einschränkungen verwalten > Nutzung auf eine Reihe von IP-Adressen beschränken aus.

3. Führen Sie einen der folgenden Schritte aus:

   • Geben Sie im Feld IP-Adresse eine einzelne IP-Adresse ein.
   • Geben Sie für einen Bereich von IP-Adressen den Bereich in CIDR-Notation (Classless Inter-Domain Routing) ein. Geben Sie im Feld IP-Adresse die erste Adresse im Bereich ein. Geben Sie im Feld CIDR die Netzwerkpräfixgröße ein.

   Sie können auch die Registerkarte Massenweise verwalten auswählen und einzelne IP-Adressen und -bereiche durch Leerzeichen getrennt eingeben. Änderungen, die Sie in einer Registerkarte vornehmen, werden in der anderen Registerkarte angezeigt.

4. Um eine weitere IP-Adresse oder einen anderen IP-Bereich hinzuzufügen, klicken Sie auf + Hinzufügen.

5. Klicken Sie auf Speichern.

Name oder Notiz eines API-Schlüssels ändern

1. Klicken Sie auf der Registerkarte API-Schlüssel auf das Überlaufmenü () für den Schlüssel, den Sie ändern möchten.
2. Wählen Sie Schlüssel bearbeiten aus.
3. Führen Sie Folgendes aus:
   • Um den Namen zu ändern, geben Sie einen neuen Namen in das Feld Schlüsselname ein.
   • Wenn Sie den Text der Notiz ändern möchten, geben Sie unter Notiz den neuen ́Text ein.
4. Klicken Sie auf Speichern.

API-Schlüssel ablaufen lassen

Wenn Sie einen geheimen API-Schlüssel oder einen eingeschränkten API-Schlüssel ablaufen lassen, müssen Sie einen neuen erstellen und alle Codes aktualisieren, die den abgelaufenen Schlüssel verwenden. Alle Codes, die den abgelaufenen Schlüssel verwenden, können keine API-Aufrufe mehr durchführen.

1. Klicken Sie auf der Registerkarte API-Schlüssel in der Liste Standardschlüssel oder Eingeschränkte Schlüssel auf das Überlaufmenü () für den Schlüssel, den Sie ablaufen lassen möchten.
2. Wählen Sie Schlüssel ablaufen lassen aus.
3. Klicken Sie im Dialogfeld auf Schlüssel ablaufen lassen. Wenn Sie den Schlüssel nicht mehr ablaufen lassen möchten, klicken Sie auf Abbrechen.

Einen API-Schlüssel rotieren

Durch Rotieren eines API-Schlüssels wird dieser widerrufen und ein Ersatzschlüssel generiert, der sofort verwendet werden kann. Sie können auch planen, dass ein API-Schlüssel nach einer bestimmten Zeit rotiert. Der Ersatzschlüssel wird wie folgt benannt:

• Der Name des veröffentlichbaren Ersatzschlüssels ist immer veröffentlichbarer Schlüssel.
• Der Name des Ersatz-Geheimschlüssels ist immer Geheimschlüssel.
• Der eingeschränkte Ersatzschlüsselname ist derselbe wie der des rotierten Schlüssels.

Sie können einen geheimen oder eingeschränkten API-Schlüssel umbenennen, indem Sie den Schlüssel bearbeiten.

Rotieren Sie einen API-Schlüssel in folgenden Szenarien:

• Wenn Sie im Live-Modus einen geheimen oder eingeschränkten API-Schlüssel verlieren und diesen nicht über das Dashboard wiederherstellen können.
• Wenn ein geheimer oder eingeschränkter API-Schlüssel kompromittiert wird, müssen Sie ihn widerrufen, um potenzielle böswillige API-Anfragen zu blockieren, die ihn verwenden könnten.
• Wenn ein Teammitglied mit Zugriff auf den Schlüssel Ihre Organisation verlässt oder die Rollen wechselt.
• Wenn Ihre Richtlinie das Wechseln von Schlüsseln in bestimmten Intervallen erfordert.

Einen API-Schlüssel rotieren

1. Klicken Sie auf der Registerkarte API-Schlüssel auf das Überlaufmenü () für den Schlüssel, den Sie rotieren möchten.
2. Wählen Sie Schlüssel rotieren aus.
3. Wählen Sie im Dropdown-Menü Gültig bisAblaufdatum aus. Wenn Sie Jetzt auswählen, wird der alte Schlüssel gelöscht. Wenn Sie einen Zeitpunkt angeben, wird die verbleibende Zeit bis zum Ablauf des Schlüssels unter dem Schlüsselnamen angezeigt.
4. Klicken Sie auf API-Schlüssel rotieren.
5. Klicken Sie auf den Schlüsselwert, um ihn zu kopieren.
6. Speichern Sie den Schlüsselwert. Sie können ihn später nicht abrufen.
7. Geben Sie in das Feld Notiz hinzufügen den Speicherort ein, an dem Sie den Schlüssel gespeichert haben, und klicken Sie dann auf Speichern oder Fertig.

Zugriff eines API-Schlüssels wiederherstellen

An API key might have its access limited if it hasn’t been used to create transfers, payouts, or update payout destinations for over 180 days. You can’t use a limited access key to create payouts and transfers or to create payout destinations. You can restore access to use the key normally or to perform a blocked action.

So stellen Sie den Zugriff für einen API-Schlüssel wieder her

1. Klicken Sie auf der Registerkarte API-Schlüssel auf das Überlaufmenü () für den Schlüssel, den Sie wiederherstellen möchten.
2. Wählen Sie Zugriff wiederherstellen.
3. Klicken Sie auf Wiederherstellen.

API-Anfrage-Logs anzeigen

Um die API-Anfrage-Logs zu öffnen, klicken Sie für einen beliebigen Schlüssel auf das Überlaufmenü () und wählen Anfrage-Logs-anzeigen aus. Durch Öffnen der Logs kehren Sie zum Stripe-Dashboard zurück.