> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 創建 API 密鑰

> 創建一個用於程序化訪問的新 API 密鑰。

創建一個新的 API 密鑰。完整的密鑰值僅在創建時返回一次。

## 身份驗證

需要提供 Bearer 令牌。參見[身份驗證](/api-reference/authentication)。

## 請求體

<ParamField body="name" type="string">
  便於識別的標籤（例如 `"Production Server"`、`"Development"`）。
</ParamField>

<ParamField body="scopes" type="string[]">
  該密鑰的權限範圍（例如 `["completions", "skills"]`）。默認為全部範圍。
</ParamField>

<ParamField body="scope" type="'personal' | 'org'">
  聲明新密鑰是**個人**憑證（僅你可見）還是**團隊**憑證（與所屬組織的所有成員共享）。

  * `"personal"` — 創建個人密鑰。不得提供 `org_id`。即使你擁有管理團隊密鑰的權限，服務器也**永遠不會**自動關聯你當前所在的團隊。
  * `"org"` — 創建團隊共享密鑰。可提供 `org_id` 指定特定組織，或省略以回退到你當前的活動團隊上下文。

  若省略 `scope`，服務器會自動推斷該值：若提供了 `org_id` 則為 `"org"`，否則為 `"personal"`。
</ParamField>

<ParamField body="org_id" type="string">
  用於限定密鑰所屬範圍的組織 UUID。當 `scope` 為 `"org"` 且調用方沒有活動團隊上下文時為必填項；當 `scope` 為 `"personal"` 時禁止提供。調用方必須擁有目標組織的 `manageApiKeys` 權限。
</ParamField>

## 請求示例

個人密鑰（顯式指定）：

```bash theme={null}
curl -X POST https://www.hitheo.ai/api/v1/keys \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Server", "scope": "personal"}'
```

團隊共享密鑰（指定特定組織）：

```bash theme={null}
curl -X POST https://www.hitheo.ai/api/v1/keys \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CI pipeline", "scope": "org", "org_id": "org_123"}'
```

## 響應

返回創建的密鑰對象。完整的 API 密鑰字符串**僅在此響應中包含一次**——請妥善保存。

<Warning>
  完整的密鑰值僅在創建時顯示一次，之後將無法再次獲取。
</Warning>

## 端點

`POST /api/v1/keys`

需要通過 Bearer 令牌進行身份驗證。參見[身份驗證](/api-reference/authentication)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.