> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/org/developer/api-keys.md).

# API Key 管理

管理組織內所有成員的 API Key：三步驟代發金鑰、限制可用模型與 RPM／TPM、停用與撤銷、查看最後使用時間；以及成員如何在帳號頁面自行建立金鑰。

API Key 讓外部系統、腳本、MCP 客戶端或 AI Gateway 以某位成員的身分呼叫 MaiAgent。每把金鑰綁定一位成員與一個組織，呼叫時的權限和該成員完全相同。

金鑰有兩個管理入口：

* **管理員**：在 <mark style="color:blue;">組織設定</mark> → <mark style="color:blue;">API Key 管理</mark> 查看組織內所有金鑰，為成員代發金鑰、限制可用模型與速率、停用或撤銷。
* **成員本人**：在帳號頁面的 <mark style="color:blue;">API 金鑰</mark> 自行建立與撤銷自己的金鑰，見[成員自行建立金鑰](#self-issued-keys)。

## 誰可以使用 <a href="#permissions" id="permissions"></a>

| 操作                                                                                       | 需要的條件                                                                                                                                                                      |
| ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 進入 <mark style="color:blue;">API Key 管理</mark>，查看、代發、停用、撤銷組織內所有金鑰                        | 角色權限 <mark style="color:blue;">組織權限</mark> 底下的 <mark style="color:blue;">API Key 管理權限</mark>（組織擁有者預設具備；設定方式見[編輯角色權限](/org/roles/role-permission.md#edit-role-permissions)） |
| 在帳號頁面建立、撤銷自己的金鑰                                                                          | 組織內的有效成員即可，不需要額外權限                                                                                                                                                         |
| 設定 <mark style="color:blue;">開通模型</mark>、查看本月花費、使用 <mark style="color:blue;">存取診斷</mark> | 組織已啟用 [AI Gateway](/build/ai-gateway.md)                                                                                                                                   |

## 基本概念 <a href="#key-concepts" id="key-concepts"></a>

* **完整金鑰只顯示一次**：建立當下會顯示完整金鑰，關閉視窗後就無法再看到，列表只顯示 <mark style="color:blue;">前綴</mark>。遺失時請撤銷舊金鑰、重新建立。
* **沒有數量上限**：每位成員可以同時持有多把有效金鑰。輪替時可以先建立新金鑰、更新整合設定，再撤銷舊金鑰，服務不會中斷。
* **呼叫方式**：平台 API 在 HTTP 標頭帶 `Authorization: Api-Key <金鑰>`；AI Gateway 的 OpenAI 相容端點則帶 `Authorization: Bearer <金鑰>`。完整範例請見技術手冊的 [API 快速上手](https://docs.maiagent.ai/tech/api-integration/quickstart) 與 [AI Gateway：OpenAI 相容 API 串接](https://docs.maiagent.ai/tech/ai-gateway/ai-gateway-openai-compatible)。

### 金鑰來源 <a href="#key-sources" id="key-sources"></a>

列表的 <mark style="color:blue;">來源</mark> 欄標示金鑰是誰簽發的，可用 <mark style="color:blue;">篩選來源</mark> 過濾：

| 來源                                      | 說明                                                                  |
| --------------------------------------- | ------------------------------------------------------------------- |
| <mark style="color:blue;">系統自動簽發</mark> | 成員加入組織時由系統自動建立，名稱是一串成員 ID                                           |
| <mark style="color:blue;">本人自建</mark>   | 成員在帳號頁面自行建立                                                         |
| <mark style="color:blue;">管理者代發</mark>  | 管理員在 <mark style="color:blue;">API Key 管理</mark> 為成員建立，標籤下方會顯示代發者姓名 |

### 金鑰狀態 <a href="#key-statuses" id="key-statuses"></a>

| 狀態                                   | 說明                         |
| ------------------------------------ | -------------------------- |
| <mark style="color:blue;">有效</mark>  | 可以正常呼叫                     |
| <mark style="color:blue;">已停用</mark> | 管理員暫停使用；金鑰與用量歷史都保留，可隨時重新啟用 |
| <mark style="color:blue;">已過期</mark> | 超過設定的到期時間                  |
| <mark style="color:blue;">已撤銷</mark> | 永久失效，無法復原                  |

停用、過期、撤銷的金鑰，以及已被移除成員的金鑰，呼叫時都會被當成無效金鑰拒絕。

## 進入方式 <a href="#how-to-enter" id="how-to-enter"></a>

從左側選單點選 <mark style="color:blue;">組織設定</mark> → <mark style="color:blue;">API Key 管理</mark>。列表依建立時間由新到舊排列，欄位包含 <mark style="color:blue;">擁有者</mark>、<mark style="color:blue;">名稱</mark>、<mark style="color:blue;">前綴</mark>、<mark style="color:blue;">來源</mark>、<mark style="color:blue;">狀態</mark>、<mark style="color:blue;">開通模型・速率</mark>、<mark style="color:blue;">最後使用</mark>、<mark style="color:blue;">到期時間</mark>、<mark style="color:blue;">建立時間</mark>。

* 上方搜尋框可用名稱、擁有者或 Email 搜尋，另可依來源與狀態篩選。
* <mark style="color:blue;">最後使用</mark> 是這把金鑰最近一次通過驗證的時間，同一把金鑰最多每分鐘更新一次；從未使用過的金鑰顯示 `-`。

## 建立 API Key <a href="#create-api-key" id="create-api-key"></a>

點選右上角 <mark style="color:blue;">建立 API Key</mark>，會開啟三步驟的 <mark style="color:blue;">新增 API Key</mark> 視窗。

{% stepper %}
{% step %}

### 選擇成員 <a href="#step-select-member" id="step-select-member"></a>

在 <mark style="color:blue;">選擇成員</mark> 搜尋並選擇金鑰要綁定的成員，<mark style="color:blue;">API Key 名稱</mark> 會自動帶入「成員名稱 的 API Key」，可自行修改（最多 50 個字）。選好成員後，畫面會顯示這位成員可觸及的模型數。

不需要限制時，可直接按 <mark style="color:blue;">略過設定，直接產生金鑰</mark>：金鑰會以預設值建立（可觸及模型全開、不限速、永不過期、立即啟用）。要設定限制則按 <mark style="color:blue;">下一步：開通與限制</mark>。
{% endstep %}

{% step %}

### 開通與限制 <a href="#step-provision-and-limits" id="step-provision-and-limits"></a>

以下設定都是選填，建立後也能在金鑰設定中調整：

| 欄位                                                | 作用                                                                                              |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| <mark style="color:blue;">開通模型</mark>             | 這把金鑰透過 AI Gateway 對話時可用的模型，預設全選。只能在「可觸及」範圍（組織可用且 Gateway 開放的模型）內縮小，不會超出組織的可用範圍；不影響 Embedding 端點 |
| <mark style="color:blue;">每分鐘請求數（RPM）</mark>      | 這把金鑰每分鐘可呼叫的平台 API 次數，不只 AI Gateway，一般平台 API 也計入。留空為不限                                           |
| <mark style="color:blue;">每分鐘 Token 數（TPM）</mark> | 這把金鑰經 AI Gateway 推論每分鐘可用的 Token 數。以每分鐘固定區間計算，單次請求可能讓當分鐘用量略超過上限，之後同一分鐘內的請求會被拒絕。留空為不限             |
| <mark style="color:blue;">到期時間</mark>             | 金鑰失效的時間，留空為永不過期                                                                                 |
| <mark style="color:blue;">建立後立即啟用</mark>          | 取消勾選時，金鑰建立後為「已停用」，需要時再啟用                                                                        |

組織未啟用 AI Gateway 時不會出現 <mark style="color:blue;">開通模型</mark>，其他欄位照常可設定。設定完成後按 <mark style="color:blue;">產生金鑰</mark>。
{% endstep %}

{% step %}

### 產生金鑰 <a href="#step-generate-key" id="step-generate-key"></a>

畫面會顯示完整金鑰，請按複製按鈕立即保存，再按 <mark style="color:blue;">確認關閉</mark>。關閉後就無法再次檢視完整金鑰。
{% endstep %}
{% endstepper %}

{% hint style="info" %}
在「產生金鑰」之前關掉視窗的話，金鑰可能已經建立，但完整金鑰無法再顯示。請在列表找到這把金鑰並撤銷，再重新建立。
{% endhint %}

## 管理既有金鑰 <a href="#manage-keys" id="manage-keys"></a>

每把金鑰右側有四個操作：

| 操作                                                                      | 說明                                                                             |
| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| <mark style="color:blue;">管理</mark>                                     | 開啟 <mark style="color:blue;">金鑰設定與用量</mark> 側欄（見下方）                            |
| <mark style="color:blue;">存取診斷</mark>                                   | 檢查這把金鑰為什麼呼叫不到模型，逐一列出未通過的關卡（說明見 [AI Gateway 總覽](/build/ai-gateway.md#overview)） |
| <mark style="color:blue;">停用</mark>／<mark style="color:blue;">啟用</mark> | 暫停或恢復這把金鑰，確認後立即生效                                                              |
| <mark style="color:blue;">撤銷</mark>                                     | 永久停止這把金鑰，無法復原                                                                  |

<mark style="color:blue;">金鑰設定與用量</mark> 側欄分為兩區：

* <mark style="color:blue;">金鑰設定</mark>：<mark style="color:blue;">啟用</mark> 開關、RPM、TPM、<mark style="color:blue;">到期時間</mark>（留空＝永不過期）與 <mark style="color:blue;">開通模型</mark>，修改後按 <mark style="color:blue;">儲存</mark>，立即生效。
* <mark style="color:blue;">本月用量</mark>：<mark style="color:blue;">本月花費（credits）</mark>、綁定成員的 <mark style="color:blue;">成員額度</mark>，以及 <mark style="color:blue;">呼叫的模型・花費</mark> 明細。花費與模型明細只在組織啟用 AI Gateway 時顯示。

**停用和撤銷怎麼選**：只是暫時不讓某個整合呼叫（例如排查異常流量），用停用，之後可以重新啟用；確定不再使用或金鑰外洩，用撤銷。

{% hint style="warning" %}
語音 Agent、會議記錄等功能，會在背景以成員的身分呼叫平台，前提是這位成員至少還有一把有效金鑰。撤銷或停用某位成員的所有金鑰（包括系統自動簽發的那把）後，這些功能可能無法以他的身分運作。輪替金鑰時，請先建立新金鑰，再撤銷舊金鑰。
{% endhint %}

## 成員自行建立金鑰 <a href="#self-issued-keys" id="self-issued-keys"></a>

成員不需要管理權限，就能為自己建立個人金鑰：

1. 點選右上角頭像 → <mark style="color:blue;">帳號</mark>。
2. 在左側目前組織名稱下方，點選 <mark style="color:blue;">API 金鑰</mark>。
3. 點選 <mark style="color:blue;">建立金鑰</mark>（還沒有任何金鑰時，按鈕是 <mark style="color:blue;">建立第一把金鑰</mark>），輸入 <mark style="color:blue;">名稱</mark>，可選填 <mark style="color:blue;">到期時間</mark>。
4. 複製畫面上的完整金鑰後，按 <mark style="color:blue;">確認關閉</mark>。

個人金鑰建立在**目前切換到的組織**，以您本人的身分與權限呼叫 API。如果您同時屬於多個組織，請先切換到要使用的組織再建立。

這個頁面只列出您自己建立的金鑰，可以撤銷狀態為有效的金鑰。管理者代發或系統自動簽發給您的金鑰，由組織管理員在 <mark style="color:blue;">API Key 管理</mark> 管理。具備 <mark style="color:blue;">API Key 管理權限</mark> 的成員，在此頁上方會看到 <mark style="color:blue;">組織金鑰管理</mark> 連結，可直接前往組織的金鑰列表。

個人金鑰不能自行設定開通模型或 RPM／TPM；需要限制時，請管理員在 <mark style="color:blue;">API Key 管理</mark> 調整。

## 常見問題 <a href="#faq" id="faq"></a>

#### Q：每位成員只能有一把有效金鑰嗎？ <a href="#faq-key-count" id="faq-key-count"></a>

不是。每位成員可以同時持有多把有效金鑰，沒有數量上限。

#### Q：API Key 管理頁打開是空白的？ <a href="#faq-blank-page" id="faq-blank-page"></a>

依序確認：

1. 您的角色具備 <mark style="color:blue;">API Key 管理權限</mark>（見[誰可以使用](#permissions)）；只是要替自己建立金鑰，請改走[成員自行建立金鑰](#self-issued-keys)。
2. 左上角切換到正確的組織，再重新整理頁面；瀏覽器若有舊版頁面快取，請強制重新整理（Windows `Ctrl+F5`、macOS `Cmd+Shift+R`）。
3. 公司網路或瀏覽器擴充功能擋下了對 API 網域的請求時，列表會載入失敗；換一個網路或無痕視窗試試。

仍然空白時，請把瀏覽器開發者工具 Console 的錯誤訊息與組織名稱提供給 MaiAgent 窗口。

#### Q：忘記複製完整金鑰怎麼辦？ <a href="#faq-lost-key" id="faq-lost-key"></a>

完整金鑰只在建立時顯示一次，系統無法再取回。請撤銷這把金鑰，再重新建立一把。

#### Q：為什麼個人頁面看不到管理員幫我建立的金鑰？ <a href="#faq-missing-in-profile" id="faq-missing-in-profile"></a>

個人頁面只顯示您自己建立的金鑰。管理者代發與系統自動簽發的金鑰，請洽有 <mark style="color:blue;">API Key 管理權限</mark> 的管理員查看或撤銷。

#### Q：<mark style="color:blue;">存取診斷</mark> 按鈕無法點選？ <a href="#faq-diagnose-disabled" id="faq-diagnose-disabled"></a>

存取診斷需要組織已啟用 AI Gateway。未啟用時按鈕會顯示「此組織未啟用 AI Gateway，無法診斷。」；已撤銷的金鑰也無法診斷。

## 延伸閱讀 <a href="#further-reading" id="further-reading"></a>

* [AI Gateway](/build/ai-gateway.md)：用 API Key 呼叫組織的模型與備援群組
* [MaiAgent MCP](https://docs.maiagent.ai/tech/mcp/maiagent-mcp)：用 API Key 讓 Claude 等 AI 工具操作平台
* [OAuth 應用程式](/org/developer/oauth-applications.md)：讓 MCP 客戶端改用 OAuth 授權，不必貼 API Key
* [成員 Credits 額度管理](/others/credits/member-credit-quota.md)：限制金鑰綁定成員可用的 Credits


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/org/developer/api-keys.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.