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