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

# Обновление API key

> Используйте CometAPI PUT /api/token/ для обновления API key по ID с редактируемыми полями в JSON body.

Используйте этот endpoint, чтобы обновить имя API key, статус, квоту, срок действия, ограничения моделей, список разрешённых IP-адресов и настройки группы.

<Note>
  Сгенерируйте personal access token в [Console → Personal Settings](https://www.cometapi.com/console/personal), затем передайте его как необработанное значение заголовка `Authorization`. Не добавляйте префикс `Bearer`.
</Note>

<Warning>
  Этот endpoint использует `PUT /api/token/`, а `id` должен находиться в JSON body. Передавайте редактируемые поля, которые хотите сохранить; пропущенные числовые, логические или строковые поля могут быть сброшены при обновлении.
</Warning>

## Тело запроса

| Field                  | Type           | Description                                                                                                                                                                                                                                                                                     |
| ---------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                   | integer        | Обязательно. ID API key, возвращаемый методом [List API keys](./list-api-keys).                                                                                                                                                                                                                 |
| `name`                 | string         | Отображаемое имя key, понятное пользователю. Должно содержать не более 50 символов.                                                                                                                                                                                                             |
| `status`               | integer        | Рабочий статус. `1` включает key для запросов к моделям. `2` отключает её. `3` помечает её как истёкшую. `4` помечает её как исчерпавшую квоту. Отключённые, истёкшие или исчерпавшие квоту key отклоняются endpoint'ами моделей.                                                               |
| `expired_time`         | integer        | Unix timestamp в секундах, когда срок действия key истекает. Используйте `-1` для отсутствия срока действия. Метка времени в прошлом блокирует запросы к моделям.                                                                                                                               |
| `remain_quota`         | integer        | Оставшаяся квота во внутренних единицах квоты CometAPI. Если это значение достигает `0` и `unlimited_quota` равно `false`, запросы к моделям с этой key отклоняются как исчерпавшие квоту.                                                                                                      |
| `unlimited_quota`      | boolean        | Определяет, пропускает ли key проверку оставшейся квоты. Устанавливайте `true` только если key должна продолжать работать, даже когда `remain_quota` равно `0`.                                                                                                                                 |
| `model_limits_enabled` | boolean        | Определяет, нужно ли ограничивать эту key конкретными моделями. Когда `false`, `model_limits` игнорируется.                                                                                                                                                                                     |
| `model_limits`         | string         | Разделённые запятыми model ID, разрешённые для этой key, когда `model_limits_enabled` равно `true`. Используйте model ID, возвращаемые `/v1/models`; используйте пустую строку, если ограничения по моделям не нужны.                                                                           |
| `allow_ips`            | string or null | Необязательный список разрешённых IP-адресов. Передайте одну JSON-строку с записями, разделёнными символами новой строки (`\n`). Каждая запись может быть отдельным IPv4-адресом, отдельным IPv6-адресом, IPv4 CIDR или IPv6 CIDR. Используйте `null` или `""`, чтобы отключить IP-ограничения. |
| `group`                | string         | Необязательное ограничение по группе аккаунта. Используйте пустую строку, если явная группа не нужна. Непустые значения должны быть доступны аккаунту, иначе API вернёт `success: false`.                                                                                                       |
| `cross_group_retry`    | boolean        | Определяет, включён ли межгрупповой повтор для автоматической маршрутизации по группам. Это имеет смысл только когда key использует группу с автоматической маршрутизацией.                                                                                                                     |

## Формат списка разрешённых адресов

Чтобы разрешить несколько IP-адресов или диапазонов CIDR, передайте их как одну JSON-строку с `\n` между записями:

```json theme={null}
{
  "allow_ips": "198.51.100.10\n203.0.113.0/24\n2001:db8::/32"
}
```

Этот пример разрешает один IPv4-адрес, один диапазон IPv4 CIDR и один диапазон 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 `<model-id-1>,<model-id-2>`. 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`.

````