list_subscription_grants

List the access grants a subscription holds — one per resource and dated window, with the connector, how access was given, where it stands and why it failed if it did.

Purpose

Read the access ledger for one purchase: every grant the subscription holds, one per resource (and per dated window for a pass), with the connector that gave it, the mode (an invite link, a membership, a role, a task for the creator), the state (pending_identity, pending, held, granted, revoked, failed) and, for a failure, the classified reason and the sentence a creator reads. Use it to answer "does this member actually have access to the channel?" instead of inferring it from the subscription's payment status.

Required ability

project-subscription:view

Input schema

{
  "type": "object",
  "required": ["subscription_id"],
  "properties": {
    "subscription_id": {
      "type": "string",
      "description": "UUID of the subscription whose grants to list."
    }
  }
}

Output shape

{
  "data": [
    {
      "id": "7d1c3e9a-2b64-4f0e-9a58-3c6b1d8e2f47",
      "subscription_id": "5b7e2d40-1a86-4c39-97f2-e83d0b16c5a4",
      "resource_id": "c9e21f37-8a4b-4d56-b1e0-2f7c9d3a6e15",
      "window_id": null,
      "identity_id": "0c2d8a7e-4b1f-4d3e-9a6b-2f5e8c1d7a90",
      "connector": "telegram",
      "mode": "bearer_link",
      "state": "granted",
      "reference": "https://t.me/+AbCdEfGhIjKlMnOp",
      "granted_at": "2026-09-12T10:05:00+00:00",
      "revoked_at": null,
      "failure_kind": null,
      "failure_detail": null,
      "created_at": "2026-09-12T10:04:58+00:00"
    }
  ]
}

mode is one of bearer_link (a personal invite link the member comes through), membership (the connector added the member), role (a role was assigned) or creator_task (the creator has to do something by hand). reference is the connector's handle on the grant — the invite link on Telegram — and is null before anything was issued. A failed grant carries failure_kind (unreachable, not_permitted, target_missing, rate_limited, configuration, transient, other) and failure_detail.

Example prompts

"Does subscription 5b7e2d40-… actually have access to every channel in its plan?"

"Which of this member's grants failed, and why?"

Failure modes

RESOURCE_NOT_FOUND — subscription_id is not a valid UUID, or the subscription belongs to another team or a project outside the token's scope.
AUTHENTICATION_REQUIRED — no authenticated user on the request.
TOKEN_MISSING_ABILITY — token lacks project-subscription:view.

get_subscription — embeds the same rows as grants.
Subscriptions API