feat: add identity-based credits OpenAPI specifications

go/apps/api/openapi/openapi-split.yaml

@@ -143,6 +143,8 @@ paths:
     $ref: "./spec/paths/v2/identities/listIdentities/index.yaml"
   /v2/identities.updateIdentity:
     $ref: "./spec/paths/v2/identities/updateIdentity/index.yaml"
+  /v2/identities.updateCredits:
+    $ref: "./spec/paths/v2/identities/updateCredits/index.yaml"
 
   # Key Endpoints
   /v2/keys.addPermissions:

go/apps/api/openapi/overlay.yaml

@@ -31,23 +31,29 @@ actions:
   - target: $["components"]["schemas"]["V2KeysUpdateKeyRequestBody"]["properties"]["expires"]
     update:
       nullable: true
-  - target: $["components"]["schemas"]["KeyCreditsData"]["properties"]["remaining"]["type"]
+  # Credits overlays (now consolidated)
+  - target: $["components"]["schemas"]["Credits"]["properties"]["remaining"]["type"]
     update: integer
-  - target: $["components"]["schemas"]["KeyCreditsData"]["properties"]["remaining"]
+  - target: $["components"]["schemas"]["Credits"]["properties"]["remaining"]
     update:
       nullable: true
-  - target: $["components"]["schemas"]["UpdateKeyCreditsData"]["type"]
+  - target: $["components"]["schemas"]["UpdateCredits"]["type"]
     update: object
-  - target: $["components"]["schemas"]["UpdateKeyCreditsData"]
+  - target: $["components"]["schemas"]["UpdateCredits"]
     update:
       nullable: true
-  - target: $["components"]["schemas"]["UpdateKeyCreditsData"]["properties"]["remaining"]["type"]
+  - target: $["components"]["schemas"]["UpdateCredits"]["properties"]["remaining"]["type"]
     update: integer
-  - target: $["components"]["schemas"]["UpdateKeyCreditsData"]["properties"]["remaining"]
+  - target: $["components"]["schemas"]["UpdateCredits"]["properties"]["remaining"]
     update:
       nullable: true
-  - target: $["components"]["schemas"]["UpdateKeyCreditsRefill"]["type"]
+  - target: $["components"]["schemas"]["UpdateCreditsRefill"]["type"]
     update: object
-  - target: $["components"]["schemas"]["UpdateKeyCreditsRefill"]
+  - target: $["components"]["schemas"]["UpdateCreditsRefill"]
+    update:
+      nullable: true
+  - target: $["components"]["schemas"]["V2IdentitiesUpdateCreditsRequestBody"]["properties"]["value"]["type"]
+    update: integer
+  - target: $["components"]["schemas"]["V2IdentitiesUpdateCreditsRequestBody"]["properties"]["value"]
     update:
       nullable: true

go/apps/api/openapi/spec/common/CreditInterval.yaml

@@ -0,0 +1,6 @@
+type: string
+enum:
+  - daily
+  - monthly
+description: How often credits are automatically refilled.
+example: monthly

go/apps/api/openapi/spec/common/CreditOperation.yaml

@@ -0,0 +1,8 @@
+type: string
+enum:
+  - set
+  - increment
+  - decrement
+description: |
+  Defines how to modify credits. Use 'set' to replace current credits with a specific value or unlimited usage, 'increment' to add credits for plan upgrades or credit purchases, and 'decrement' to reduce credits for refunds or policy violations.
+example: set

go/apps/api/openapi/spec/common/KeyCreditsData.yaml → go/apps/api/openapi/spec/common/Credits.yaml

@@ -1,5 +1,5 @@
 type: object
-description: Credit configuration and remaining balance for this key.
+description: Credit configuration and remaining balance.
 properties:
   remaining:
     type:
@@ -11,7 +11,7 @@ properties:
     description: Number of credits remaining (null for unlimited).
     example: 1000
   refill:
-    "$ref": "./KeyCreditsRefill.yaml"
+    "$ref": "./CreditsRefill.yaml"
 required:
   - remaining
-additionalProperties: false
+additionalProperties: false

go/apps/api/openapi/spec/common/KeyCreditsRefill.yaml → go/apps/api/openapi/spec/common/CreditsRefill.yaml

@@ -2,12 +2,7 @@ type: object
 description: Configuration for automatic credit refill behavior.
 properties:
   interval:
-    type: string
-    enum:
-      - daily
-      - monthly
-    description: How often credits are automatically refilled.
-    example: daily
+    "$ref": "./CreditInterval.yaml"
   amount:
     type: integer
     format: int64
@@ -27,4 +22,4 @@ properties:
 required:
   - interval
   - amount
-additionalProperties: false
+additionalProperties: false

go/apps/api/openapi/spec/common/Identity.yaml

@@ -15,6 +15,8 @@ properties:
     description: Identity ratelimits
     items:
       "$ref": "./RatelimitResponse.yaml"
+  credits:
+    "$ref": "./Credits.yaml"
 required:
   - externalId
   - id

go/apps/api/openapi/spec/common/KeyResponseData.yaml

@@ -68,7 +68,7 @@ properties:
       - editor
       - viewer
   credits:
-    "$ref": "./KeyCreditsData.yaml"
+    "$ref": "./Credits.yaml"
   identity:
     "$ref": "./Identity.yaml"
   plaintext:

go/apps/api/openapi/spec/common/UpdateCredits.yaml

@@ -0,0 +1,21 @@
+type:
+  - object
+  - "null"
+description: |
+  Update credit configuration.
+  Omitting this field preserves existing credits, while setting to null removes credit limits entirely.
+
+  Use this for adjusting usage quotas when users change subscription plans or purchase additional credits.
+properties:
+  remaining:
+    type:
+      - integer
+      - "null"
+    format: int64
+    minimum: 0
+    maximum: 9223372036854775807
+    description: Number of credits remaining (null for unlimited).
+    example: 1000
+  refill:
+    "$ref": "./UpdateCreditsRefill.yaml"
+additionalProperties: false

go/apps/api/openapi/spec/paths/v2/keys/updateKey/UpdateKeyCreditsRefill.yaml → go/apps/api/openapi/spec/common/UpdateCreditsRefill.yaml

@@ -1,15 +1,10 @@
 type:
   - object
-  - null
-description: Configuration for automatic credit refill behavior.
+  - "null"
+description: Configuration for automatic credit refill behavior. Set to null to disable refills.
 properties:
   interval:
-    type: string
-    enum:
-      - daily
-      - monthly
-    description: How often credits are automatically refilled.
-    example: daily
+    "$ref": "./CreditInterval.yaml"
   amount:
     type: integer
     format: int64
@@ -29,4 +24,4 @@ properties:
 required:
   - interval
   - amount
-additionalProperties: false
+additionalProperties: false

go/apps/api/openapi/spec/paths/v2/identities/createIdentity/V2IdentitiesCreateIdentityRequestBody.yaml

@@ -45,3 +45,12 @@ properties:
       - Each named limit can have different thresholds and windows
 
       When verifying keys, you can specify which limits you want to use and all keys attached to this identity will share the limits, regardless of which specific key is used.
+  credits:
+    "$ref": "../../../../common/Credits.yaml"
+    description: |
+      Configure credit limits for this identity that are shared across all associated keys.
+      When a key belonging to this identity is verified, credits are deducted from the identity's balance rather than individual key limits.
+      Essential for implementing usage-based billing and quota management at the user or organization level.
+
+      Identity credits take priority over key-level credits during verification.
+      If not specified, the identity has unlimited credits by default.

go/apps/api/openapi/spec/paths/v2/identities/updateCredits/V2IdentitiesUpdateCreditsRequestBody.yaml

@@ -0,0 +1,70 @@
+type: object
+required:
+  - identity
+  - operation
+properties:
+  identity:
+    type: string
+    minLength: 3
+    description: The ID of the identity to update. Accepts either the externalId (your system-generated identifier) or the identityId (internal identifier returned by the identity service). This uniquely identifies which identity's credits will be updated across all associated keys.
+    example: user_123
+  value:
+    type:
+      - integer
+      - "null"
+    format: int64
+    minimum: 0
+    maximum: 9223372036854775807
+    description: |
+      The credit value to use with the specified operation. The meaning depends on the operation: for 'set', this becomes the new remaining credits value; for 'increment', this amount is added to current credits; for 'decrement', this amount is subtracted from current credits.
+
+      Set to null when using 'set' operation to make the identity unlimited (removes usage restrictions entirely). When decrementing, if the result would be negative, remaining credits are automatically set to zero. Credits are consumed during successful key verification for keys associated with this identity, and when credits reach zero, verification fails with `code=INSUFFICIENT_CREDITS`.
+
+      Required when using 'increment' or 'decrement' operations. Optional for 'set' operation (null creates unlimited usage).
+    example: 10000
+  operation:
+    "$ref": "../../../../common/CreditOperation.yaml"
+additionalProperties: false
+examples:
+  planUpgrade:
+    summary: Upgrade user to higher credit tier
+    description: Increase credits when user upgrades to a higher-tier plan
+    value:
+      identity: user_premium_1234
+      operation: set
+      value: 50000
+  creditPurchase:
+    summary: Add purchased credits to existing balance
+    description: User bought additional credits to add to their current quota
+    value:
+      identity: user_5678
+      operation: increment
+      value: 10000
+  unlimitedUpgrade:
+    summary: Upgrade to unlimited usage plan
+    description: Remove credit restrictions for enterprise tier users
+    value:
+      identity: org_enterprise_9876
+      operation: set
+      value: null
+  billingCycleReset:
+    summary: Reset monthly quota at billing cycle
+    description: Refresh user's monthly credit allocation
+    value:
+      identity: user_monthly_abcd
+      operation: set
+      value: 100000
+  policyViolation:
+    summary: Reduce credits for policy violation
+    description: Subtract credits as penalty for terms of service violation
+    value:
+      identity: user_violation_123
+      operation: decrement
+      value: 5000
+  refundCredits:
+    summary: Refund unused credits
+    description: Remove credits when processing a partial refund
+    value:
+      identity: user_refund_789
+      operation: decrement
+      value: 15000

go/apps/api/openapi/spec/paths/v2/identities/updateCredits/V2IdentitiesUpdateCreditsResponseBody.yaml

@@ -0,0 +1,56 @@
+type: object
+required:
+  - meta
+  - data
+properties:
+  meta:
+    "$ref": "../../../../common/Meta.yaml"
+  data:
+    "$ref": "../../../../common/Credits.yaml"
+additionalProperties: false
+examples:
+  planUpgradeSuccess:
+    summary: Plan upgrade completed
+    description: Credits updated after user upgraded to higher tier
+    value:
+      meta:
+        requestId: req_upgrade_1234
+      data:
+        remaining: 50000
+        refill:
+          interval: monthly
+          amount: 50000
+          refillDay: 1
+  creditPurchaseSuccess:
+    summary: Credit purchase completed
+    description: Additional credits added to user's balance
+    value:
+      meta:
+        requestId: req_purchase_5678
+      data:
+        remaining: 35000
+        refill:
+          interval: monthly
+          amount: 25000
+          refillDay: 15
+  unlimitedUpgradeSuccess:
+    summary: Unlimited upgrade completed
+    description: User upgraded to unlimited usage plan
+    value:
+      meta:
+        requestId: req_unlimited_9876
+      data:
+        remaining: null
+        refill: null
+  billingResetSuccess:
+    summary: Billing cycle reset completed
+    description: Monthly quota refreshed at billing cycle
+    value:
+      meta:
+        requestId: req_reset_abcd
+      data:
+        remaining: 100000
+        refill:
+          interval: monthly
+          amount: 100000
+          refillDay: 1

go/apps/api/openapi/spec/paths/v2/identities/updateCredits/index.yaml

@@ -0,0 +1,70 @@
+post:
+  tags:
+    - identities
+  summary: Update identity credits
+  description: |
+    Update credit quotas for an identity in response to plan changes, billing cycles, or usage purchases.
+
+    Use this for user upgrades/downgrades, monthly quota resets, credit purchases, or promotional bonuses. Supports three operations: set, increment, or decrement credits. Set to null for unlimited usage.
+
+    Identity credits are shared across all keys belonging to the identity and take priority over key-level credits during verification.
+
+    **Important**: Setting unlimited credits automatically clears existing refill configurations.
+
+    **Required Permissions**
+
+    Your root key must have one of the following permissions:
+    - `identity.*.update_identity` (to update any identity)
+    - `identity.<identity_id>.update_identity` (to update a specific identity)
+
+    **Side Effects**
+
+    Credit updates take effect immediately. Setting credits to unlimited automatically clears any existing refill settings. Changes propagate instantly but may take up to 30 seconds to reach all edge regions.
+  operationId: identities.updateCredits
+  x-speakeasy-name-override: updateCredits
+  security:
+    - rootKey: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          "$ref": "./V2IdentitiesUpdateCreditsRequestBody.yaml"
+  responses:
+    "200":
+      description: |
+        Credits updated successfully. Response includes updated remaining credits and refill settings.
+      content:
+        application/json:
+          schema:
+            "$ref": "./V2IdentitiesUpdateCreditsResponseBody.yaml"
+    "400":
+      description: Bad request
+      content:
+        application/json:
+          schema:
+            "$ref": "../../../../error/BadRequestErrorResponse.yaml"
+    "401":
+      description: Unauthorized
+      content:
+        application/json:
+          schema:
+            "$ref": "../../../../error/UnauthorizedErrorResponse.yaml"
+    "403":
+      description: Forbidden
+      content:
+        application/json:
+          schema:
+            "$ref": "../../../../error/ForbiddenErrorResponse.yaml"
+    "404":
+      description: Not found
+      content:
+        application/json:
+          schema:
+            "$ref": "../../../../error/NotFoundErrorResponse.yaml"
+    "500":
+      description: Internal server error
+      content:
+        application/json:
+          schema:
+            "$ref": "../../../../error/InternalServerErrorResponse.yaml"

go/apps/api/openapi/spec/paths/v2/identities/updateIdentity/V2IdentitiesUpdateIdentityRequestBody.yaml

@@ -33,6 +33,8 @@ properties:
         limit: 1000
         duration: 3600000
         autoApply: true
+  credits:
+    "$ref": "../../../../common/UpdateCredits.yaml"
 additionalProperties: false
 required:
   - identity

go/apps/api/openapi/spec/paths/v2/keys/createKey/V2KeysCreateKeyRequestBody.yaml

@@ -118,7 +118,7 @@ properties:
       Essential for trial periods, temporary access, and security compliance requiring key rotation.
     example: 1704067200000
   credits:
-    "$ref": "../../../../common/KeyCreditsData.yaml"
+    "$ref": "../../../../common/Credits.yaml"
     description: |
       Controls usage-based limits through credit consumption with optional automatic refills.
       Unlike rate limits which control frequency, credits control total usage with global consistency.