> ## 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/ لتحديث مفتاح API حسب المعرّف مع الحقول القابلة للتعديل في نص JSON.

استخدم نقطة النهاية هذه لتحديث اسم مفتاح API، وحالته، والحصة، وتاريخ انتهاء الصلاحية، وقيود النموذج، وقائمة IP المسموح بها، وإعدادات المجموعة.

<Note>
  أنشئ personal access token من [Console → Personal Settings](https://www.cometapi.com/console/personal)، ثم أرسله كقيمة خام لترويسة `Authorization`. لا تضف إليه البادئة `Bearer`.
</Note>

<Warning>
  تستخدم نقطة النهاية هذه `PUT /api/token/`، ويجب وضع `id` داخل نص JSON. أرسل الحقول القابلة للتعديل التي تريد الاحتفاظ بها؛ إذ يمكن إعادة تعيين الحقول الرقمية أو المنطقية أو النصية التي يتم حذفها أثناء التحديث.
</Warning>

## نص الطلب

| Field                  | Type           | Description                                                                                                                                                                                                                                  |
| ---------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                   | integer        | مطلوب. معرّف مفتاح API الذي يتم إرجاعه بواسطة [List API keys](./list-api-keys).                                                                                                                                                              |
| `name`                 | string         | اسم عرض مقروء للمستخدم للمفتاح. يجب ألا يزيد عن 50 حرفًا.                                                                                                                                                                                    |
| `status`               | integer        | الحالة التشغيلية. تؤدي القيمة `1` إلى تفعيل المفتاح لطلبات النموذج. وتؤدي `2` إلى تعطيله. وتشير `3` إلى أنه منتهي الصلاحية. وتشير `4` إلى استنفاد الحصة. يتم رفض المفاتيح المعطلة أو منتهية الصلاحية أو المستنفدة بواسطة نقاط نهاية النموذج. |
| `expired_time`         | integer        | طابع زمني Unix بالثواني يحدد وقت انتهاء صلاحية المفتاح. استخدم `-1` لعدم وجود انتهاء صلاحية. يمنع الطابع الزمني الماضي طلبات النموذج.                                                                                                        |
| `remain_quota`         | integer        | الحصة المتبقية بوحدات الحصة الداخلية في CometAPI. إذا وصلت هذه القيمة إلى `0` وكانت `unlimited_quota` تساوي `false`، فسيتم رفض طلبات النموذج باستخدام هذا المفتاح باعتبار أن الحصة مستنفدة.                                                  |
| `unlimited_quota`      | boolean        | ما إذا كان المفتاح يتجاوز فحوصات الحصة المتبقية. اضبطها على `true` فقط عندما يجب أن يستمر المفتاح في العمل حتى إذا كانت `remain_quota` تساوي `0`.                                                                                            |
| `model_limits_enabled` | boolean        | ما إذا كان يجب تقييد هذا المفتاح بنماذج محددة. عندما تكون القيمة `false`، يتم تجاهل `model_limits`.                                                                                                                                          |
| `model_limits`         | string         | model IDs مفصولة بفواصل ومسموح بها لهذا المفتاح عندما تكون `model_limits_enabled` تساوي `true`. استخدم model IDs التي يتم إرجاعها من `/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        | ما إذا كانت إعادة المحاولة عبر المجموعات مفعلة للتوجيه التلقائي للمجموعات. يكون لهذا معنى فقط عندما يستخدم المفتاح مجموعة يتم توجيهها تلقائيًا.                                                                                              |

## تنسيق القائمة المسموح بها

للسماح بعدة عناوين 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`.

````