---
title: "API 密钥"
description: "对 API 请求进行身份验证，并妥善保管您的密钥。"
source: "https://docs.tokenz.one/zh-CN/v2/checkout/api-keys"
api_version: "v2"
locale: "zh-CN"
version_status: "current"
docs_stage: "prod"
---

# API 密钥

对 API 请求进行身份验证，并妥善保管您的密钥。

## 简介

对 Tokenz API 的每个请求，都通过以 Bearer 令牌形式发送的**私密 API 密钥**进行身份验证：

```bash
curl https://api.tokenz.one/v2/checkoutsession \
  --header 'Authorization: Bearer secret_test_YOUR_KEY_HERE'
```

Tokenz 仅使用**私密密钥**，没有可公开的（publishable）客户端密钥。私密密钥可以在您的账户上创建付款并读取订单数据，因此**绝不能离开您的服务器**。

您可以在后台的 **Developers → API keys** 中创建和管理密钥。

## 测试密钥与正式密钥

每个密钥都属于一种模式：

| 前缀 | 模式 | 是否涉及资金 |
| --- | --- | --- |
| `secret_test_…` | 测试 | 否 —— 仅为模拟付款 |
| `secret_live_…` | 正式 | 是 —— 真实付款 |

请使用**测试**密钥构建和测试您的集成，然后在生产环境中切换为**正式**密钥。测试密钥无法处理真实付款，正式密钥也不能在测试模式下使用，因此请将两者放在不同的环境配置中（例如，每个环境取值不同的 `TOKENZ_SECRET_KEY` 变量）。

## 妥善保管您的私密密钥

由于不存在可在客户端安全使用的密钥，请像对待密码一样对待私密密钥：

- **仅在服务器端使用。** 绝不要将其放入浏览器代码、移动应用、单页应用打包文件，或任何会发送到用户设备的内容中。
- **绝不要将其提交**到源代码管理，也不要出现在日志、错误信息和 URL 中。
- **将其存储在环境变量或密钥管理工具中**，而不是代码库里。

> 密钥仅在创建时**显示一次**。请当场复制并妥善保管。如果丢失，请创建新密钥，而不要尝试找回旧密钥。

## 只授予密钥所需的权限

创建密钥时，您可以选择其**权限（scope）**——例如结账会话的创建/读取、订单的读取/取消、配送记录、商品读取、退款的创建/读取、兑换码的验证/兑换，或订阅套餐变更。

请为每个密钥授予其所需的**最小权限**：

- **每个集成或服务使用单独的密钥**，只授予该集成用到的权限。仅读取订单的报表任务不需要退款或结账权限。
- 如果一个权限受限的密钥泄露，影响范围很小，您可以只吊销该密钥，而不影响其他部分。

## 轮换和吊销密钥

- **轮换**方法是：创建一个新密钥并部署，然后在 **Developers → API keys** 中删除旧密钥。由于可以同时持有多个密钥，您可以在不停机的情况下完成轮换。
- **一旦密钥泄露**（提交到仓库、粘贴到工单、写入日志），请立即删除。删除密钥即会将其吊销，使用该密钥的任何请求都将失效。然后再签发一个新密钥。

## Webhook 签名密钥

Webhook 端点的**签名密钥**与您的 API 密钥是分开的。Tokenz 用它对每个 Webhook 进行签名，您则针对**原始请求正文**验证 `Tokenz-Signature` 头，以确认事件的真实性。签名密钥也应像 API 密钥一样保存在服务器端。

有关如何验证签名，请参阅 [Webhook](https://docs.tokenz.one/zh-CN/v2/checkout/webhooks-get-started)。