> ## 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 키 업데이트

> CometAPI PUT /api/token/을 사용해 JSON 본문의 수정 가능한 필드로 ID 기준 API 키를 업데이트합니다.

이 엔드포인트를 사용하면 API 키의 이름, 상태, quota, 만료, 모델 제한, IP 허용 목록, 그룹 설정을 업데이트할 수 있습니다.

<Note>
  [Console → Personal Settings](https://www.cometapi.com/console/personal)에서 personal access token을 생성한 다음, 이를 가공하지 않은 `Authorization` 헤더 값으로 전송하세요. `Bearer` 접두사는 붙이지 마세요.
</Note>

<Warning>
  이 엔드포인트는 `PUT /api/token/`을 사용하며, `id`는 JSON 본문에 들어갑니다. 유지하려는 수정 가능 필드를 함께 전송하세요. 생략된 숫자, 불리언 또는 문자열 필드는 업데이트 과정에서 재설정될 수 있습니다.
</Warning>

## Request body

| Field                  | Type           | Description                                                                                                                                                        |
| ---------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `id`                   | integer        | 필수. [List API keys](./list-api-keys)에서 반환된 API 키 ID입니다.                                                                                                            |
| `name`                 | string         | 키의 사용자용 표시 이름입니다. 50자 이하여야 합니다.                                                                                                                                    |
| `status`               | integer        | 운영 상태입니다. `1`은 모델 요청에 키를 활성화합니다. `2`는 비활성화합니다. `3`은 만료됨으로 표시합니다. `4`는 quota 소진으로 표시합니다. 비활성화되었거나, 만료되었거나, 소진된 키는 모델 엔드포인트에서 거부됩니다.                                 |
| `expired_time`         | integer        | 키가 만료되는 시점의 초 단위 Unix timestamp입니다. 만료 없음은 `-1`을 사용하세요. 과거 timestamp는 모델 요청을 차단합니다.                                                                                |
| `remain_quota`         | integer        | CometAPI 내부 quota 단위 기준 남은 quota입니다. 이 값이 `0`에 도달하고 `unlimited_quota`가 `false`이면, 이 키를 사용하는 모델 요청은 quota 소진으로 거부됩니다.                                               |
| `unlimited_quota`      | boolean        | 이 키가 남은 quota 확인을 우회할지 여부입니다. `remain_quota`가 `0`이어도 키가 계속 동작해야 하는 경우에만 `true`로 설정하세요.                                                                             |
| `model_limits_enabled` | boolean        | 이 키를 특정 모델로 제한할지 여부입니다. `false`이면 `model_limits`는 무시됩니다.                                                                                                           |
| `model_limits`         | string         | `model_limits_enabled`가 `true`일 때 이 키로 허용되는 쉼표로 구분된 model ID 목록입니다. `/v1/models`에서 반환된 model ID를 사용하세요. 모델 제한이 없으면 빈 문자열을 사용하세요.                                   |
| `allow_ips`            | string or null | 선택적 IP 허용 목록입니다. 항목 사이를 줄바꿈 문자(`\n`)로 구분한 하나의 JSON 문자열로 제공하세요. 각 항목은 단일 IPv4 주소, 단일 IPv6 주소, IPv4 CIDR 또는 IPv6 CIDR일 수 있습니다. IP 제한을 비활성화하려면 `null` 또는 `""`를 사용하세요. |
| `group`                | string         | 선택적 계정 그룹 제한입니다. 명시적 그룹이 없으면 빈 문자열을 사용하세요. 비어 있지 않은 값은 해당 계정에서 사용 가능해야 하며, 그렇지 않으면 API가 `success: false`를 반환합니다.                                                   |
| `cross_group_retry`    | boolean        | 자동 그룹 라우팅을 위한 cross-group retry 활성화 여부입니다. 이 값은 키가 자동 라우팅 그룹을 사용할 때만 의미가 있습니다.                                                                                     |

## Allowlist format

여러 IP 또는 CIDR 범위를 허용하려면, 항목 사이에 `\n`을 넣은 하나의 JSON 문자열로 전송하세요:

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

````