> ## 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 密钥都可以携带一份显式的技能白名单。**空**白名单表示该密钥继承你安装的全部技能（默认行为）。**非空**白名单会将该密钥限制为白名单内的技能，且在请求时与你已安装的技能集合取交集。

## 身份验证

需要具备 `billing` 权限范围的 API 密钥。调用者必须是该密钥的所有者，或具有管理 API 密钥权限的团队成员。

## 路径参数

<ParamField path="id" type="string" required>
  API 密钥的 UUID。
</ParamField>

## 获取绑定关系

`GET /api/v1/keys/{id}/skills`

<ResponseField name="key_id" type="string">
  API 密钥的 UUID。
</ResponseField>

<ResponseField name="inherits_all" type="boolean">
  当白名单为空时为 `true`（表示该密钥继承全部已安装的技能）。
</ResponseField>

<ResponseField name="skill_ids" type="string[]">
  已绑定的技能 ID（当 `inherits_all` 为 `true` 时为空）。
</ResponseField>

<ResponseField name="skills" type="array">
  每个已绑定技能的展示元数据：`id`、`slug`、`name`、`category`、`is_public`。
</ResponseField>

## 替换绑定关系

`PUT /api/v1/keys/{id}/skills`

<ParamField body="skill_ids" type="string[]" required>
  要绑定的完整技能 ID 集合。传入空数组可将该密钥重置为继承全部已安装的技能。
</ParamField>

团队作用域的密钥只能绑定公开的、由调用者本人创建的、或归属于该密钥所在团队的技能。若任一 ID 对该密钥不可见，请求将返回 `400 skill_visibility_denied`，且不会做任何变更。

## 示例

<CodeGroup>
  ```bash curl theme={null}
  curl -X PUT https://www.hitheo.ai/api/v1/keys/KEY_ID/skills \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "skill_ids": ["11111111-2222-3333-4444-555555555555"] }'
  ```

  ```json Response theme={null}
  {
    "key_id": "KEY_ID",
    "inherits_all": false,
    "skill_ids": ["11111111-2222-3333-4444-555555555555"]
  }
  ```
</CodeGroup>


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