{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "#/components/schemas/V2KeysUpdateKeyRequestBody",
  "title": "V2KeysUpdateKeyRequestBody",
  "type": "object",
  "required": [
    "keyId"
  ],
  "properties": {
    "keyId": {
      "type": "string",
      "minLength": 3,
      "maxLength": 255,
      "pattern": "^[a-zA-Z0-9_]+$",
      "description": "Specifies which key to update using the database identifier returned from `createKey`.\nDo not confuse this with the actual API key string that users include in requests.\n",
      "example": "key_2cGKbMxRyIzhCxo1Idjz8q"
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 255,
      "description": "Sets a human-readable name for internal organization and identification.\nOmitting this field leaves the current name unchanged, while setting null removes it entirely.\nAvoid generic names like \"API Key\" when managing multiple keys per user or service.\n",
      "example": "Payment Service Production Key"
    },
    "externalId": {
      "type": [
        "string",
        "null"
      ],
      "minLength": 1,
      "maxLength": 255,
      "pattern": "^[a-zA-Z0-9_.-]+$",
      "description": "Links this key to a user or entity in your system for ownership tracking during verification.\nOmitting this field preserves the current association, while setting null disconnects the key from any identity.\nEssential for user-specific analytics, billing, and key management across multiple users.\nSupports letters, numbers, underscores, dots, and hyphens for flexible identifier formats.\n",
      "example": "user_912a841d"
    },
    "meta": {
      "type": [
        "object",
        "null"
      ],
      "additionalProperties": true,
      "maxProperties": 100,
      "description": "Stores arbitrary JSON metadata returned during key verification.\nOmitting this field preserves existing metadata, while setting null removes all metadata entirely.\nAvoid storing sensitive data here as it's returned in verification responses.\nLarge metadata objects increase verification latency and should stay under 10KB total size.\n",
      "example": {
        "plan": "enterprise",
        "limits": {
          "storage": "500GB",
          "compute": "1000 minutes/month"
        },
        "features": [
          "analytics",
          "exports",
          "webhooks"
        ],
        "hasAcceptedTerms": true,
        "billing": {
          "cycle": "monthly",
          "next_billing": "2024-01-15"
        },
        "preferences": {
          "timezone": "UTC",
          "notifications": true
        },
        "lastBillingDate": "2023-10-15"
      }
    },
    "expires": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64",
      "minimum": 0,
      "maximum": 4102444800000,
      "description": "Sets when this key automatically expires as a Unix timestamp in milliseconds.\nVerification fails with code=EXPIRED immediately after this time passes.\nOmitting this field preserves the current expiration, while setting null makes the key permanent.\n\nAvoid setting timestamps in the past as they immediately invalidate the key.\nKeys expire based on server time, not client time, which prevents timezone-related issues.\nActive sessions continue until their next verification attempt after expiry.\n",
      "example": 1704067200000
    },
    "credits": {
      "$ref": "#/components/schemas/UpdateKeyCreditsData",
      "description": "Controls usage-based limits for this key through credit consumption.\nOmitting this field preserves current credit settings, while setting null enables unlimited usage.\nCannot configure refill settings when credits is null, and refillDay requires monthly interval.\nEssential for implementing usage-based pricing and subscription quotas.\n"
    },
    "ratelimits": {
      "type": "array",
      "maxItems": 50,
      "items": {
        "$ref": "#/components/schemas/RatelimitRequest"
      },
      "description": "Defines time-based rate limits that protect against abuse by controlling request frequency.\nOmitting this field preserves existing rate limits, while setting null removes all rate limits.\nUnlike credits which track total usage, rate limits reset automatically after each window expires.\nMultiple rate limits can control different operation types with separate thresholds and windows.\n"
    },
    "enabled": {
      "type": "boolean",
      "description": "Controls whether the key is currently active for verification requests.\nWhen set to `false`, all verification attempts fail with `code=DISABLED` regardless of other settings.\nOmitting this field preserves the current enabled status.\nUseful for temporarily suspending access during billing issues, security incidents, or maintenance windows without losing key configuration.\n",
      "example": true
    },
    "roles": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 100,
        "pattern": "^[a-zA-Z0-9_:\\-\\.\\*]+$",
        "description": "Assigns existing roles to this key for permission management through role-based access control.\nRoles must already exist in your workspace before assignment.\nDuring verification, all permissions from assigned roles are checked against requested permissions.\nRoles provide a convenient way to group permissions and apply consistent access patterns across multiple keys.\n"
      },
      "example": [
        "api_admin",
        "billing_reader"
      ]
    },
    "permissions": {
      "type": "array",
      "maxItems": 1000,
      "items": {
        "type": "string",
        "minLength": 3,
        "maxLength": 100,
        "pattern": "^[a-zA-Z0-9_:\\-\\.\\*]+$",
        "description": "Grants specific permissions directly to this key without requiring role membership.\nWildcard permissions like `documents.*` grant access to all sub-permissions including `documents.read` and `documents.write`.\nDirect permissions supplement any permissions inherited from assigned roles.\n"
      },
      "example": [
        "documents.read",
        "documents.write",
        "settings.view"
      ]
    }
  },
  "additionalProperties": false
}