---
title: "API 金鑰"
description: "驗證您的 API 請求，並妥善保管您的金鑰。"
source: "https://docs.tokenz.one/zh-TW/v2/checkout/api-keys"
api_version: "v2"
locale: "zh-TW"
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 中。
- **將其儲存在環境變數或機密管理工具（secrets manager）中**，而不要放在程式碼庫裡。

> 金鑰僅在建立時**顯示一次**。請當場複製並妥善保管。若遺失，請建立新的金鑰，而不要嘗試找回舊金鑰。

## 只授予金鑰所需的範圍

建立金鑰時，您可以選擇其**權限（scope）**——例如結帳工作階段的建立／讀取、訂單的讀取／取消、配送記錄、商品讀取、退款的建立／讀取、兌換碼的驗證／兌換，或訂閱方案變更。

請為每個金鑰授予其所需的**最小權限**：

- **每個整合或服務使用各自的金鑰**，只授予該整合用到的範圍。僅讀取訂單的報表工作不需要退款或結帳權限。
- 若一個範圍受限的金鑰外洩，影響範圍很小，您可以只撤銷該金鑰，而不影響其他部分。

## 金鑰的輪替與撤銷

- **輪替**方式為：建立一個新金鑰並部署，然後在 **Developers → API keys** 中刪除舊金鑰。由於可以同時持有多個金鑰，您可以在不停機的情況下完成輪替。
- **一旦金鑰外洩**（提交到儲存庫、貼到工單、寫入記錄檔），請立即刪除。刪除金鑰即會撤銷它，使用該金鑰的任何請求都將失效。接著再簽發一個新金鑰。

## Webhook 簽章金鑰

Webhook 端點的**簽章金鑰**與您的 API 金鑰是分開的。Tokenz 會用它為每個 Webhook 簽章，您則針對**原始請求內容（raw body）**驗證 `Tokenz-Signature` 標頭，以確認事件的真實性。簽章金鑰也應像 API 金鑰一樣保存在伺服器端。

有關如何驗證簽章，請參閱 [Webhook](https://docs.tokenz.one/zh-TW/v2/checkout/webhooks-get-started)。