> ## 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 密鑰與護欄策略之間的 1:1 綁定關係。此處強制執行嚴格的“顯式選擇加入”約定:傳入 `policy_id: null` 會清除綁定,該密鑰隨即恢復為不受任何護欄約束的狀態——不會自動回退到組織或用戶的默認策略。

## 身份驗證

需要攜帶具有 `billing` API 密鑰權限範圍的 Bearer 令牌,並具備對該密鑰的訪問權限(調用方必須是該密鑰的所有者,或者——對於團隊密鑰——通過所屬組織獲得訪問權限)。

## GET

讀取當前綁定。

```bash theme={null}
curl https://www.hitheo.ai/api/v1/keys/{id}/guardrails \
  -H "Authorization: Bearer $THEO_API_KEY"
```

```typescript theme={null}
const { policy_id, has_policy } = await theo.keys.getGuardrailPolicy(keyId);
```

```json theme={null}
{ "key_id": "key_abc", "policy_id": "1f4f2c1a-...", "has_policy": true }
```

## PUT

設置或清除綁定。

<ParamField body="policy_id" type="string">
  策略 UUID。傳入 `null` 可完全清除該綁定。
</ParamField>

```bash theme={null}
# 綁定一個策略
curl -X PUT https://www.hitheo.ai/api/v1/keys/{id}/guardrails \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "policy_id": "1f4f2c1a-22ce-4b07-9c0b-9c4f4b9b1d2e" }'

# 清除綁定
curl -X PUT https://www.hitheo.ai/api/v1/keys/{id}/guardrails \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "policy_id": null }'
```

```typescript theme={null}
await theo.keys.setGuardrailPolicy(keyId, "1f4f2c1a-22ce-4b07-9c0b-9c4f4b9b1d2e");
await theo.keys.setGuardrailPolicy(keyId, null); // 清除
```

## 範圍規則

* 個人策略只能綁定到其作者本人擁有的密鑰。
* 團隊策略只能綁定到同一組織內的密鑰。
* 跨越該邊界會返回 `400 guardrail_policy_not_bindable`,並附帶廠商中立的錯誤消息。

## 錯誤

* `400 guardrail_policy_not_bindable` —— 該策略在此密鑰的範圍內不可見。
* `404 not_found` —— 密鑰或策略不存在(或對調用方不可見)。


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