> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Cập nhật một API key
> Sử dụng CometAPI PUT /api/token/ để cập nhật một API key theo ID với các trường có thể chỉnh sửa trong phần thân JSON.
Sử dụng endpoint này để cập nhật tên, trạng thái, quota, thời hạn hết hạn, giới hạn model, danh sách IP được phép và cài đặt nhóm của một API key.
Tạo một personal access token tại [Console → Personal Settings](https://www.cometapi.com/console/personal), sau đó gửi nó dưới dạng giá trị thô của header `Authorization`. Không thêm tiền tố `Bearer`.
Endpoint này sử dụng `PUT /api/token/`, và `id` phải nằm trong phần thân JSON. Hãy gửi các trường có thể chỉnh sửa mà bạn muốn giữ nguyên; các trường số, boolean hoặc chuỗi bị bỏ qua có thể bị đặt lại khi cập nhật.
## Phần thân yêu cầu
| Field | Type | Description |
| ---------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | integer | Bắt buộc. ID API key được trả về bởi [List API keys](./list-api-keys). |
| `name` | string | Tên hiển thị dễ đọc dành cho người dùng của key. Phải có tối đa 50 ký tự. |
| `status` | integer | Trạng thái hoạt động. `1` bật key cho các yêu cầu model. `2` tắt key. `3` đánh dấu key đã hết hạn. `4` đánh dấu key đã hết quota. Các key bị tắt, hết hạn hoặc hết quota sẽ bị từ chối bởi các endpoint model. |
| `expired_time` | integer | Unix timestamp tính bằng giây khi key hết hạn. Dùng `-1` để không hết hạn. Một timestamp trong quá khứ sẽ chặn các yêu cầu model. |
| `remain_quota` | integer | Quota còn lại theo đơn vị quota nội bộ của CometAPI. Nếu giá trị này đạt `0` và `unlimited_quota` là `false`, các yêu cầu model với key này sẽ bị từ chối vì đã hết quota. |
| `unlimited_quota` | boolean | Key có bỏ qua việc kiểm tra quota còn lại hay không. Chỉ đặt `true` khi key cần tiếp tục hoạt động ngay cả khi `remain_quota` là `0`. |
| `model_limits_enabled` | boolean | Có giới hạn key này chỉ dùng cho các model cụ thể hay không. Khi là `false`, `model_limits` sẽ bị bỏ qua. |
| `model_limits` | string | Danh sách model ID được phép dùng với key này, phân tách bằng dấu phẩy khi `model_limits_enabled` là `true`. Dùng các model ID được trả về từ `/v1/models`; dùng chuỗi rỗng nếu không giới hạn model. |
| `allow_ips` | string or null | Danh sách IP được phép tùy chọn. Cung cấp một chuỗi JSON với các mục được phân tách bằng ký tự xuống dòng (`\n`). Mỗi mục có thể là một địa chỉ IPv4 đơn lẻ, một địa chỉ IPv6 đơn lẻ, một IPv4 CIDR hoặc một IPv6 CIDR. Dùng `null` hoặc `""` để tắt giới hạn IP. |
| `group` | string | Giới hạn nhóm tài khoản tùy chọn. Dùng chuỗi rỗng nếu không chỉ định nhóm cụ thể. Các giá trị không rỗng phải khả dụng với tài khoản, nếu không API sẽ trả về `success: false`. |
| `cross_group_retry` | boolean | Có bật cross-group retry để định tuyến nhóm tự động hay không. Chỉ có ý nghĩa khi key sử dụng một nhóm được định tuyến tự động. |
## Định dạng allowlist
Để cho phép nhiều IP hoặc dải CIDR, hãy gửi chúng dưới dạng một chuỗi JSON với `\n` giữa các mục:
```json theme={null}
{
"allow_ips": "198.51.100.10\n203.0.113.0/24\n2001:db8::/32"
}
```
Ví dụ này cho phép một địa chỉ IPv4, một dải IPv4 CIDR và một dải IPv6 CIDR.
## OpenAPI
````yaml api/openapi/api-keys/update-api-key.openapi.json PUT /api/token/
openapi: 3.1.0
info:
title: Update API Key
version: 1.0.0
servers:
- url: https://api.cometapi.com
security:
- accessTokenAuth: []
paths:
/api/token/:
put:
summary: Update an API key
description: >-
Update an API key by sending its ID and editable fields in the JSON
body. This endpoint behaves like a full update: send fields you want to
preserve because omitted numeric, boolean, or string fields can be
reset.
operationId: updateApiKey
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateApiKeyRequest'
examples:
default:
summary: Update an API key
value:
id: 1234
name: production-renamed
status: 1
expired_time: -1
remain_quota: 100000
unlimited_quota: false
model_limits_enabled: false
model_limits: ''
allow_ips: null
group: ''
cross_group_retry: false
with_ip_allowlist:
summary: Configure an IP allowlist
description: >-
Use one JSON string and separate multiple IP or CIDR entries
with `\n`.
value:
id: 1234
name: production-renamed
status: 1
expired_time: -1
remain_quota: 100000
unlimited_quota: false
model_limits_enabled: false
model_limits: ''
allow_ips: |-
198.51.100.10
203.0.113.0/24
2001:db8::/32
group: ''
cross_group_retry: false
responses:
'200':
description: Updated API key record.
content:
application/json:
schema:
type: object
required:
- success
- message
- data
properties:
success:
type: boolean
message:
type: string
data:
$ref: '#/components/schemas/ApiKey'
examples:
success:
summary: Updated
value:
success: true
message: ''
data:
id: 1234
user_id: 5678
key: $COMETAPI_KEY
status: 1
name: production-renamed
created_time: 1766102400
accessed_time: 1766102400
expired_time: -1
remain_quota: 100000
unlimited_quota: false
model_limits_enabled: false
model_limits: ''
allow_ips: null
used_quota: 0
group: ''
cross_group_retry: false
name_too_long:
summary: Name too long
value:
success: false
message: token name is too long
x-codeSamples:
- lang: curl
label: cURL
source: |-
curl -X PUT https://api.cometapi.com/api/token/ \
-H "Authorization: your-access-token" \
-H "Content-Type: application/json" \
-d '{
"id": 1234,
"name": "production-renamed",
"status": 1,
"expired_time": -1,
"remain_quota": 100000,
"unlimited_quota": false,
"model_limits_enabled": false,
"model_limits": "",
"allow_ips": null,
"group": "",
"cross_group_retry": false
}'
- lang: curl
label: cURL with IP allowlist
source: |-
curl -X PUT https://api.cometapi.com/api/token/ \
-H "Authorization: your-access-token" \
-H "Content-Type: application/json" \
-d '{
"id": 1234,
"name": "production-renamed",
"status": 1,
"expired_time": -1,
"remain_quota": 100000,
"unlimited_quota": false,
"model_limits_enabled": false,
"model_limits": "",
"allow_ips": "198.51.100.10\n203.0.113.0/24\n2001:db8::/32",
"group": "",
"cross_group_retry": false
}'
components:
schemas:
UpdateApiKeyRequest:
type: object
required:
- id
properties:
id:
type: integer
description: >-
Numeric API key ID returned by the list endpoint. For updates, send
this value in the JSON body, not in the URL.
example: 1234
name:
type: string
maxLength: 50
description: >-
User-readable display name for the API key. The backend accepts up
to 50 Unicode characters; longer names return `success: false` with
`token name is too long`.
example: production
status:
type: integer
description: >-
Operational status for the key. `1` enables the key for model
requests, `2` disables it, `3` marks it expired, and `4` marks it
quota exhausted. Disabled, expired, or exhausted keys are rejected
by model endpoints.
enum:
- 1
- 2
- 3
- 4
example: 1
expired_time:
type: integer
description: >-
Unix timestamp in seconds when the key expires. Use `-1` for no
expiration. A past timestamp blocks model requests with this key.
example: -1
remain_quota:
type: integer
description: >-
Remaining quota to assign to the key in CometAPI internal quota
units. If this reaches `0` while `unlimited_quota` is `false`, model
requests with this key are rejected as quota exhausted.
example: 100000
unlimited_quota:
type: boolean
description: >-
Whether the key bypasses remaining-quota checks. Set `true` only
when the key should keep working even if `remain_quota` is `0`.
example: false
model_limits_enabled:
type: boolean
description: >-
Whether to restrict this key to specific models. When `true`, only
model IDs listed in `model_limits` are allowed. When `false`,
`model_limits` is ignored.
example: false
model_limits:
type: string
description: >-
Comma-separated model IDs allowed by this key when
`model_limits_enabled` is `true`. Use model IDs returned by
`/v1/models`, for example `,`. Use an empty
string for no model restriction.
example: ''
allow_ips:
type:
- string
- 'null'
description: >-
Optional IP allowlist. Provide one JSON string with entries
separated by newline characters (`\n`). Each entry can be a single
IPv4 address, single IPv6 address, IPv4 CIDR, or IPv6 CIDR. Example
for three allowlist entries:
`198.51.100.10\n203.0.113.0/24\n2001:db8::/32`. CometAPI compares
the model request client IP to this list. Use `null` or `""` to
disable IP restrictions.
example: |-
198.51.100.10
203.0.113.0/24
2001:db8::/32
group:
type: string
description: >-
Optional account group restriction. Use an empty string for no
explicit group restriction. Non-empty values must be available to
the account, or the API returns `success: false` with a `no access
to group` message.
example: ''
cross_group_retry:
type: boolean
description: >-
Whether cross-group retry is enabled for automatic group routing.
This is only meaningful when the key uses an auto-routed group such
as `auto`.
example: false
additionalProperties: false
ApiKey:
type: object
properties:
id:
type: integer
description: >-
Numeric API key ID. Use this value with the get, update, and delete
endpoints.
example: 1234
user_id:
type: integer
description: Account user ID that owns the key.
example: 5678
key:
type: string
description: >-
API key value returned by the management API. Treat it as a secret
and use it as `Authorization: Bearer $COMETAPI_KEY` for model
requests.
example: $COMETAPI_KEY
status:
type: integer
description: >-
Operational status for the key. `1` means enabled, `2` disabled, `3`
expired, and `4` exhausted. Only enabled keys are accepted by model
endpoints.
enum:
- 1
- 2
- 3
- 4
example: 1
name:
type: string
description: User-readable display name for the API key.
example: production
maxLength: 50
created_time:
type: integer
description: Unix timestamp in seconds when the key was created.
example: 1766102400
accessed_time:
type: integer
description: >-
Unix timestamp in seconds when the key was last used. Newly created
keys may show the creation time until first use.
example: 1766102400
expired_time:
type: integer
description: >-
Unix timestamp in seconds when the key expires. `-1` means no
expiration.
example: -1
remain_quota:
type: integer
description: >-
Remaining quota for this key in CometAPI internal quota units. When
this reaches `0` and `unlimited_quota` is `false`, model requests
are rejected as quota exhausted.
example: 100000
unlimited_quota:
type: boolean
description: Whether the key bypasses remaining-quota checks.
example: false
model_limits_enabled:
type: boolean
description: >-
Whether model restrictions are active for this key. When `false`,
`model_limits` is ignored.
example: false
model_limits:
type: string
description: >-
Comma-separated model IDs allowed by this key when
`model_limits_enabled` is `true`. Empty means no configured model
list.
example: ''
allow_ips:
type:
- string
- 'null'
description: >-
Optional IP allowlist stored as one newline-separated string. Each
entry can be a single IPv4 address, single IPv6 address, IPv4 CIDR,
or IPv6 CIDR. Example:
`198.51.100.10\n203.0.113.0/24\n2001:db8::/32`. `null` or `""` means
IP restrictions are disabled.
example: |-
198.51.100.10
203.0.113.0/24
2001:db8::/32
used_quota:
type: integer
description: Quota already consumed by this key in CometAPI internal quota units.
example: 0
group:
type: string
description: >-
Account group restriction for this key. Empty means no explicit
group restriction.
example: ''
cross_group_retry:
type: boolean
description: >-
Whether cross-group retry is enabled for automatic group routing.
This is only meaningful when the key uses an auto-routed group such
as `auto`.
example: false
additionalProperties: true
securitySchemes:
accessTokenAuth:
type: apiKey
in: header
name: Authorization
description: >-
Personal access token copied from CometAPI Console > Personal Settings.
Send the raw token value; do not prefix it with `Bearer`.
````