Stripe API 密钥全解:测试与正式、可公开与保密、受限密钥

Stripe 的 publishable、secret 和 restricted 密钥分别该放在哪里?本文讲清测试与正式模式、最小权限、首次请求、密钥轮换与常见报错。

用 Apifox,节省研发团队的每一分钟

Stripe API 密钥全解:测试与正式、可公开与保密、受限密钥

免费使用 Apifox

相关推荐

最新文章

API

一体化协作平台

API 设计

API 文档

API 调试

自动化测试

API Mock

API Hub

立即体验 Apifox
目录

每个 Stripe 集成都从同一个问题开始:哪个密钥放在哪里?Stripe 提供可公开密钥、私密密钥,以及可选的受限密钥,每种都有测试和正式两个版本。放错位置,轻则花一下午排查 401,重则泄露动钱能力。本文介绍每种密钥的用途、位置、第一个测试模式请求,以及如何让正式密钥远离共享内容。通用概念可先读《API Token(凭证)是什么?怎么使用?》。以下依据 Stripe 的 API 密钥文档,核查于 2026 年 9 月。

密钥在控制台中的位置

打开 dashboard.stripe.com/apikeys。它位于 Developers 下,显示当前账户或沙箱的密钥。开关可在沙箱和正式模式间切换,列表随之变化。

页面有两个列表:

  • 标准密钥:可公开密钥和私密密钥。
  • 受限密钥:带权限范围的密钥。

沙箱中可随时显示所有密钥。正式模式下,自行创建的私密密钥只在创建时显示一次,关闭对话框前请复制到密码库;丢失只能轮换。只有 Stripe 生成的默认密钥能在正式模式再次显示。

页面不显示 webhook 签名密钥。它们按端点存放在 Webhooks 下,不是 API 密钥。

可公开密钥与私密密钥

名称本身就说明了信任边界。

Stripe 可公开、私密和受限 API 密钥对比
密钥 前缀 可安全暴露 能力
可公开 pk_test_ / pk_live_ 是 标识账户,在 Stripe.js、Elements 和移动 SDK 中把卡号转成 token 和 PaymentMethod
私密 sk_test_ / sk_live_ 否 创建扣款、退款、读取客户数据、触发打款
受限 rk_test_ / rk_live_ 否 仅限授予的资源和权限

可公开密钥属于浏览器或移动应用。它把卡号变成 token,不能创建扣款或读取账户数据,放在前端是预期行为。

私密密钥只该放在服务器。Stripe 文档现在表示“不建议在新用例中使用私密密钥”,并引导使用受限密钥。无限制私密密钥仍可用,但应只作为应急手段,而不是默认选择。

测试模式与正式模式

Stripe 运行两个独立世界,各有密钥。测试密钥(文档称沙箱,前缀仍是 _test_)返回模拟对象:假客户、假 PaymentIntent、可命令成功或拒付的测试卡,不涉及真钱。正式密钥连接卡组织,调动真实资金。

隔离非常严格。用 sk_test_ 创建的客户在 sk_live_ 看来不存在,反之亦然。错误码 livemode_mismatch 表示测试和正式模式的密钥、请求与对象只能在对应模式内使用。

两条规则:

  • 全程使用 sk_test_ 或 rk_test_ 构建和测试。新集成建议单独创建沙箱。
  • 切换正式模式是配置变更,不是代码变更。服务器从环境变量或密码库读取密钥,上线只改值。

每个响应都包含 livemode 布尔值。在测试中断言它,是防止用错密钥部署的成本最低的保障。

受限密钥与最小权限

受限 API 密钥(RAK)是带权限掩码的私密密钥。创建时为每个资源组选择 None、Read 或 Write,默认 None。Write 包含 Read;GET 需要 Read,POST 和 DELETE 需要 Write。

点击 API 密钥页面的 Create restricted key,选择预设或从零开始,命名、设置权限并完成两步验证。密钥值只显示一次。

受限密钥指南建议每个服务一个密钥:计费服务获得 Invoices 和 Customers 的 Write,报表任务获得 Charges 和 Disputes 的 Read。某个服务被攻破时,攻击者被限制在该密钥权限内。只读的 Disputes 密钥无法创建扣款,也无法触碰打款。

先在沙箱给新密钥较宽权限,运行测试,再打开请求日志(溢出菜单 View request logs),删掉没有流量的权限。Stripe 还允许给用于自主 AI Agent 的密钥打标签,使其受打款和退款审批规则约束;请走这条路径,而不是普通私密密钥。

用 curl 和 Python 发出第一个请求

Stripe 使用 HTTP Basic Auth:密钥是用户名,密码为空。末尾冒号告诉 curl 不提示密码:

export STRIPE_API_KEY=sk_test_...   # 你的沙箱私密密钥

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

响应是 PaymentIntent,id 以 pi_ 开头,status 为 "requires_payment_method",livemode 为 false。

Stripe 也接受 -H "Authorization: Bearer $STRIPE_API_KEY",这是 Apifox 和大多数 HTTP 客户端使用的形式。两者携带的是同一把密钥;发送方式见《如何在请求头中添加和传递 Bearer Token》。请求必须走 HTTPS,明文 HTTP 会失败,见认证参考。

Python 当前 SDK 使用从环境读取密钥的 StripeClient:

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

文件中不出现密钥字符串。同一段代码会根据环境提供的是测试密钥还是正式密钥,分别运行在测试或正式模式。

让编程 Agent 用 Apifox CLI 测试 Stripe 密钥

Curl 只能证明密钥能用一次。编程 Agent 可以通过 Apifox CLI 把它变成可重复检查,并让密钥远离共享项目。先配置(令牌在账号设置 > API 访问令牌):

npm install -g apifox-cli@latest
apifox login --with-token <YOUR_TOKEN>
npx -y skills add https://apifox.com   # 按提示选择你的 Agent

给 Agent 一段提示:

Use Apifox 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.

它运行的命令(对照 Apifox CLI 2.2.7):

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

categoryId 是测试用例在前端显示的必填项:先用 apifox test-case category --project <id> 取到分组 ID 写进 pi-case.json,否则会出现创建成功但前端看不到。

Stripe v1 端点不接受 JSON,所以提示词里指定了表单编码。livemode 断言是绊线:一旦有人用正式密钥运行,它会在第二次请求发出前失败。CI 中同一条 apifox run 命令从流水线密钥存储读取密钥;《怎么把接口测试塞进 CI CD 流水线?用 Apifox CLI 自动跑测试》这篇指南里有可复制版本。请求定义共享,正式凭据永不共享。

轮换密钥与泄露处理

Stripe 的密钥处理指南很直接:任何提交到仓库、粘贴到聊天或打印到日志的内容,都应视为已泄露,即使不确定有没有人看到。

轮换内置于控制台。从密钥溢出菜单选择 Rotate key,为旧密钥设置过期时间,复制新密钥。宽限期内两者都可用,最长 7 天,因此可以逐步切换,并在请求日志里盯住漏改的调用;选择 Now 则立即吊销旧密钥。

如果私密或受限密钥泄露:

  • 立即轮换,设置较短过期时间。
  • 更新所有使用它的服务器,在请求日志确认流量,再让旧密钥过期。
  • 在 Workbench 检查近期活动:不认识的关联账户、不是你发起的打款、新银行账户。
  • 暂停可疑打款,撤回已发出的款项,并尽快退还欺诈扣款,以便尽早避免拒付争议。
  • 同时轮换其他密钥。一把泄露,就假设泄露渠道看到了更多。

Stripe 会扫描暴露密钥并通知你,有时主动停用,但检测不保证。在仓库和 CI 配置搜索 sk_live_ 和 rk_live_ 是五分钟审计;在 pre-commit hook 加《如何使用 Secret Scanner 发现并解决泄漏的 API Key》可阻止下一次泄露。Stripe 绝不会索要私密密钥,索要它的消息都是钓鱼。

常见错误

常见 Stripe API 密钥错误及修复
症状 含义 修复
401 “No valid API key provided” 密钥缺失、格式错误或已吊销 检查请求头;确认未被轮换
api_key_expired 密钥已轮换或过期 从控制台获取当前密钥
secret_key_required 把 pk_ 密钥发到了服务端端点 后端使用 sk_ 或 rk_
已知 ID 返回 resource_missing 模式错误:测试密钥访问正式对象,或反之 让密钥模式与对象匹配
403 “doesn’t have permissions…” 受限密钥缺少该资源的 Read 或 Write 编辑权限;错误体会指出缺少什么
livemode_mismatch 请求中混用测试和正式密钥或对象 每个环境保持同一模式

401 和 403 在 Python SDK 中对应 stripe.AuthenticationError 和 stripe.PermissionError,见错误参考,这样可以单独捕获这两类错误。正式密钥如果连续 180 天未用于发起转账或打款,相关操作会受限,密钥页面提供 Restore access 操作。

常见问题

可公开密钥放前端安全吗?

安全。pk_ 密钥可 token 化卡信息,但不能创建扣款、读取客户或转移资金。只有私密和受限密钥需要留在服务端。

可以在测试模式使用受限密钥吗?

可以。受限密钥在两种模式都存在(rk_test_ 和 rk_live_)。建议先调整测试版本,再创建权限匹配的正式密钥。

webhook 签名密钥和 API 密钥是同一个吗?

不是。签名密钥按 webhook 端点签发,只验证事件来自 Stripe,位于 Webhooks 下。接入时请参阅《如何在 CI 中使用 Apifox 捕获并验证 Stripe Webhook》。

生产环境用测试密钥会怎样?

请求成功,但不扣款、不转移资金。每个对象返回的 livemode 都是 false,断言该字段会在客户发现问题前抓住错误。

简要总结

可公开密钥放客户端,私密和受限密钥留服务端;测试与正式绝不混用;能划清范围时受限密钥优于私密密钥。正式密钥放密码库,运行时把测试密钥传给 Apifox CLI,并在每个测试用例中保留 livemode 断言。