# 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. 點擊右上角的「使用者名稱」下拉選單
2. 點擊「帳號」進入個人資料頁面

<div><figure><img src="/files/Pfj4XpBQ3z0txIcQYJTn" alt=""><figcaption></figcaption></figure> <figure><img src="/files/0GarWa1NB1GKTTFQgS3X" alt=""><figcaption></figcaption></figure></div>

2. 將頁面切換至 API 金鑰頁面。

<figure><img src="/files/hsaLEtrBuSUHvppUetJO" alt=""><figcaption></figcaption></figure>

3. 即可複製查看「API 金鑰」。

<figure><img src="/files/qlLsYiPFoEeM11urfi5Z" alt=""><figcaption></figcaption></figure>

{% hint style="success" %}

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

## 錯誤處理

當認證錯誤時，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: 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.maiagent.ai/api/preparation/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.