> For the complete documentation index, see [llms.txt](https://docs.blockchainsecurity.asia/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blockchainsecurity.asia/documentation/kai-shi-shi-yong/authentication.md).

# 認證與 API key

資料平面的所有請求都以 **API key** 認證。把 key 放進每個請求的 `X-API-Key` header 即可。

```bash
curl https://api.blockchainsecurity.asia/v1/webhooks \
  -H "X-API-Key: ak_live_YOUR_KEY"
```

{% hint style="info" %}
未取得 API key？歡迎先免費試用。部分端點支援免 API key 測試（同 IP 每日 10 次），方便評估回傳格式與串接流程。

若需完整 API 模組、高頻率查詢或商用正式接入，請聯絡 <support@chainsecurity.asia> 申請專屬 API key，以享有完整額度與用量計費。
{% endhint %}

## API key 長什麼樣子

* API key 長什麼樣子

  • API key 以 `ak_live_` 開頭，後接一段隨機字串，例如 `ak_live_3f9a2c7b8e1d4a60...`。

  • 管理後台與操作紀錄只會顯示 key 的前綴或部分遮蔽字元，用於辨識，不會顯示完整明碼。

  • 系統只保存 key 的雜湊值，不保存完整明碼。若遺失明碼，無法取回，只能撤銷後重新建立。

{% hint style="warning" %}
請將 API key 視同密碼保存。建議放在伺服器端環境變數或密鑰管理服務中，切勿寫入前端程式碼、公開 repository、版本控制或公開頁面。
{% endhint %}

## 認證結果

| 情況               | HTTP | code                  | 說明                          |
| ---------------- | ---: | --------------------- | --------------------------- |
| 未帶 key，但端點允許免費試用 |  200 | —                     | 依免費試用額度處理請求                 |
| 未帶 key，且端點需認證    |  401 | `unauthorized`        | 請求未提供有效 API key             |
| API key 無效或已撤銷   |  401 | `unauthorized`        | key 不存在、格式錯誤或已被撤銷           |
| API key 有效但權限不足  |  403 | `forbidden`           | key 無權呼叫該 endpoint 或 API 模組 |
| Credit 不足        |  402 | `insufficient_credit` | 剩餘額度不足，無法處理需計費請求            |
| 超過限流             |  429 | `rate_limited`        | 請求頻率超過目前方案或 endpoint 限制     |
| 認證通過             |  200 | —                     | 繼續處理請求                      |

{% hint style="info" %}
為避免洩漏「某把 key 是否存在」，key 無效、已撤銷或不存在時，系統皆回傳 401 unauthorized。
{% endhint %}

## 取得與管理金鑰

API key 由客戶方管理員在管理後台建立與管理，可執行以下操作：

• 建立 — 指定 key 名稱、方案、權限範圍與初始 Credit，建立後取得一次性明碼。

• 撤銷 — 立即停用該 key；撤銷後，使用該 key 的請求一律回傳 401 unauthorized。

• 調整 Credit — 依方案或授權額度，為指定 key 增加或減少可用 Credit。

## 輪替金鑰

系統不會自動輪替，建議流程如下：

{% stepper %}
{% step %}

#### 建立新 key

請管理員建立一把新 key，並妥善保存明碼。
{% endstep %}

{% step %}

#### 切換整合

將應用程式、後端服務或排程任務改用新 key，並重新部署。
{% endstep %}

{% step %}

### 觀察請求

確認切換完成後，撤銷舊 key，避免舊憑證繼續被使用。
{% endstep %}

{% step %}

### 撤銷舊 key

確認切換完成後，撤銷舊 key，避免舊憑證繼續被使用。
{% endstep %}
{% endstepper %}

## 追蹤每個請求

每次回應都會包含 request\_id，並可能同步出現在 X-Request-Id header。當你回報問題、查詢扣點、追蹤延遲或進行稽核時，請提供該 request\_id 以加速定位。

## 下一步

{% content-ref url="/pages/BBN0nBFpnfmeQEccdirr" %}
[錯誤處理](/documentation/he-xin-gai-nian/errors.md)
{% endcontent-ref %}

{% content-ref url="/pages/hauJglYxlKcGMt6ydPim" %}
[限流](/documentation/he-xin-gai-nian/rate-limiting.md)
{% endcontent-ref %}