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.
| Key | Prefix | Safe in a browser | Use for |
|---|---|---|---|
| Publishable | pk_test_, pk_live_ | Yes | Client-side tokenization and Stripe.js. Grants no API access. |
| Secret | sk_test_, sk_live_ | No | Server-side API calls. Full account permissions. |
| Restricted | rk_test_, rk_live_ | No | Server-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.
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:"
const response = await fetch("https://api.stripe.com/v1/balance", {
headers: { Authorization: `Bearer ${process.env.STRIPE_SECRET_KEY}` },
});
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.
STRIPE_SECRET_KEY=sk_test_51N...
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.
| Integration | Suggested permissions |
|---|---|
| Reporting job | Read on charges, balance transactions, and payouts. |
| Checkout server | Write on payment intents and refunds. Read on customers. |
| Webhook verifier | Read 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.
- Create a replacement key with the same permissions.
- Add it to the secret store under a new name.
- Deploy the service that reads the new name.
- Confirm traffic succeeds on the new key.
- Revoke the old key in the Dashboard.
- Review the request log for calls from the old key after the deploy.
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.
- Revoke the key in the Dashboard under Developers → API keys.
- Create a replacement and deploy it.
- Review the request log for unknown IP addresses or unusual endpoints.
- Check the balance and payout history for movements you did not start.
- Contact Stripe support if you find unauthorized activity.
Revocation takes effect immediately. A revoked key fails on its next request.
Common failures
| Symptom | Cause | Fix |
|---|---|---|
401 Invalid API Key provided | Key is truncated, revoked, or from another account. | Re-copy the key from the Dashboard. |
403 on one resource | A restricted key lacks permission. | Add the permission or use a key with a wider scope. |
401 in production only | The environment variable is empty in that deployment. | Check the secret store for the production environment. |
| Request hangs, then fails | A proxy blocks outbound HTTPS to api.stripe.com. | Allow the host on port 443. |
Next steps
- Idempotent requests to make a retried
POSTsafe. - Errors and retries to map each failure to a recovery step.
- API versioning and upgrades to pin response shapes.