Saltar al contenido principal

Authentication and key management

The Stripe API authenticates every request with an API key. The key identifies your account and carries the permissions of the role that created it. One leaked secret key exposes every charge, customer, and payout on the account.

Key types​

Each account holds three kinds of key. Only one of them belongs on a server.

KeyPrefixSafe in a browserUse for
Publishablepk_test_, pk_live_YesClient-side tokenization and Stripe.js. Grants no API access.
Secretsk_test_, sk_live_NoServer-side API calls. Full account permissions.
Restrictedrk_test_, rk_live_NoServer-side calls limited to named resources and operations.

A secret key reads and writes everything the account owns. A restricted key narrows that surface to the resources you list, such as read-only access to charges. Use a restricted key wherever the integration doesn't need the full account.

peligro

Never ship a secret or restricted key in client code, a mobile binary, a public repository, or a support ticket. Anyone who holds the key can move money.

Send the key​

Pass the key as the Basic auth username with an empty password. Stripe accepts the same value as a bearer token, but the documented form for cURL is the username field.

curl https://api.stripe.com/v1/balance \
-u "$STRIPE_SECRET_KEY:"
Node.js
const response = await fetch("https://api.stripe.com/v1/balance", {
headers: { Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}` },
});
Python
import os, requests

response = requests.get(
"https://api.stripe.com/v1/balance",
auth=(os.environ["STRIPE_SECRET_KEY"], ""),
)

Requests must use HTTPS. A request over plain HTTP fails before Stripe reads the key.

Store the key​

Load the key from the environment at runtime. Never commit it, and never log it.

.env
STRIPE_SECRET_KEY=sk_test_51N...
server.js
if (!process.env.STRIPE_SECRET_KEY) {
throw new Error("STRIPE_SECRET_KEY is not set");
}

Add the environment file to .gitignore. Hosted platforms keep the value in a secret store and inject it into the process environment. That keeps the key out of the repository and out of build logs.

Verify the connection​

Send one read request. A 200 response with a balance object confirms the key, the base URL, and the network path.

curl -s https://api.stripe.com/v1/balance -u "$STRIPE_SECRET_KEY:" | jq '.object, .livemode'

The output reads "balance" and false for a test key. A 401 means the key is wrong for this account, revoked, or missing. A 403 means a restricted key lacks permission for the resource.

Scope a restricted key​

A restricted key lists permissions per resource. Grant the smallest set that the integration needs.

IntegrationSuggested permissions
Reporting jobRead on charges, balance transactions, and payouts.
Checkout serverWrite on payment intents and refunds. Read on customers.
Webhook verifierRead on events. No write permissions.

Name each key for the service that uses it. A name such as checkout-api-prod makes an incident review fast, because the audit log shows which key acted.

Rotate a key​

Rotate on a schedule and after any suspected exposure. Stripe keeps several keys active at once, so a rotation needs no downtime.

  1. Create a replacement key with the same permissions.
  2. Add it to the secret store under a new name.
  3. Deploy the service that reads the new name.
  4. Confirm traffic succeeds on the new key.
  5. Revoke the old key in the Dashboard.
  6. Review the request log for calls from the old key after the deploy.
aviso

Revoking first breaks production. Deploy the new key before you revoke the old one, and watch the error rate between the two steps.

Respond to a leak​

Treat a secret key in a repository, a log, or a chat message as compromised.

  1. Revoke the key in the Dashboard under Developers → API keys.
  2. Create a replacement and deploy it.
  3. Review the request log for unknown IP addresses or unusual endpoints.
  4. Check the balance and payout history for movements you did not start.
  5. Contact Stripe support if you find unauthorized activity.

Revocation takes effect immediately. A revoked key fails on its next request.

Common failures​

SymptomCauseFix
401 Invalid API Key providedKey is truncated, revoked, or from another account.Re-copy the key from the Dashboard.
403 on one resourceA restricted key lacks permission.Add the permission or use a key with a wider scope.
401 in production onlyThe environment variable is empty in that deployment.Check the secret store for the production environment.
Request hangs, then failsA proxy blocks outbound HTTPS to api.stripe.com.Allow the host on port 443.

Next steps​