---
title: "list_invitations"
description: "Generated reference for the management action list_invitations: its description, access metadata, payload contract, and registration status."
slug: /reference/actions/list-invitations
order: 68
visibility: public
redirects_from: []
---

# list\_invitations

Generated automatically from the [published contract sources](/cloud/reference/about/#contract-sources).

A script calls this action over HTTPS at `POST https://tzcloud.turnzero.ai/v1/list_invitations`, with a bearer credential and the action's payload as the JSON body. It also accepts `GET`. An MCP connection lists this action as the tool `tzcloud_list_invitations`.

OAuth access tokens and minted tokens, including the turnzero command's computer token, are bearer credentials. The action determines which kinds, scopes and grants it accepts ([Sign-in, sessions, and tokens](/cloud/concepts/sign-in-sessions-and-tokens/)).

**Build metadata:** Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.

## Contract description

List an application realm's invitations and their state, paged\. You receive neither a URL nor an invitation token\. Pass `application` from `list_applications`, and `email` to filter one address\. Follow `next_cursor` until null\. An invitation's `id` revokes it through `invite_end_user`'s `invitation`\. Issue a new invitation to replace a lost URL\. Choose the realm with `environment`\. Production is the default, and development must already be on\.

## More about this action

The `email` argument takes one address\. With it, the page lists only the invitations issued to that address, in issue order, under the same paging\. The address is matched as redemption matches it: case\-insensitively and trimmed\. A cursor is valid only within the filter that returned it\. A cursor that points to an invitation the filter excludes is refused `invalid_request`\.

Without `application`, the call reads the operator's builder invitations, admitted only under `super_admin`\. Other credentials are refused `grant_required`; an application\-bounded token is refused `token_scope_refused`\. Those entries also carry `products`, the profiles redemption adds\. For an application's invitations, pass its id\.

## Access and action metadata

```json
{
  "name": "list_invitations",
  "resource": "realm",
  "tier": "observe",
  "surface": "tzcloud",
  "addresses": [
    "tzcloud"
  ],
  "product": "cloud",
  "summary": "Each invitation of a realm, paged in issue order, never a URL or its token. Each row holds the identifier `invite_end_user` returned at the issue, the address, and the issue, expiry, redemption, and revocation stamps. It also holds the user a redemption created or the existing account that redeemed it, and the state those decide. With no application member it lists the builder realm's, admitted to super_admin alone, each row then carrying `products`, the profiles its redemption adds.",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false,
    "idempotentHint": true
  }
}
```

## MCP catalog entry

```json
{
  "name": "list_invitations",
  "title": "List invitations",
  "tier": "observe",
  "summary": "List an application realm's invitations and their state, paged. You receive neither a URL nor an invitation token. Pass `application` from `list_applications`, and `email` to filter one address. Follow `next_cursor` until null. An invitation's `id` revokes it through `invite_end_user`'s `invitation`. Issue a new invitation to replace a lost URL. Choose the realm with `environment`. Production is the default, and development must already be on.",
  "owners": [
    "ACS-L0-01",
    "ACS-L0-08",
    "ACC-L0-23",
    "PLD-L0-40"
  ],
  "scenario": "ACS-L0-08"
}
```

## request

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Additional properties: false |
| /<wbr>properties/<wbr>application | The application id from `list_applications`, for its realm's invitations\. Omitted, reads the operator's builder realm under `super_admin` alone\.<br><br>Type: string |
| /<wbr>properties/<wbr>email | Optional\. One address; with it, the page holds the invitations issued to that address alone, case\-insensitive and trimmed, in issue order\. A cursor pointing to a row the filter excludes refuses `invalid_request`\. Absent, every invitation of the realm\.<br><br>Type: string<br>Minimum length: 1 |
| /<wbr>properties/<wbr>cursor | The next\_cursor a previous page returned\.<br><br>Type: string |
| /<wbr>properties/<wbr>limit | Invitations per page, 1 to 200; 50 where none is given\.<br><br>Type: integer<br>Minimum: 1<br>Maximum: 200 |
| /<wbr>properties/<wbr>environment | Optional\. The environment whose realm you address, `development` or `production`; absent, `production`\. Ignored when `application` is absent, because the platform's builder realm has no environment\.<br><br>Type: string<br>Pattern: ^\(development\|production\)$ |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version","invitations","next\_cursor"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>contract\_version | Required value: 1 |
| /<wbr>properties/<wbr>invitations | Type: array |
| /<wbr>properties/<wbr>invitations/<wbr>items | Type: object<br>Required fields: \["id","email","created\_at","expires\_at","redeemed\_at","redeemed\_by","revoked\_at","state"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>invitations/<wbr>items/<wbr>properties/<wbr>id | The identifier `invite_end_user` returned at the issue\.<br><br>Type: string |
| /<wbr>properties/<wbr>invitations/<wbr>items/<wbr>properties/<wbr>email | Type: string |
| /<wbr>properties/<wbr>invitations/<wbr>items/<wbr>properties/<wbr>created\_at | Type: string |
| /<wbr>properties/<wbr>invitations/<wbr>items/<wbr>properties/<wbr>expires\_at | Type: string |
| /<wbr>properties/<wbr>invitations/<wbr>items/<wbr>properties/<wbr>redeemed\_at | Type: \["string","null"\] |
| /<wbr>properties/<wbr>invitations/<wbr>items/<wbr>properties/<wbr>redeemed\_by | The end user the redemption created: the identifier list\_end\_users returned while the user existed, which delete\_end\_user may since have removed\. On the platform's builder realm it is the account the redemption created, or the existing account whose sign\-in redeemed it for a product it lacked\. Null until redeemed\.<br><br>Type: \["string","null"\] |
| /<wbr>properties/<wbr>invitations/<wbr>items/<wbr>properties/<wbr>revoked\_at | Type: \["string","null"\] |
| /<wbr>properties/<wbr>invitations/<wbr>items/<wbr>properties/<wbr>state | What the stamps and the clock decide: revoked where revoked\_at is set, redeemed where redeemed\_at is set, expired where expires\_at has passed on a row neither redeemed nor revoked, standing otherwise\.<br><br>Allowed values: \["standing","redeemed","revoked","expired"\] |
| /<wbr>properties/<wbr>invitations/<wbr>items/<wbr>properties/<wbr>products | Only the rows of the platform's builder realm, the form with no `application`: the products the invitation's redemption grants, `["tzcloud"]` on an invitation that listed none\. An application's rows have no such member, because an end user holds no product profile\.<br><br>Type: array |
| /<wbr>properties/<wbr>invitations/<wbr>items/<wbr>properties/<wbr>products/<wbr>items | Type: string |
| /<wbr>properties/<wbr>next\_cursor | Type: \["string","null"\] |
| /<wbr>properties/<wbr>detail | Type: string |

## Complete payload contract

```json
{
  "request": {
    "type": "object",
    "properties": {
      "application": {
        "type": "string",
        "description": "The application id from `list_applications`, for its realm's invitations. Omitted, reads the operator's builder realm under `super_admin` alone."
      },
      "email": {
        "type": "string",
        "minLength": 1,
        "description": "Optional. One address; with it, the page holds the invitations issued to that address alone, case-insensitive and trimmed, in issue order. A cursor pointing to a row the filter excludes refuses `invalid_request`. Absent, every invitation of the realm."
      },
      "cursor": {
        "type": "string",
        "description": "The next_cursor a previous page returned."
      },
      "limit": {
        "type": "integer",
        "minimum": 1,
        "maximum": 200,
        "description": "Invitations per page, 1 to 200; 50 where none is given."
      },
      "environment": {
        "type": "string",
        "pattern": "^(development|production)$",
        "description": "Optional. The environment whose realm you address, `development` or `production`; absent, `production`. Ignored when `application` is absent, because the platform's builder realm has no environment."
      }
    },
    "additionalProperties": false
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "invitations",
      "next_cursor"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "invitations": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "id",
            "email",
            "created_at",
            "expires_at",
            "redeemed_at",
            "redeemed_by",
            "revoked_at",
            "state"
          ],
          "properties": {
            "id": {
              "type": "string",
              "description": "The identifier `invite_end_user` returned at the issue."
            },
            "email": {
              "type": "string"
            },
            "created_at": {
              "type": "string"
            },
            "expires_at": {
              "type": "string"
            },
            "redeemed_at": {
              "type": [
                "string",
                "null"
              ]
            },
            "redeemed_by": {
              "type": [
                "string",
                "null"
              ],
              "description": "The end user the redemption created: the identifier list_end_users returned while the user existed, which delete_end_user may since have removed. On the platform's builder realm it is the account the redemption created, or the existing account whose sign-in redeemed it for a product it lacked (ACB-L0-77). Null until redeemed."
            },
            "revoked_at": {
              "type": [
                "string",
                "null"
              ]
            },
            "state": {
              "enum": [
                "standing",
                "redeemed",
                "revoked",
                "expired"
              ],
              "description": "What the stamps and the clock decide: revoked where revoked_at is set, redeemed where redeemed_at is set, expired where expires_at has passed on a row neither redeemed nor revoked, standing otherwise (ACS-L0-08)."
            },
            "products": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Only the rows of the platform's builder realm, the form with no `application`: the products the invitation's redemption grants, `[\"tzcloud\"]` on an invitation that listed none (ACB-L0-77). An application's rows have no such member, because an end user holds no product profile."
            }
          },
          "additionalProperties": false
        }
      },
      "next_cursor": {
        "type": [
          "string",
          "null"
        ]
      },
      "detail": {
        "type": "string"
      }
    },
    "additionalProperties": false
  }
}
```

## Shared contracts

- [Refusals](/cloud/reference/refusals/): every refusal, by surface, with its cause and its remedy
- [schemas/wire\_error\.schema\.json](/cloud/reference/sources/schemas/wire-error-schema/)
- [schemas/wire\_errors\.json](/cloud/reference/sources/schemas/wire-errors/)
- [schemas/action\_payloads\.json](/cloud/reference/sources/schemas/action-payloads/) (includes shared shapes)
- [management\_api\_contract\.md](/cloud/reference/sources/management-api-contract/)
