# 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

### Label Management

API Keys can be associated with one or more labels to classify and filter keys by business line, environment, application, or other dimensions. Labels are bound and unbound through dedicated label management APIs, without modifying the API Key creation or update parameters.

> Note: Label management APIs are management APIs. Refer to the API management platform for the published operation names, request URLs, and common parameters.

For a complete list of label operations and their detailed definitions, visit the [UCloud API Management Platform](https://console.ucloud.cn/uapi/ucloudapi/Cloud%20Resources).

#### Label Data Structure

Each label consists of a label key (`Key`) and a label value (`Value`):

```json
{
  "Key": "environment",
  "Value": "production"
}
```

An API Key can be associated with multiple labels. For example:

```json
[
  {
    "Key": "environment",
    "Value": "production"
  },
  {
    "Key": "application",
    "Value": "customer-service"
  }
]
```

#### Bind Labels

Call the `BindLabels` API with the project ID (`ProjectId`), the API Key resource ID list (`ResourceIds`), and the labels to bind (`Labels`). After a successful call, the labels are saved to the corresponding API Keys and can be used to filter the API Key list.

#### Unbind Labels

Call the label unbinding API with the API Key resource IDs and the labels to remove. After unbinding, the labels are no longer associated with the API Keys. When all labels are removed, the API Keys return to an untagged state. Refer to the API management platform for the specific operation name, request URL, and parameters.

#### Usage Recommendations

- `ResourceIds` must contain API Key resource IDs (for example, `uminferapikey-xxxxx`), not API Key secret values.
- Use stable, maintainable names for label keys and values, such as `environment`, `application`, and `owner`.
- Binding or unbinding labels does not change an API Key's model permissions, quota, validity period, or IP whitelist settings.
- When an API Key is deleted, its associated labels become invalid as well.

### 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"}}
```