> ## Documentation Index
> Fetch the complete documentation index at: https://ppio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 查询 API Key 模型访问策略

查询单个 API Key 当前的模型访问策略。如果该 Key 从未单独配置过，返回默认策略（`mode=all_enabled`）。

<Info>
  `allowedModels` / `excludedModels` 实际可能返回 `null` 或空数组，调用方建议统一按空数组处理。
</Info>

## 权限

| 角色            | 是否可查询                                                            |
| :------------ | :--------------------------------------------------------------- |
| Owner / Admin | 可查询团队内任意 API Key 的完整策略。                                          |
| Developer     | 只能查询自己拥有的 API Key，且响应中不返回 `allowedModels` / `excludedModels` 明细。 |

被查询的 API Key 必须属于当前调用方所在的团队。

## 请求头

<ParamField header="Authorization" type="string" required={true}>
  Bearer 身份验证格式，例如：Bearer \{\{API 密钥}}。
</ParamField>

## 路径参数

<ParamField path="stringId" type="string" required={true}>
  目标 API Key 的 stringId。
</ParamField>

## 响应参数

<ResponseField name="stringId" type="string" required={true}>
  API Key 的 stringId。
</ResponseField>

<ResponseField name="policy" type="object" required={true}>
  模型访问策略对象。

  <Expandable title="properties" defaultOpen={true}>
    <ResponseField name="schemaVersion" type="int32" required={true}>
      策略结构版本号，当前为 `1`。
    </ResponseField>

    <ResponseField name="productScope" type="string" required={true}>
      策略适用的产品范围。当前仅支持 `model_api`。
    </ResponseField>

    <ResponseField name="mode" type="string" required={true}>
      访问模式。取值：`all_enabled`（可访问全部已开通模型）、`selected`（仅可访问指定模型）。
    </ResponseField>

    <ResponseField name="allowedModels" type="object[]" required={false}>
      可访问的模型列表。仅在 `mode=selected` 时有意义；`mode=all_enabled` 时为空。Developer 查询时不返回该明细。

      <Expandable title="properties">
        <ResponseField name="type" type="string" required={true}>
          模型类型。取值：`llm`、`multimodal`。
        </ResponseField>

        <ResponseField name="id" type="string" required={true}>
          模型标识，例如 `deepseek/deepseek-v3`。
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="excludedModels" type="object[]" required={false}>
      已排除的模型列表。仅在 `mode=all_enabled` 时有意义；`mode=selected` 时为空。字段结构同 `allowedModels`。Developer 查询时不返回该明细。
    </ResponseField>

    <ResponseField name="source" type="object" required={false}>
      策略来源，由服务端返回，写入时忽略。

      <Expandable title="properties">
        <ResponseField name="type" type="string" required={true}>
          来源类型。取值：`default`（从未单独配置，返回默认策略）、`private_policy`（该 Key 的内嵌策略）。
        </ResponseField>

        <ResponseField name="policyId" type="string" required={false}>
          关联的策略 ID，仅在适用时返回。
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="policyStatus" type="string" required={true}>
  策略状态。`active` 表示策略有效；`no_available_models` 表示当前无可访问模型（例如已选模型全部下线）。
</ResponseField>

<ResponseField name="allowedModelCount" type="int32" required={true}>
  可访问模型数量。
</ResponseField>

<ResponseField name="excludedModelCount" type="int32" required={true}>
  已排除模型数量。
</ResponseField>

<ResponseField name="updatedAt" type="int64" required={true}>
  最近一次更新时间，Unix 时间戳（秒）。默认策略下为 `0`。
</ResponseField>

<ResponseField name="updatedBy" type="string" required={true}>
  最近一次更新操作者的用户标识。默认策略下为空字符串。
</ResponseField>

<RequestExample>
  ```bash theme={null}
  curl --request GET \
    --url https://api.ppio.com/openapi/v2/user/key/<stringId>/model-access-policy \
    --header 'Authorization: Bearer <API_KEY>'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 (仅限指定模型) theme={null}
  {
    "stringId": "key_xxx",
    "policy": {
      "schemaVersion": 1,
      "productScope": "model_api",
      "mode": "selected",
      "allowedModels": [
        {
          "type": "llm",
          "id": "deepseek/deepseek-v3"
        }
      ],
      "excludedModels": [],
      "source": {
        "type": "private_policy"
      }
    },
    "policyStatus": "active",
    "allowedModelCount": 1,
    "excludedModelCount": 0,
    "updatedAt": 1783764000,
    "updatedBy": "user_uuid_xxx"
  }
  ```

  ```json 200 (默认策略) theme={null}
  {
    "stringId": "key_xxx",
    "policy": {
      "schemaVersion": 1,
      "productScope": "model_api",
      "mode": "all_enabled",
      "allowedModels": [],
      "excludedModels": [],
      "source": {
        "type": "default"
      }
    },
    "policyStatus": "active",
    "allowedModelCount": 0,
    "excludedModelCount": 0,
    "updatedAt": 0,
    "updatedBy": ""
  }
  ```
</ResponseExample>