API Key 與安全
區分憑證、限制寄件網域範圍，安全輪替及撤銷金鑰。
1. 兩類 Bearer 憑證
工作階段 Token 用於 domains、api-keys、webhooks 管理；API Key 用於 /v1/mail 與 SMTP 密碼。它不是帳戶密碼、會話 Token 或語言 Cookie。GET /v1/apikey/verify 只驗證 Key，不保證網域已驗證或額度充足。
2. 建立與保存
電子郵件驗證後使用 POST /api-keys，name 為非空字串，domain_id 為選填數字 ID。完整 key 僅在 201 建立回應出現。請存入伺服器秘密管理工具，不要記錄至日誌、截圖或前端程式碼。列表無法還原明文。
| 欄位 / 設定 | 型別 / 狀態 | 說明 |
|---|---|---|
| name | string | 建立必填非空 |
| domain_id | uint64 | 建立時選填網域 ID |
| key | string | 僅建立回應提供完整金鑰 |
| id / key_prefix / status | uint64 / string | 列表資料，prefix 不可驗證 |
| allowed_domain_id / last_used_at | uint64 / time | 可省略，非固定 null 欄位 |
curl -X POST "${SMTPDOG_API_ORIGIN}/api-keys" \
-H "Authorization: Bearer ${SMTPDOG_SESSION_TOKEN}" \
-H "Content-Type: application/json" \
--data '{"name":"Server integration","domain_id":123}'
curl -X GET "${SMTPDOG_API_ORIGIN}/api-keys" \
-H "Authorization: Bearer ${SMTPDOG_SESSION_TOKEN}"
curl -X DELETE "${SMTPDOG_API_ORIGIN}/api-keys/${SMTPDOG_KEY_ID}" \
-H "Authorization: Bearer ${SMTPDOG_SESSION_TOKEN}"3. 限制發送範圍
省略 domain_id 可用於帳戶已驗證網域；指定後僅允許該網域發送。建立時檢查歸屬，發送時仍檢查 verified。目前不支援 Key 有效期、角色或直接修改範圍。範圍限制不取代所有權驗證及反濫用檢查。
4. 輪替與撤銷
輪替順序為建立新 Key、更新服務設定、確認切換，再 DELETE /api-keys/{id} 撤銷舊 Key。回應為無本文 204，新請求無法使用舊 Key。目前沒有原地輪替或明文還原介面。誤用 Token 時請先確認所需驗證方式。