> 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.atlantis.example/v1/webhooks \
  -H "X-API-Key: ak_live_YOUR_KEY"
```

## API key 長什麼樣子

* 明碼 key 以 `ak_live_` 開頭，後接一段隨機字串，例如 `ak_live_3f9a2c7b8e1d4a60...`。
* 後台與紀錄中只會顯示 key 的**前綴**（前 16 個字元，如 `ak_live_3f9a2c7b`）供辨識；完整明碼僅在建立當下回傳一次。
* 系統只保存 key 的雜湊值，**不保存明碼**——遺失無法找回，只能撤銷重建。

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

## 認證結果

| 情況               | HTTP | 錯誤碼            |
| ---------------- | ---- | -------------- |
| 未帶或 key 無效／已撤銷   | 401  | `unauthorized` |
| key 有效但已停用（例如欠費） | 403  | `forbidden`    |
| 認證通過             | —    | 繼續處理請求         |

{% hint style="info" %}
為避免洩漏「某把 key 是否存在」，查無此 key 與已撤銷都回傳同樣的 `401 unauthorized`。
{% endhint %}

## 取得與管理金鑰

API key 由你方管理員建立與管理，可進行：

* **建立** — 指定名稱、方案與初始 credit，取得一次性明碼。
* **撤銷** — 立即失效，之後使用該 key 的請求一律 401。
* **調整 credit** — 為該 key 增減點數。

## 輪替金鑰

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

{% stepper %}
{% step %}

#### 建立新 key

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

{% step %}

#### 切換整合

把你的應用程式改用新 key 並部署。
{% endstep %}

{% step %}

#### 撤銷舊 key

確認新 key 運作正常後，請管理員撤銷舊 key。
{% endstep %}
{% endstepper %}

## 追蹤每個請求

每個回應都會帶 `X-Request-Id`（你也可以自帶 `X-Request-Id` header，系統會沿用）。回報問題時附上這個值，可大幅加快定位。

## 下一步

{% 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 %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.blockchainsecurity.asia/documentation/kai-shi-shi-yong/authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.