> 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/api/preparation/authentication.md).

# API 認證

本篇將介紹在使用 MaiAgent API 時的身分驗證方法及取得方式

MaiAgent 使用 API 金鑰進行身分驗證。

## 身分認證方式

所有 API 請求必須在 HTTP Header 中包含 API Key，格式如下：

```javascript
const headers = {
  "Authorization": "Api-Key YOUR_API_KEY_HERE",
  "Content-Type": "application/json"
}
```

## 如何獲取 API 金鑰？

請登入 MaiAgent 系統後台，然後按照以下步驟操作：

1. 點擊右上角的 <mark style="color:blue;">使用者名稱</mark>下拉選單。
2. 點擊 <mark style="color:blue;">帳號</mark>，進入個人資料頁面。
3. 切換至 <mark style="color:blue;">API 金鑰</mark>頁面。
4. 點擊 <mark style="color:blue;">建立金鑰</mark>，輸入名稱並視需要設定到期日。未設定到期日的金鑰不會自動到期。
5. 建立後立即複製並妥善保存完整金鑰。

{% hint style="success" %}

* **安全提醒**：請妥善保管您的 API 金鑰，不要在公開場所分享
* **金鑰格式說明**：API 金鑰英數字組合
  {% endhint %}

{% hint style="warning" %}
完整金鑰只會在建立成功時顯示一次。之後的列表僅顯示部分字元，無法再次查看或還原完整金鑰；若未保存，請建立新金鑰、更新使用該金鑰的服務，再撤銷舊金鑰。
{% endhint %}

## 找不到舊的系統簽發金鑰 <a href="#system-issued-api-key" id="system-issued-api-key"></a>

個人帳號的 <mark style="color:blue;">API 金鑰</mark>頁面只列出您自行建立的金鑰。首次加入組織（包含透過 AD 首次登入）時，系統可能會自動簽發一把無到期日的金鑰，但不會提供其完整值，因此無法取得該金鑰來呼叫 API。若要呼叫 API，請在個人頁面自行建立新金鑰，並在建立成功時立即保存完整值。

系統自動簽發或由管理者代為簽發的金鑰，只有具有組織金鑰管理權限的成員可從 <mark style="color:blue;">組織金鑰管理</mark>查看其擁有者、前綴、簽發來源、狀態與到期日，但該頁不會顯示完整值。若您沒有此權限，可請組織擁有者或具有組織金鑰管理權限的成員協助確認或撤銷舊金鑰。

## 錯誤處理

當認證錯誤時，API 會回傳 401 Unauthorized 的 HTTP 錯誤代碼：

* **API Key 無效或缺失**

```json
{
  "detail": "Authentication credentials were not provided."
}
```

*修復建議：檢查請求標頭是否包含正確的 Authorization 欄位。格式應為： `Authorization: Api-Key YOUR_API_KEY`*

* **API Key 格式錯誤**

```json
{
  "detail": "Invalid API key format."
}
```

*修復建議：確認 API Key 格式正確。檢查是否使用了正確的前綴 `Api-Key` 而非 `Bearer`，並確認 API Key 本身沒有多餘的空格或字元。*


---

# 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, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/api/preparation/authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.