{
  "components": {
    "schemas": {
      "AccountUsageDto": {
        "additionalProperties": false,
        "properties": {
          "developerId": {
            "format": "uuid",
            "type": "string"
          },
          "keys": {
            "items": {
              "$ref": "#/components/schemas/KeyUsageDto"
            },
            "nullable": true,
            "type": "array"
          },
          "organizationId": {
            "format": "uuid",
            "nullable": true,
            "type": "string"
          },
          "overageAccruedMinor": {
            "format": "int64",
            "nullable": true,
            "type": "integer"
          },
          "overageCeilingMinor": {
            "format": "int64",
            "nullable": true,
            "type": "integer"
          },
          "overageCurrency": {
            "nullable": true,
            "type": "string"
          },
          "overageRequests": {
            "format": "int64",
            "type": "integer"
          },
          "periodEnd": {
            "format": "date-time",
            "type": "string"
          },
          "periodStart": {
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "AcknowledgeSunsetRequest": {
        "additionalProperties": false,
        "properties": {
          "applicationId": {
            "format": "uuid",
            "type": "string"
          }
        },
        "type": "object"
      },
      "ApiKeyDto": {
        "additionalProperties": false,
        "properties": {
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "description": {
            "nullable": true,
            "type": "string"
          },
          "expiresAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "failedRequests": {
            "format": "int64",
            "type": "integer"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "ipWhitelist": {
            "items": {
              "type": "string"
            },
            "nullable": true,
            "type": "array"
          },
          "keyPrefix": {
            "nullable": true,
            "type": "string"
          },
          "lastRotatedAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "lastUsedAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "name": {
            "nullable": true,
            "type": "string"
          },
          "requestsPerDay": {
            "format": "int32",
            "type": "integer"
          },
          "requestsPerHour": {
            "format": "int32",
            "type": "integer"
          },
          "requestsPerMinute": {
            "format": "int32",
            "type": "integer"
          },
          "revokedAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "revokedReason": {
            "nullable": true,
            "type": "string"
          },
          "rotationOverlapEndsAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "scopes": {
            "items": {
              "type": "string"
            },
            "nullable": true,
            "type": "array"
          },
          "status": {
            "nullable": true,
            "type": "string"
          },
          "supersededByKeyId": {
            "format": "uuid",
            "nullable": true,
            "type": "string"
          },
          "tier": {
            "nullable": true,
            "type": "string"
          },
          "totalRequests": {
            "format": "int64",
            "type": "integer"
          },
          "userId": {
            "format": "uuid",
            "type": "string"
          }
        },
        "type": "object"
      },
      "ApiKeyDtoPaginatedResponse": {
        "additionalProperties": false,
        "properties": {
          "hasNextPage": {
            "readOnly": true,
            "type": "boolean"
          },
          "hasPreviousPage": {
            "readOnly": true,
            "type": "boolean"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/ApiKeyDto"
            },
            "nullable": true,
            "type": "array"
          },
          "pageNumber": {
            "format": "int32",
            "type": "integer"
          },
          "pageSize": {
            "format": "int32",
            "type": "integer"
          },
          "totalCount": {
            "format": "int32",
            "type": "integer"
          },
          "totalPages": {
            "format": "int32",
            "readOnly": true,
            "type": "integer"
          }
        },
        "type": "object"
      },
      "ApiKeyIntrospectionResultDto": {
        "additionalProperties": false,
        "properties": {
          "active": {
            "type": "boolean"
          },
          "apiKeyId": {
            "format": "uuid",
            "nullable": true,
            "type": "string"
          },
          "organizationId": {
            "format": "uuid",
            "nullable": true,
            "type": "string"
          },
          "scopes": {
            "items": {
              "type": "string"
            },
            "nullable": true,
            "type": "array"
          }
        },
        "type": "object"
      },
      "ApiKeyValidationResultDto": {
        "additionalProperties": false,
        "properties": {
          "apiKeyId": {
            "format": "uuid",
            "nullable": true,
            "type": "string"
          },
          "breachedDimension": {
            "nullable": true,
            "type": "string"
          },
          "burstUsedThisMinute": {
            "format": "int32",
            "nullable": true,
            "type": "integer"
          },
          "dailyResetAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "failureReason": {
            "nullable": true,
            "type": "string"
          },
          "insufficientScope": {
            "type": "boolean"
          },
          "isValid": {
            "type": "boolean"
          },
          "requestsPerDay": {
            "format": "int32",
            "nullable": true,
            "type": "integer"
          },
          "requestsPerDayLimit": {
            "format": "int64",
            "nullable": true,
            "type": "integer"
          },
          "requestsPerHour": {
            "format": "int32",
            "nullable": true,
            "type": "integer"
          },
          "requestsPerMinute": {
            "format": "int32",
            "nullable": true,
            "type": "integer"
          },
          "requestsToday": {
            "format": "int64",
            "nullable": true,
            "type": "integer"
          },
          "requiredScope": {
            "nullable": true,
            "type": "string"
          },
          "retryAfterSeconds": {
            "format": "int32",
            "nullable": true,
            "type": "integer"
          },
          "scopes": {
            "items": {
              "type": "string"
            },
            "nullable": true,
            "type": "array"
          },
          "throttled": {
            "type": "boolean"
          },
          "tier": {
            "nullable": true,
            "type": "string"
          },
          "userId": {
            "format": "uuid",
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "ApiVersionDto": {
        "additionalProperties": false,
        "properties": {
          "changeClass": {
            "nullable": true,
            "type": "string"
          },
          "decisionRegisterRef": {
            "nullable": true,
            "type": "string"
          },
          "deprecatedAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "migrationGuideUrl": {
            "nullable": true,
            "type": "string"
          },
          "remainingConsumers": {
            "format": "int32",
            "type": "integer"
          },
          "replacementVersion": {
            "nullable": true,
            "type": "string"
          },
          "status": {
            "nullable": true,
            "type": "string"
          },
          "sunsetAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "version": {
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "ConsumerMigrationRowDto": {
        "additionalProperties": false,
        "properties": {
          "ackState": {
            "nullable": true,
            "type": "string"
          },
          "applicationName": {
            "nullable": true,
            "type": "string"
          },
          "calls30d": {
            "format": "int64",
            "type": "integer"
          },
          "extensionUntil": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "lastSeenAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "maintainerEmail": {
            "nullable": true,
            "type": "string"
          },
          "migrated": {
            "type": "boolean"
          },
          "principalId": {
            "format": "uuid",
            "type": "string"
          }
        },
        "type": "object"
      },
      "CreateApiKeyRequest": {
        "additionalProperties": false,
        "properties": {
          "description": {
            "nullable": true,
            "type": "string"
          },
          "expiresAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "name": {
            "nullable": true,
            "type": "string"
          },
          "scopes": {
            "items": {
              "type": "string"
            },
            "nullable": true,
            "type": "array"
          },
          "tier": {
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "CreateApiKeyResponse": {
        "additionalProperties": false,
        "properties": {
          "apiKey": {
            "nullable": true,
            "type": "string"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "expiresAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "id": {
            "format": "uuid",
            "type": "string"
          },
          "keyPrefix": {
            "nullable": true,
            "type": "string"
          },
          "name": {
            "nullable": true,
            "type": "string"
          },
          "scopes": {
            "items": {
              "type": "string"
            },
            "nullable": true,
            "type": "array"
          },
          "tier": {
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "DeclareDeprecationRequest": {
        "additionalProperties": false,
        "properties": {
          "changeClass": {
            "nullable": true,
            "type": "string"
          },
          "deprecationDate": {
            "format": "date-time",
            "type": "string"
          },
          "migrationGuideUrl": {
            "nullable": true,
            "type": "string"
          },
          "rationale": {
            "nullable": true,
            "type": "string"
          },
          "replacementVersion": {
            "nullable": true,
            "type": "string"
          },
          "sunsetDate": {
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "DeprecationDecisionDto": {
        "additionalProperties": false,
        "properties": {
          "changeClass": {
            "nullable": true,
            "type": "string"
          },
          "decidedAt": {
            "format": "date-time",
            "type": "string"
          },
          "decidedBy": {
            "nullable": true,
            "type": "string"
          },
          "decisionRegisterRef": {
            "nullable": true,
            "type": "string"
          },
          "rationale": {
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "DeprecationReportDto": {
        "additionalProperties": false,
        "properties": {
          "decision": {
            "$ref": "#/components/schemas/DeprecationDecisionDto"
          },
          "notificationEvidence": {
            "$ref": "#/components/schemas/NotificationEvidenceDto"
          },
          "parity": {
            "items": {
              "$ref": "#/components/schemas/SurfaceParityDto"
            },
            "nullable": true,
            "type": "array"
          },
          "version": {
            "nullable": true,
            "type": "string"
          },
          "zeroTrafficRecord": {
            "$ref": "#/components/schemas/ZeroTrafficRecordDto"
          }
        },
        "type": "object"
      },
      "GrantExtensionRequest": {
        "additionalProperties": false,
        "properties": {
          "reason": {
            "nullable": true,
            "type": "string"
          },
          "until": {
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "IntrospectApiKeyRequest": {
        "additionalProperties": false,
        "properties": {
          "apiKey": {
            "nullable": true,
            "type": "string"
          },
          "requiredScope": {
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "KeyUsageDto": {
        "additionalProperties": false,
        "properties": {
          "applicationId": {
            "format": "uuid",
            "type": "string"
          },
          "applicationName": {
            "nullable": true,
            "type": "string"
          },
          "breachedDimension": {
            "nullable": true,
            "type": "string"
          },
          "burstPerMinuteLimit": {
            "format": "int32",
            "type": "integer"
          },
          "burstUsedThisMinute": {
            "format": "int32",
            "type": "integer"
          },
          "dailyResetAt": {
            "format": "date-time",
            "type": "string"
          },
          "keyId": {
            "format": "uuid",
            "type": "string"
          },
          "requestsPerDayLimit": {
            "format": "int64",
            "nullable": true,
            "type": "integer"
          },
          "requestsToday": {
            "format": "int64",
            "type": "integer"
          },
          "retryAfterSeconds": {
            "format": "int32",
            "nullable": true,
            "type": "integer"
          },
          "throttledNow": {
            "type": "boolean"
          },
          "tierCode": {
            "nullable": true,
            "type": "string"
          },
          "trend7Day": {
            "items": {
              "$ref": "#/components/schemas/UsageTrendPointDto"
            },
            "nullable": true,
            "type": "array"
          }
        },
        "type": "object"
      },
      "MigrationProgressDto": {
        "additionalProperties": false,
        "properties": {
          "consumers": {
            "items": {
              "$ref": "#/components/schemas/ConsumerMigrationRowDto"
            },
            "nullable": true,
            "type": "array"
          },
          "liveRequestsInWindow": {
            "format": "int64",
            "type": "integer"
          },
          "measurementWindowDays": {
            "format": "int32",
            "type": "integer"
          },
          "version": {
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "NotificationEvidenceDto": {
        "additionalProperties": false,
        "properties": {
          "acknowledged": {
            "format": "int32",
            "type": "integer"
          },
          "correlationId": {
            "nullable": true,
            "type": "string"
          },
          "delivered": {
            "format": "int32",
            "type": "integer"
          },
          "failed": {
            "format": "int32",
            "type": "integer"
          },
          "notAcknowledged": {
            "format": "int32",
            "type": "integer"
          },
          "totalRecipients": {
            "format": "int32",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "NotifyCampaignRequest": {
        "additionalProperties": false,
        "properties": {
          "audience": {
            "nullable": true,
            "type": "string"
          },
          "reminderCadence": {
            "items": {
              "type": "string"
            },
            "nullable": true,
            "type": "array"
          }
        },
        "type": "object"
      },
      "NotifyCampaignResponse": {
        "additionalProperties": false,
        "properties": {
          "correlationId": {
            "nullable": true,
            "type": "string"
          },
          "recipients": {
            "format": "int32",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "PendingSunsetDto": {
        "additionalProperties": false,
        "properties": {
          "ackState": {
            "nullable": true,
            "type": "string"
          },
          "applicationId": {
            "format": "uuid",
            "type": "string"
          },
          "applicationName": {
            "nullable": true,
            "type": "string"
          },
          "deprecatedAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "endpointsCalled": {
            "items": {
              "type": "string"
            },
            "nullable": true,
            "type": "array"
          },
          "measurementWindowDays": {
            "format": "int32",
            "type": "integer"
          },
          "migrated": {
            "type": "boolean"
          },
          "migrationGuideUrl": {
            "nullable": true,
            "type": "string"
          },
          "replacementVersion": {
            "nullable": true,
            "type": "string"
          },
          "sunsetAt": {
            "format": "date-time",
            "type": "string"
          },
          "version": {
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "ProblemDetails": {
        "additionalProperties": {},
        "properties": {
          "detail": {
            "nullable": true,
            "type": "string"
          },
          "instance": {
            "nullable": true,
            "type": "string"
          },
          "status": {
            "format": "int32",
            "nullable": true,
            "type": "integer"
          },
          "title": {
            "nullable": true,
            "type": "string"
          },
          "type": {
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "RetireVersionRequest": {
        "additionalProperties": false,
        "properties": {
          "force": {
            "type": "boolean"
          },
          "signOffRationale": {
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "RetireVersionResponse": {
        "additionalProperties": false,
        "properties": {
          "retiredAt": {
            "format": "date-time",
            "type": "string"
          },
          "zeroTrafficVerifiedAt": {
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "RevokeApiKeyRequest": {
        "additionalProperties": false,
        "properties": {
          "reason": {
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "RotateApiKeyRequest": {
        "additionalProperties": false,
        "properties": {
          "overlapHours": {
            "format": "int32",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "RotateApiKeyResponse": {
        "additionalProperties": false,
        "properties": {
          "apiKey": {
            "nullable": true,
            "type": "string"
          },
          "createdAt": {
            "format": "date-time",
            "type": "string"
          },
          "expiresAt": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "keyPrefix": {
            "nullable": true,
            "type": "string"
          },
          "newKeyId": {
            "format": "uuid",
            "type": "string"
          },
          "oldKeyId": {
            "format": "uuid",
            "type": "string"
          },
          "previousKeyValidUntil": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "SurfaceParityDto": {
        "additionalProperties": false,
        "properties": {
          "deprecated": {
            "type": "boolean"
          },
          "detail": {
            "nullable": true,
            "type": "string"
          },
          "surface": {
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "UsageTrendPointDto": {
        "additionalProperties": false,
        "properties": {
          "date": {
            "nullable": true,
            "type": "string"
          },
          "requests": {
            "format": "int64",
            "type": "integer"
          },
          "throttledRequests": {
            "format": "int64",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "ValidateApiKeyRequest": {
        "additionalProperties": false,
        "properties": {
          "apiKey": {
            "nullable": true,
            "type": "string"
          },
          "endpoint": {
            "nullable": true,
            "type": "string"
          },
          "ipAddress": {
            "nullable": true,
            "type": "string"
          },
          "requestedVersion": {
            "nullable": true,
            "type": "string"
          },
          "requiredScope": {
            "nullable": true,
            "type": "string"
          }
        },
        "type": "object"
      },
      "ZeroTrafficRecordDto": {
        "additionalProperties": false,
        "properties": {
          "liveRequestsInWindow": {
            "format": "int64",
            "type": "integer"
          },
          "measurementWindowDays": {
            "format": "int32",
            "type": "integer"
          },
          "verifiedAt": {
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      }
    },
    "securitySchemes": {
      "Bearer": {
        "description": "JWT Authorization header using the Bearer scheme. Example: \"Authorization: Bearer {token}\"",
        "in": "header",
        "name": "Authorization",
        "type": "apiKey"
      }
    }
  },
  "info": {
    "contact": {
      "email": "support@essence.digital",
      "name": "Essence Platform",
      "url": "https://essence.digital"
    },
    "description": "API key management service for the Essence API Platform (EPIC 8)",
    "title": "Essence API Key Management",
    "version": "v1"
  },
  "openapi": "3.0.1",
  "paths": {
    "/api/v1/api-keys": {
      "get": {
        "parameters": [
          {
            "in": "query",
            "name": "pageNumber",
            "schema": {
              "default": 1,
              "format": "int32",
              "type": "integer"
            }
          },
          {
            "in": "query",
            "name": "pageSize",
            "schema": {
              "default": 20,
              "format": "int32",
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyDtoPaginatedResponse"
                }
              }
            },
            "description": "Success"
          }
        },
        "summary": "Gets all API keys for the authenticated user",
        "tags": [
          "ApiKeys"
        ]
      },
      "post": {
        "requestBody": {
          "content": {
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/CreateApiKeyRequest"
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateApiKeyRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateApiKeyRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateApiKeyResponse"
                }
              }
            },
            "description": "Created"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Bad Request"
          }
        },
        "summary": "Creates a new API key. The plain key is returned ONCE in the response and cannot be retrieved again.",
        "tags": [
          "ApiKeys"
        ]
      }
    },
    "/api/v1/api-keys/introspect": {
      "post": {
        "description": "For a backend that authenticates a key for itself rather than trusting an identity the\r\nedge forwards (EPIC 51's compliance gate). The edge's `validate` has already metered\r\nthe request; this one must not meter it twice. Restricted to service callers holding\r\n`apikey.introspect`: plain `[Authorize]` would let any signed-in user test key\r\nguesses here without a single request ever being counted against them.",
        "requestBody": {
          "content": {
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/IntrospectApiKeyRequest"
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IntrospectApiKeyRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/IntrospectApiKeyRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyIntrospectionResultDto"
                }
              }
            },
            "description": "Success"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Bad Request"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Forbidden"
          }
        },
        "summary": "Says whether a presented key is live and usable for one scope, and which organisation it\r\nacts for — WITHOUT recording a request against it (#10370).",
        "tags": [
          "ApiKeys"
        ]
      }
    },
    "/api/v1/api-keys/usage": {
      "get": {
        "parameters": [
          {
            "description": "Optional, and must be the caller's own id when supplied. The console passes it\r\nexplicitly; accepting an arbitrary value would turn this into a read of anyone's\r\nconsumption pattern, which reveals their traffic volume and outage windows.",
            "in": "query",
            "name": "developerId",
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountUsageDto"
                }
              }
            },
            "description": "Success"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Forbidden"
          }
        },
        "summary": "Rolls up consumption across every key the calling developer holds.",
        "tags": [
          "ApiKeys"
        ]
      }
    },
    "/api/v1/api-keys/validate": {
      "post": {
        "requestBody": {
          "content": {
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/ValidateApiKeyRequest"
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ValidateApiKeyRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/ValidateApiKeyRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyValidationResultDto"
                }
              }
            },
            "description": "Success"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Bad Request"
          }
        },
        "summary": "Validates an API key (used by the API gateway for key-based authentication).\r\nUses CryptographicOperations.FixedTimeEquals for constant-time comparison (SEC-005).",
        "tags": [
          "ApiKeys"
        ]
      }
    },
    "/api/v1/api-keys/{id}": {
      "delete": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/RevokeApiKeyRequest"
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RevokeApiKeyRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/RevokeApiKeyRequest"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "No Content"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not Found"
          }
        },
        "summary": "Revokes an API key",
        "tags": [
          "ApiKeys"
        ]
      },
      "get": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiKeyDto"
                }
              }
            },
            "description": "Success"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not Found"
          }
        },
        "summary": "Gets an API key by ID",
        "tags": [
          "ApiKeys"
        ]
      }
    },
    "/api/v1/api-keys/{id}/rotate": {
      "post": {
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/RotateApiKeyRequest"
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RotateApiKeyRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/RotateApiKeyRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RotateApiKeyResponse"
                }
              }
            },
            "description": "Success"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not Found"
          }
        },
        "summary": "Rotates an API key (creates a new key with the same properties and revokes the old one —\r\nat once, or after an optional overlap of up to 24 hours during which both validate).\r\nThe new plain key is returned ONCE in the response.",
        "tags": [
          "ApiKeys"
        ]
      }
    },
    "/api/v1/api-keys/{id}/usage": {
      "get": {
        "description": "Answers 404 both when the key does not exist and when it is not the caller's, so\r\nthe response cannot be used to enumerate key ids.",
        "parameters": [
          {
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/KeyUsageDto"
                }
              }
            },
            "description": "Success"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not Found"
          }
        },
        "summary": "Reports one key's consumption against its quota (FR-25.009.5): requests today, the\r\nenforced daily ceiling, current burst pressure, whether the key is being throttled\r\nright now and on which dimension, and a seven-day trend.",
        "tags": [
          "ApiKeys"
        ]
      }
    },
    "/api/v1/versions": {
      "get": {
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/ApiVersionDto"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Success"
          }
        },
        "summary": "The publisher version catalogue (FR-08.050).",
        "tags": [
          "ApiVersions"
        ]
      }
    },
    "/api/v1/versions/pending-sunsets": {
      "get": {
        "description": "developerId is accepted for the console's query-string contract but\r\n            is NOT the identity: a developer may only read their own pending sunsets, so a value\r\n            other than the caller's own is refused rather than honoured. Trusting it would turn a\r\n            convenience parameter into a cross-tenant read of another developer's integration\r\n            inventory — which endpoints they call, and on which versions.",
        "parameters": [
          {
            "in": "query",
            "name": "developerId",
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/PendingSunsetDto"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Success"
          },
          "403": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Forbidden"
          }
        },
        "summary": "Pending sunsets affecting a developer's applications (FR-08.039).",
        "tags": [
          "ApiVersions"
        ]
      }
    },
    "/api/v1/versions/{version}/acknowledge": {
      "post": {
        "parameters": [
          {
            "in": "path",
            "name": "version",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/AcknowledgeSunsetRequest"
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AcknowledgeSunsetRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/AcknowledgeSunsetRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PendingSunsetDto"
                }
              }
            },
            "description": "Success"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not Found"
          }
        },
        "summary": "The maintainer acknowledges the sunset notice (FR-08.051).",
        "tags": [
          "ApiVersions"
        ]
      }
    },
    "/api/v1/versions/{version}/consumers/{principalId}/extension": {
      "post": {
        "parameters": [
          {
            "in": "path",
            "name": "version",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "path",
            "name": "principalId",
            "required": true,
            "schema": {
              "format": "uuid",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/GrantExtensionRequest"
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GrantExtensionRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/GrantExtensionRequest"
              }
            }
          }
        },
        "responses": {
          "204": {
            "description": "No Content"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not Found"
          }
        },
        "summary": "Grants one consumer a grace extension past the sunset date.",
        "tags": [
          "ApiVersions"
        ]
      }
    },
    "/api/v1/versions/{version}/deprecate": {
      "post": {
        "parameters": [
          {
            "in": "path",
            "name": "version",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/DeclareDeprecationRequest"
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeclareDeprecationRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/DeclareDeprecationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiVersionDto"
                }
              }
            },
            "description": "Success"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Bad Request"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Conflict"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "The sunset date is inside the 12-month floor (`sunset_floor_violation`)."
          }
        },
        "summary": "Declares a version deprecated (FR-08.050).",
        "tags": [
          "ApiVersions"
        ]
      }
    },
    "/api/v1/versions/{version}/deprecation-report": {
      "get": {
        "parameters": [
          {
            "in": "path",
            "name": "version",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeprecationReportDto"
                }
              }
            },
            "description": "Success"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not Found"
          }
        },
        "summary": "The read-only governance/audit bundle (FR-08.053).",
        "tags": [
          "ApiVersions"
        ]
      }
    },
    "/api/v1/versions/{version}/migration-progress": {
      "get": {
        "parameters": [
          {
            "in": "path",
            "name": "version",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MigrationProgressDto"
                }
              }
            },
            "description": "Success"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not Found"
          }
        },
        "summary": "Per-consumer migration progress (FR-08.051).",
        "tags": [
          "ApiVersions"
        ]
      }
    },
    "/api/v1/versions/{version}/notify": {
      "post": {
        "parameters": [
          {
            "in": "path",
            "name": "version",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/NotifyCampaignRequest"
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/NotifyCampaignRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/NotifyCampaignRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotifyCampaignResponse"
                }
              }
            },
            "description": "Success"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not Found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Conflict"
          }
        },
        "summary": "Sends or re-sends the deprecation notice campaign (FR-08.050 → EPIC 66).",
        "tags": [
          "ApiVersions"
        ]
      }
    },
    "/api/v1/versions/{version}/retire": {
      "post": {
        "parameters": [
          {
            "in": "path",
            "name": "version",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/*+json": {
              "schema": {
                "$ref": "#/components/schemas/RetireVersionRequest"
              }
            },
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RetireVersionRequest"
              }
            },
            "text/json": {
              "schema": {
                "$ref": "#/components/schemas/RetireVersionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RetireVersionResponse"
                }
              }
            },
            "description": "Success"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not Found"
          },
          "409": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Live traffic or unacknowledged consumers remain (`version_still_in_use`)."
          }
        },
        "summary": "Retires a version, subject to the zero-traffic gate (FR-08.052).",
        "tags": [
          "ApiVersions"
        ]
      }
    }
  },
  "security": [
    {
      "Bearer": []
    }
  ]
}