Stripe API-Schlüssel erklärt: Test vs. Live, Publishable vs. Secret und Restricted Keys

Jede Stripe-Integration beginnt mit derselben Frage: Welcher Schlüssel gehört wohin? Stripe gibt Ihnen einen Publishable Key, einen Secret Key und die Möglichkeit, eingeschränkte Schlüssel zu erstellen – jeweils in einer Test- und einer Live-Variante. Setzen Sie den falschen an die falsche Stelle, geben Sie entweder die Möglichkeit preis, Geld zu bewegen, oder verlieren einen Nachmittag an einen 401. Dieser Leitfaden behandelt, was jeder Stripe-API-Schlüssel tut, wo er liegt, wie man eine erste Anfrage im Testmodus sendet und wie man den Live-Schlüssel aus allem heraushält, was geteilt wird. Für das allgemeine Konzept beginnen Sie zunächst mit was ein API-Schlüssel ist. Alles Folgende richtet sich nach Stripes API-keys-Dokumentation, geprüft im September 2026.

Wo Ihre Stripe-API-Schlüssel im Dashboard liegen

Öffnen Sie die API-keys-Seite unter dashboard.stripe.com/apikeys. Sie befindet sich im Dashboard unter Developers und zeigt die Schlüssel für das Konto oder die Sandbox an, die Sie gerade ansehen. Ein Umschalter wechselt zwischen Sandbox-Modus und Live-Modus, und die Schlüsselliste ändert sich entsprechend.

Die Seite enthält zwei Listen:

• Standard keys enthalten Ihren Publishable Key und Ihren Secret Key.
• Restricted keys enthalten alle Schlüssel, die Sie mit eingeschränkten Berechtigungen erstellt haben.

Die Sichtbarkeit unterscheidet sich je nach Modus. In einer Sandbox können Sie jeden Schlüssel jederzeit einblenden. Im Live-Modus wird ein Secret Key, den Sie selbst erstellen, einmal angezeigt – bei der Erstellung. Kopieren Sie ihn in Ihren Tresor, bevor Sie den Dialog schließen; ihn zu verlieren bedeutet, ihn rotieren zu müssen. Nur die von Stripe generierten Standard-Schlüssel können im Live-Modus erneut eingeblendet werden.

Eines zeigt die Seite nicht: Webhook-Signaturgeheimnisse. Diese liegen unter Webhooks, pro Endpoint, und sind überhaupt keine API-Schlüssel.

Publishable vs. Secret Keys

Die Namen beschreiben die Vertrauensgrenze.

Ein Publishable Key gehört in den Browser oder die mobile App. Er verwandelt eine Kartennummer in einen Token und kaum mehr. Er kann keine Charge erstellen oder Kontodaten lesen, daher ist es zu erwarten, ihn im Frontend-Code auszuliefern.

Ein Secret Key gehört auf Ihren Server und nirgendwo sonst. Stripes Empfehlung hat sich geändert: Die Dokumentation sagt jetzt, sie „empfehlen nicht die Verwendung von Secret Keys für neue Anwendungsfälle“ und verweist stattdessen auf Restricted Keys. Der uneingeschränkte Secret Key funktioniert weiterhin, aber behandeln Sie ihn als Notfalllösung, nicht als Standard.

Test- vs. Live-Modus-Schlüssel

Stripe betreibt zwei getrennte Welten, jede mit ihrem eigenen Schlüsselsatz. Test-Schlüssel (neuere Dokumentation nennt die Testseite eine Sandbox, obwohl die Präfixe weiterhin _test_ lauten) liefern simulierte Objekte: gefälschte Kunden, gefälschte PaymentIntents, Testkarten, die auf Befehl erfolgreich sind oder abgelehnt werden, kein echtes Geld. Live-Schlüssel treffen Kartennetzwerke und bewegen echte Gelder.

Die Trennung ist strikt. Ein Kunde, der mit sk_test_ erstellt wurde, existiert für sk_live_ nicht, und umgekehrt. Stripes Fehlercode für das Kreuzen der Ströme, livemode_mismatch, sagt es unmissverständlich: „Test and live mode API keys, requests, and objects are only available within the corresponding mode.“

Daraus folgen zwei praktische Regeln:

• Entwickeln und testen Sie vollständig gegen sk_test_ oder rk_test_. Stripe empfiehlt eine separate allgemeine Sandbox für neue Integrationen, damit deren Einstellungen und Daten isoliert bleiben.
• Der Wechsel zu Live ist eine Konfigurationsänderung, keine Codeänderung. Ihr Server liest den Schlüssel aus einer Umgebungsvariable oder einem Tresor, und live zu gehen bedeutet, diesen Wert zu ändern.

Jede API-Antwort enthält einen booleschen Wert livemode. Prüfen Sie ihn in Ihren Tests; er ist die günstigste Absicherung gegen ein Deployment mit dem falschen Schlüssel.

Restricted Keys und geringste Berechtigungen

Ein Restricted API Key (Stripe kürzt ihn mit RAK ab) ist ein Secret Key mit einer Berechtigungsmaske. Wenn Sie einen erstellen, wählen Sie eine Berechtigung für jede Ressourcengruppe: None, Read oder Write. Alles ist standardmäßig auf None gesetzt. Write schließt Read ein, und die Zuordnung zu HTTP ist einfach: GET benötigt Read, POST und DELETE benötigen Write.

Um einen zu erstellen, klicken Sie auf der API-keys-Seite auf Create restricted key, wählen Sie ein vorkonfiguriertes Berechtigungsset oder beginnen Sie bei null, benennen Sie ihn, legen Sie Berechtigungen fest und schließen Sie die Zwei-Faktor-Abfrage ab. Wie bei einem selbst erstellten Secret Key im Live-Modus sehen Sie den Wert nur einmal.

Der Restricted-keys-Leitfaden schlägt einen Schlüssel pro Dienst vor: Ein Billing-Dienst erhält Write auf Invoices und Customers, ein Reporting-Job erhält Read auf Charges und Disputes. Wenn ein Dienst kompromittiert wird, ist der Angreifer auf die Berechtigungen dieses Schlüssels beschränkt. Ein schreibgeschützter Disputes-Schlüssel kann keine Charge erstellen oder ein Payout anfassen.

Geben Sie einem neuen Schlüssel in einer Sandbox breite Berechtigungen, führen Sie Ihre Testsuite aus, öffnen Sie dann die Request-Logs des Schlüssels (Überlaufmenü, View request logs) und entfernen Sie jede Berechtigung, die keinen Traffic gesehen hat. Stripe erlaubt es außerdem, Schlüssel für autonome KI-Agenten zu kennzeichnen, damit sie unter Genehmigungsregeln für Payouts und Refunds fallen; nutzen Sie diesen Weg statt eines einfachen Secret Keys.

Ihre erste Anfrage mit curl und Python

Stripe authentifiziert mit HTTP Basic Auth: Der Schlüssel ist der Benutzername und das Passwort ist leer. Der abschließende Doppelpunkt sagt curl, nicht nachzufragen:

export STRIPE_API_KEY=sk_test_...   # your sandbox secret key

curl https://api.stripe.com/v1/payment_intents \
  -u "$STRIPE_API_KEY:" \
  -d amount=2000 \
  -d currency=usd \
  -d "automatic_payment_methods[enabled]=true"

Die Antwort ist ein PaymentIntent mit einer id, die mit pi_ beginnt, status: "requires_payment_method" und livemode: false. Das letzte Feld bestätigt, dass Sie einen Testschlüssel verwendet haben.

Stripe akzeptiert auch -H "Authorization: Bearer $STRIPE_API_KEY", was die Form ist, die Apidog und die meisten HTTP-Clients verwenden. Beide tragen denselben Schlüssel; wenn Sie unsicher sind, welcher Stil zu Ihrem Stack passt, behandelt unser Vergleich von API-Schlüsseln und Bearer-Tokens die Kompromisse. Anfragen müssen über HTTPS erfolgen; einfaches HTTP schlägt gemäß der Authentifizierungsreferenz direkt fehl.

In Python ist das aktuelle SDK-Muster ein StripeClient, der den Schlüssel aus der Umgebung liest:

import os
import stripe

client = stripe.StripeClient(os.environ["STRIPE_API_KEY"])

intent = client.v1.payment_intents.create({
    "amount": 2000,
    "currency": "usd",
    "automatic_payment_methods": {"enabled": True},
})
print(intent.id, intent.livemode)  # pi_..., False

Keine Schlüsselzeichenkette erscheint in der Datei. Derselbe Code läuft gegen Test oder Live, je nachdem, was die Umgebung bereitstellt.

Lassen Sie Ihren Coding-Agenten den Stripe-Schlüssel mit der Apidog CLI testen

Curl beweist einmal, dass der Schlüssel funktioniert. Ihr Coding-Agent kann daraus eine wiederholbare Prüfung über die Apidog CLI machen und den Schlüssel aus dem geteilten Projekt heraushalten. Richten Sie sie einmal ein (der Token befindet sich unter Account Settings, API Access Token):

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick your agent when prompted

Geben Sie dem Agenten dann einen Prompt:

Use Apidog CLI on project <id>. Create a "Stripe Test" environment with base URL
https://api.stripe.com. Add POST /v1/payment_intents with Bearer auth from
{{stripe_secret_key}} and a form-urlencoded body: amount=2000, currency=usd.
Create a test case asserting status 200, an id starting with pi_ and
livemode false, then run it and summarize any failures.

Die Befehle, die er ausführt, geprüft gegen Apidog CLI 2.2.7:

apidog environment create "Stripe Test" --project <id> --base-url https://api.stripe.com
apidog cli-schema get endpoint-create
apidog endpoint create --project <id> --file payment-intents.json
apidog cli-schema validate test-case-create --file pi-case.json
apidog test-case create --project <id> --file pi-case.json
apidog run --test-case <caseId> --project <id> -e <envId> \
  --env-var "stripe_secret_key=$STRIPE_API_KEY" -r cli,json

Der Prompt nennt die Form-Kodierung, weil Stripes v1-Endpunkte kein JSON akzeptieren. Die livemode-Prüfung ist Ihr Stolperdraht: Wenn jemand den Fall mit einem Live-Schlüssel ausführt, schlägt er fehl, bevor eine zweite Anfrage rausgeht. In CI liest dieselbe apidog run-Zeile den Schlüssel aus dem Secret Store Ihrer Pipeline; unser Leitfaden zur Apidog CLI CI/CD-Pipeline enthält eine zum Kopieren geeignete Version. Die Request-Definition wird geteilt; das Live-Credential nie.

Schlüssel rotieren und was zu tun ist, wenn einer leakt

Stripes eigener Leitfaden zum Umgang mit Schlüsseln ist unverblümt: Gehen Sie davon aus, dass alles, was in ein Repo committet, in einen Chat eingefügt oder in ein Log gedruckt wurde, kompromittiert ist – selbst wenn Sie sich nicht sicher sind, ob es jemand gesehen hat.

Die Rotation ist im Dashboard integriert. Wählen Sie im Überlaufmenü eines Schlüssels Rotate key, legen Sie ein Ablaufdatum für den alten Schlüssel fest und kopieren Sie den Ersatz. Beide funktionieren während der Übergangsfrist von bis zu 7 Tagen, sodass Sie schrittweise ausrollen und die Request-Logs auf Nachzügler überwachen können. Now widerruft den alten Schlüssel sofort.

Wenn ein Secret- oder Restricted Key leakt:

• Rotieren Sie ihn sofort mit einem kurzen Ablaufdatum.
• Aktualisieren Sie jeden Server, der ihn verwendet hat, bestätigen Sie den Traffic in den Request-Logs und lassen Sie den alten Schlüssel dann ablaufen.
• Überprüfen Sie die aktuelle Aktivität in Workbench auf alles, was Ihre Integration nicht tun würde: nicht erkannte verbundene Konten, Payouts, die Sie nicht initiiert haben, neue Bankkonten.
• Pausieren Sie verdächtige Payouts, kehren Sie bereits gesendete um und erstatten Sie betrügerische Charges schnell, um Disputes zuvorzukommen.
• Rotieren Sie auch Ihre anderen Schlüssel. Wenn einer geleakt ist, gehen Sie davon aus, dass der Kanal, der ihn geleakt hat, mehr gesehen hat.

Stripe scannt nach offengelegten Schlüsseln und wird Sie benachrichtigen, manchmal den Schlüssel proaktiv deaktivieren, aber die Erkennung ist nicht garantiert. Die Suche in Ihren Repos und CI-Konfigurationen nach sk_live_ und rk_live_ ist ein Fünf-Minuten-Audit, und ein Secret Scanner in einem Pre-Commit-Hook verhindert, dass der nächste durchkommt. Stripe fragt Sie nie nach Ihrem Secret Key, jede Nachricht, die ihn anfordert, ist Phishing.

Häufige Stripe-API-Schlüsselfehler

Die 401- und 403-Fälle entsprechen stripe.AuthenticationError und stripe.PermissionError im Python-SDK gemäß der Fehlerreferenz, sodass Sie sie gezielt abfangen können. Ein weniger offensichtlicher Fall: Ein Live-Schlüssel, der 180 Tage lang keine Transfers oder Payouts erstellt hat, wird für diese Aktionen eingeschränkt, mit einer Option Restore access am Schlüssel.

FAQ

Ist es sicher, einen Stripe-Publishable-Key in meinen Frontend-Code zu legen?

Ja. Ein pk_-Schlüssel tokenisiert Kartendetails, kann aber keine Charges erstellen, Kunden lesen oder Geld bewegen. Nur Secret- und Restricted Keys bleiben serverseitig.

Kann ich einen Restricted Key im Testmodus verwenden?

Ja. Restricted Keys existieren in beiden Modi (rk_test_ und rk_live_). Stripe empfiehlt, zuerst die Testversion abzustimmen und dann einen Live-Schlüssel mit passenden Berechtigungen zu erstellen.

Ist das Webhook-Signaturgeheimnis dasselbe wie mein API-Schlüssel?

Nein. Signaturgeheimnisse werden pro Webhook-Endpunkt ausgestellt und verifizieren nur, dass ein eingehendes Event von Stripe kam. Sie liegen unter Webhooks, nicht auf der API-keys-Seite. Wenn Sie diese einrichten, sehen Sie, wie man Stripe-Webhooks in CI testet.

Was passiert, wenn ich einen Testschlüssel in der Produktion verwende?

Anfragen sind erfolgreich, aber es wird keine Karte belastet und kein Geld bewegt. Da livemode bei jedem Objekt false zurückgibt, fängt eine Prüfung dieses Feldes den Fehler ab, bevor es Ihre Kunden tun.

Die Kurzfassung

Publishable Keys gehören in den Client, Secret- und Restricted Keys bleiben auf dem Server, Test und Live werden nie vermischt, und Restricted schlägt Secret, wann immer Sie es eingrenzen können. Halten Sie den Live-Schlüssel in einem Tresor, übergeben Sie den Testschlüssel zur Laufzeit an die Apidog CLI und behalten Sie in jedem Testfall, den Ihr Agent schreibt, eine livemode-Prüfung bei.