V2KeysMigrateKeyData

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "#/components/schemas/V2KeysMigrateKeyData",
  "title": "V2KeysMigrateKeyData",
  "type": "object",
  "properties": {
    "hash": {
      "type": "string",
      "minLength": 3,
      "description": "The current hash of the key on your side",
      "example": "your_already_hashed_key"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Sets a human-readable identifier for internal organization and dashboard display.\nNever exposed to end users, only visible in management interfaces and API responses.\nAvoid generic names like \"API Key\" when managing multiple keys for the same user or service.\n",
      "example": "Payment Service Production Key"
    },
    "externalId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Links this key to a user or entity in your system using your own identifier.\nReturned during verification to identify the key owner without additional database lookups.\nEssential for user-specific analytics, billing, and multi-tenant key management.\nUse your primary user ID, organization ID, or tenant ID for best results.\nAccepts letters, numbers, underscores, dots, and hyphens for flexible identifier formats.\n",
      "example": "user_1234abcd"
    },
    "meta": {
      "type": "object",
      "additionalProperties": true,
      "maxProperties": 100,
      "description": "Stores arbitrary JSON metadata returned during key verification for contextual information.\nEliminates additional database lookups during verification, improving performance for stateless services.\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",
        "featureFlags": {
          "betaAccess": true,
          "concurrentConnections": 10
        },
        "customerName": "Acme Corp",
        "billing": {
          "tier": "premium",
          "renewal": "2024-12-31"
        }
      }
    },
    "roles": {
      "type": "array",
      "maxItems": 100,
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 100
      },
      "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": 1,
        "maxLength": 100
      },
      "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"
      ]
    },
    "expires": {
      "type": "integer",
      "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 creates a permanent key that never expires.\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.\nEssential for trial periods, temporary access, and security compliance requiring key rotation.\n"
    },
    "enabled": {
      "type": "boolean",
      "default": true,
      "description": "Controls whether the key is active immediately upon creation.\nWhen set to `false`, the key exists but all verification attempts fail with `code=DISABLED`.\nUseful for pre-creating keys that will be activated later or for keys requiring manual approval.\nMost keys should be created with `enabled=true` for immediate use.\n",
      "example": true
    },
    "credits": {
      "$ref": "#/components/schemas/KeyCreditsData",
      "description": "Controls usage-based limits through credit consumption with optional automatic refills.\nUnlike rate limits which control frequency, credits control total usage with global consistency.\nEssential for implementing usage-based pricing, subscription tiers, and hard usage quotas.\nOmitting this field creates unlimited usage, while setting null is not allowed during creation.\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.\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.\nEssential for preventing API abuse while maintaining good performance for legitimate usage.\n",
      "example": [
        {
          "name": "requests",
          "limit": 100,
          "duration": 60000,
          "autoApply": true
        },
        {
          "name": "heavy_operations",
          "limit": 10,
          "duration": 3600000,
          "autoApply": false
        }
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "hash"
  ]
}