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

# Key Model Allowlist

> Read or replace the per-key model allowlist that gates which Theo models a key may run.

Each API key can carry an explicit **model allowlist** of Theo-branded model ids (e.g. `theo-1-flash`, `theo-1-reason`). An **empty** allowlist means the key inherits all models (the default). A **non-empty** allowlist restricts the key: any request that resolves to a model outside the list is rejected with `403 model_not_allowed` — on both the native and OpenAI-compatible endpoints.

## Authentication

Requires an API key with `billing` scope. The caller must own the key (or be a team member allowed to manage keys).

## Path Parameters

<ParamField path="id" type="string" required>
  The API key UUID.
</ParamField>

## Get the allowlist

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

<ResponseField name="key_id" type="string">The API key UUID.</ResponseField>
<ResponseField name="inherits_all" type="boolean">`true` when the allowlist is empty (the key can run any model).</ResponseField>
<ResponseField name="model_ids" type="string[]">The allowed Theo model ids (empty when `inherits_all` is `true`).</ResponseField>

## Replace the allowlist

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

<ParamField body="model_ids" type="string[]" required>
  The full set of Theo model ids to allow (e.g. `["theo-1-reason", "theo-1-code"]`). Pass an empty array to reset the key to inherit all models. Unknown ids are rejected.
</ParamField>

## Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X PUT https://www.hitheo.ai/api/v1/keys/KEY_ID/models \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "model_ids": ["theo-1-reason", "theo-1-code"] }'
  ```

  ```ts SDK theme={null}
  // Model binding is set via the dashboard or this REST endpoint.
  // A request that resolves to a model outside the list throws TheoError(403, "model_not_allowed").
  ```
</CodeGroup>

```json theme={null}
{ "key_id": "KEY_ID", "inherits_all": false, "model_ids": ["theo-1-reason", "theo-1-code"] }
```