List Agent Key Metadata (Admin)

{
  "operationId": "getAdminsAgentSignupMetadata",
  "summary": "List agent-prefixed API-key metadata (Admin)",
  "description": "Read API-key record metadata associated with current account emails matching the case-insensitive agent+ prefix. Authenticate with exactly one x-api-key or Authorization: Bearer credential for a Recoup admin account. Admin access is checked before query validation or metadata access.\n\nEach returned record contains only id, name, email and created_at. id identifies an API-key record, not an account or credential; no API key value or hash is selected or returned. email is the first matching current associated email, not necessarily a primary or canonical address. Multiple matching emails do not multiply a key record; multiple keys on one account remain separate records. Deleted keys are absent; expired key records are not excluded. Current email associations can change. This is a current-email metadata selection, not evidence of origin from POST /api/agents/signup, a unique-agent/account count, active-key count, usage or adoption.\n\nperiod defaults to all. Other values use inclusive midnight-UTC calendar boundaries on API-key record created_at: daily is today; weekly includes today and the preceding six calendar days; monthly includes today and the preceding 29 calendar days. Rows are ordered by key-record created_at descending. total is the length of the returned signups array, not a separate database-wide count. Existing database visibility and server row limits apply; no pagination or collection-completeness guarantee is provided. A successful empty read returns total 0 and signups []; a read failure returns a masked 500 instead.\n\nThis is GET /api/admins/agent-signups. The former GET /api/admins/agent/signups remains unavailable. The broader reporting decision in Mono #327 and original API #428 are not closed by this metadata route. Source tests use synthetic credential and storage boundaries; they do not prove production admin access, real data completeness or customer adoption. No UI, automatic caller, polling job, export or account/key creation is added.",
  "parameters": [
    {
      "name": "period",
      "in": "query",
      "required": false,
      "description": "Optional key-record creation window, inclusive from 00:00 UTC: daily = today; weekly = 7 calendar days including today; monthly = 30 calendar days including today; all = no cutoff. Defaults to all when omitted; an explicit empty or unsupported value returns 400. This is not a rolling 24-hour window and does not filter by account or email creation time.",
      "schema": {
        "type": "string",
        "enum": [
          "all",
          "daily",
          "weekly",
          "monthly"
        ],
        "default": "all"
      },
      "example": "all"
    }
  ],
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "responses": {
    "200": {
      "description": "Returned API-key metadata and the count of these returned records.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AdminAgentKeyMetadataResponse"
          },
          "examples": {
            "multipleKeys": {
              "summary": "Synthetic example: two key records share one current matching email; total is not unique accounts.",
              "value": {
                "status": "success",
                "total": 2,
                "signups": [
                  {
                    "id": "11111111-1111-4111-8111-111111111112",
                    "name": "Second agent key",
                    "email": "agent+fixture@example.invalid",
                    "created_at": "2026-10-21T12:00:00Z"
                  },
                  {
                    "id": "11111111-1111-4111-8111-111111111111",
                    "name": "First agent key",
                    "email": "agent+fixture@example.invalid",
                    "created_at": "2026-10-20T12:00:00Z"
                  }
                ]
              }
            },
            "noRecords": {
              "summary": "Successful empty metadata read, subject to existing visibility and collection limits.",
              "value": {
                "status": "success",
                "total": 0,
                "signups": []
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid or explicitly empty period, after successful admin authentication.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ErrorEnvelope"
          }
        }
      }
    },
    "401": {
      "description": "Missing, simultaneous or invalid credentials; inspect error or message according to the authentication envelope.",
      "content": {
        "application/json": {
          "schema": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/ErrorEnvelope"
              },
              {
                "$ref": "#/components/schemas/AccountErrorResponse"
              }
            ]
          }
        }
      }
    },
    "403": {
      "description": "The authenticated account is not a Recoup admin.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountErrorResponse"
          }
        }
      }
    },
    "500": {
      "description": "Metadata read or handler failure. Generic Internal server error message; not an empty success report.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/AccountErrorResponse"
          }
        }
      }
    }
  }
}