V2KeysCreateKeyRequestBody

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "#/components/schemas/V2KeysCreateKeyRequestBody",
  "title": "V2KeysCreateKeyRequestBody",
  "type": "object",
  "required": [
    "apiId"
  ],
  "properties": {
    "apiId": {
      "type": "string",
      "minLength": 3,
      "maxLength": 255,
      "pattern": "^[a-zA-Z0-9_]+$",
      "description": "The API namespace this key belongs to.\nKeys from different APIs cannot access each other.\n",
      "example": "api_1234abcd"
    },
    "prefix": {
      "type": "string",
      "minLength": 1,
      "maxLength": 16,
      "pattern": "^[a-zA-Z0-9_]+$",
      "description": "Adds a visual identifier to the beginning of the generated key for easier recognition in logs and dashboards.\nThe prefix becomes part of the actual key string (e.g., `prod_xxxxxxxxx`).\nAvoid using sensitive information in prefixes as they may appear in logs and error messages.\n",
      "example": "prod"
    },
    "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"
    },
    "byteLength": {
      "type": "integer",
      "minimum": 16,
      "maximum": 255,
      "default": 16,
      "description": "Controls the cryptographic strength of the generated key in bytes.\nHigher values increase security but result in longer keys that may be more annoying to handle.\nThe default 16 bytes provides 2^128 possible combinations, sufficient for most applications.\nConsider 32 bytes for highly sensitive APIs, but avoid values above 64 bytes unless specifically required.\n",
      "example": 24
    },
    "externalId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "pattern": "^[a-zA-Z0-9_.-]+$",
      "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,
        "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": 1,
        "maxLength": 100
      },
      "pattern": "^[a-zA-Z][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"
      ]
    },
    "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",
      "example": 1704067200000
    },
    "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
        }
      ]
    },
    "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
    },
    "recoverable": {
      "type": "boolean",
      "default": false,
      "description": "Controls whether the plaintext key is stored in an encrypted vault for later retrieval.\nWhen true, allows recovering the actual key value using keys.getKey with decrypt=true.\nWhen false, the key value cannot be retrieved after creation for maximum security.\nOnly enable for development keys or when key recovery is absolutely necessary.\n",
      "example": false
    }
  },
  "additionalProperties": false
}