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

# Set API Key Model Access Policy

Set or update the model access policy of a single API key. The request body is the `policy` object itself.

## Permissions

Only the team Owner / Admin can call this endpoint. Developer, Basic, and Billing members cannot set the policy. The target API key must belong to the caller's team.

## Request Headers

<ParamField header="Content-Type" type="string" required={true}>
  Enum: `application/json`
</ParamField>

<ParamField header="Authorization" type="string" required={true}>
  Bearer authentication format, for example: Bearer \{\{API Key}}.
</ParamField>

## Path Parameters

<ParamField path="stringId" type="string" required={true}>
  The stringId of the target API key.
</ParamField>

## Request Body

<ParamField body="schemaVersion" type="int32" required={false}>
  Policy schema version. Currently `1`.
</ParamField>

<ParamField body="productScope" type="string" required={false}>
  Product scope the policy applies to. Only `model_api` is supported when provided.
</ParamField>

<ParamField body="mode" type="string" required={true}>
  Access mode. Possible values: `all_enabled` (can access all enabled models), `selected` (can access only the specified models).
</ParamField>

<ParamField body="allowedModels" type="object[]" required={false}>
  Accessible models. Required when `mode=selected` and must contain at least one model; ignored when `mode=all_enabled`.

  <Expandable title="properties">
    <ParamField body="type" type="string" required={true}>
      Model type. Possible values: `llm`, `multimodal`.
    </ParamField>

    <ParamField body="id" type="string" required={true}>
      Model identifier, for example `deepseek/deepseek-v3`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="excludedModels" type="object[]" required={false}>
  Excluded models. Applies when `mode=all_enabled`; ignored when `mode=selected`. Same structure as `allowedModels`.
</ParamField>

<Note>
  Write constraints:

  * `mode` must be `all_enabled` or `selected`.
  * When `mode=selected`, `allowedModels` must contain at least one model.
  * Every model written must be within the team's enabled model range and currently available; requests containing offline, unavailable, or not-enabled models are rejected.
  * Model arrays that do not apply to the current mode are normalized to empty, and duplicate models are deduplicated. The response reflects the server-normalized object.
  * `source` is managed by the server and ignored on write.
</Note>

## Response

The response has the same structure as [Get API Key Model Access Policy](/docs/ja/api-reference/key-get-model-access-policy) and reflects the latest, normalized policy object.

<RequestExample>
  ```bash Selected models theme={"system"}
  curl --request PUT \
    --url https://api.novita.ai/openapi/v2/user/key/<stringId>/model-access-policy \
    --header 'Authorization: Bearer <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
      "schemaVersion": 1,
      "productScope": "model_api",
      "mode": "selected",
      "allowedModels": [
        { "type": "llm", "id": "deepseek/deepseek-v3" }
      ]
    }'
  ```

  ```bash All enabled models theme={"system"}
  curl --request PUT \
    --url https://api.novita.ai/openapi/v2/user/key/<stringId>/model-access-policy \
    --header 'Authorization: Bearer <API_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
      "schemaVersion": 1,
      "productScope": "model_api",
      "mode": "all_enabled"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"system"}
  {
    "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"
  }
  ```
</ResponseExample>