> ## 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 body 内の編集可能なフィールドで 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 body に含めます。保持したい編集可能なフィールドを送信してください。省略した数値、boolean、または文字列フィールドは、更新時にリセットされる可能性があります。
</Warning>

## リクエスト本文

| 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 タイムスタンプ。期限なしの場合は `-1` を使用します。過去のタイムスタンプはモデルリクエストをブロックします。                                                                                   |
| `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`）でエントリを区切った 1 つの JSON 文字列を指定します。各エントリには、単一の IPv4 アドレス、単一の IPv6 アドレス、IPv4 CIDR、または IPv6 CIDR を指定できます。IP 制限を無効にするには `null` または `""` を使用します。 |
| `group`                | string         | 任意のアカウントグループ制限。明示的なグループなしの場合は空文字列を使用します。空でない値はアカウントで利用可能である必要があり、そうでない場合 API は `success: false` を返します。                                                          |
| `cross_group_retry`    | boolean        | 自動グループルーティングのために cross-group retry が有効かどうか。これはキーが自動ルーティングされたグループを使用している場合にのみ意味を持ちます。                                                                            |

## 許可リストの形式

複数の IP または CIDR 範囲を許可するには、エントリの間に `\n` を入れた 1 つの JSON 文字列として送信します。

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

この例では、1 つの IPv4 アドレス、1 つの IPv4 CIDR 範囲、1 つの 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`.

````