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