list_access_codes

Paginated list of access codes for a plan, with first/last-4 masked prefixes only — full codes are never surfaced.

Purpose

List access codes for a plan. Requires plan_id, accepts an optional status filter (unredeemed, redeemed, expired, or all). Results are scoped to the caller's team.

Codes are returned with a masked prefix (first 4 + asterisks + last 4). The plaintext value is delivered to the creator's Telegram chat by bulk_generate_access_codes — the MCP layer is read-only on the secret itself.

Required ability

project-access-code:view-any

Input schema

{
  "type": "object",
  "required": ["plan_id"],
  "properties": {
    "plan_id": {
      "type": "string",
      "description": "UUID of the plan to list codes for."
    },
    "status": {
      "type": "string",
      "description": "Filter by code state. One of: unredeemed, redeemed, expired, all."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "Maximum codes to return per page (1..100)."
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "description": "1-indexed page number."
    }
  }
}

Output shape

{
  "data": [
    {
      "id": "sub_01HX...",
      "plan_id": "pln_01HX...",
      "code_masked": "A3F1****7Z9P",
      "redeemed_at": null,
      "expires_at": "2026-08-01T00:00:00Z",
      "redeemed_by": null,
      "created_at": "2026-05-18T10:05:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 25,
    "total": 47,
    "has_more": true,
    "status": "unredeemed"
  }
}

Example prompts

"How many access codes are still unredeemed on plan pln_01HX...?"

"List expired access codes for the Premium plan."

Failure modes

TOKEN_MISSING_ABILITY — token lacks project-access-code:view-any.