> ## 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.