# API Key Fine-Grained Access Control

## Overview

On 2026-03-20, API Key fine-grained permission control was introduced, supporting access control based on quota, model, and IP whitelist.

> Note: This feature is experimental. To use it, please contact the product team to enable permissions on the new platform.

## Feature Description

### Quota Control

API Keys support setting a `daily` or `monthly` spending limit. Once the limit is exceeded, API calls will be blocked. The quota can be configured when `creating/updating` an API Key.  
> Note: Quota is optional. If not configured, there is no spending limit by default.  
>       The quota limit is based on the actual incurred cost, not estimated cost. (Billing is postpaid and settled hourly, so there may be a delay in quota enforcement. It is recommended to leave some buffer when setting limits.)  
>       There may be a short delay after billing settlement due to the deduction process.

#### Steps

1. Log in to the console and go to the API Key management page  
2. Click "Create API Key" or "Edit API Key"  
3. In the "Quota Control" section, set the "daily" or "monthly" limit  
4. Click "Create" or "Save"  

![Quota Control](https://cdn.udelivrs.com/2026/04/ae390bdf8aa65e195fb6018d22b3ee26_1776318089777.png)
![Quota Control](https://cdn.udelivrs.com/2026/04/a6da0da29d2d96fdb625d0298fa48f00_1776318089773.png)

#### Example

```bash
curl https://api-us-ca.umodelverse.ai/v1/responses\
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.4",
    "input": "Hello! Who are you?"
  }'

{"error":{"message":"Access forbidden: api key quota exceeded, key_id=uminferapikey-1j3gwjgyhkwc, daily_limit_amount=100 , monthly_limit_amount=1000","type":"permission_error","param":"c2ad1049-66a6-4640-b2b5-1711dc401092","code":"forbidden"}}
```

### Model Control

API Keys support configuring an allowed model list. Only models in the list can be used. The model list can be set when `creating/updating` an API Key.  
> Note: Model control is optional. If not configured, all models are allowed by default.  
>       The console supports selecting models by provider, etc., but newly added models will not be automatically included. To use new models, they must be added manually.

> Example: If all OpenAI models are selected when creating an API Key, any new models released afterward will not be accessible with this API Key. To use new models, update the allowed model list.

![Model Control](https://cdn.udelivrs.com/2026/04/1b35ba0c7ebe1dbe96b9d71fce0b8b20_1776318089784.png)

#### Example

```bash
 curl https://api-us-ca.umodelverse.ai/v1/responses\
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.4",
    "input": "Hello! Who are you?"
  }'

{"error":{"message":"No permission to use the model: apikey [uminferapikey-1j3gwjgyhkwc] not support model [gpt-5.4]","type":"invalid_request_error","param":"6d7248f8-ebaa-437e-bfc2-d79e7c54004c","code":"model_error"}}
```

### IP Whitelist Control

API Keys support configuring an IP whitelist. If not set, the API Key can be used from any IP. Once configured, only IPs in the whitelist are allowed to access the API. The whitelist can be set when `creating/updating` an API Key.

> Note: IP whitelist is optional. If not configured, the API Key can be used from any IP by default. Currently, only IPv4 is supported.  
>       Supports single IP and CIDR/range formats, such as `192.168.1.1`, `192.168.1.0/24`, `192.168.1.10-192.168.1.20`.

![IP Whitelist Control](https://cdn.udelivrs.com/2026/04/2e221807e6b2edafb589500fc6e8c12b_1776318089780.png)

#### Example

```bash
 curl https://api-us-ca.umodelverse.ai/v1/responses\
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "gpt-5.4",
    "input": "Hello! Who are you?"
  }'

{"error":{"message":"Access forbidden: api key ip not in whitelist, key_id=uminferapikey-1j3gwjgyhkwc, ip=127.0.0.1","type":"permission_error","param":"c2ad1049-66a6-4640-b2b5-1711dc401092","code":"forbidden"}}
```