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。