---
title: "read_account"
description: "Generated reference for the management action read_account: its description, access metadata, payload contract, and registration status."
slug: /reference/actions/read-account
order: 2
visibility: public
redirects_from: []
---

# read\_account

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

A script calls this action over HTTPS at `POST https://turnzero.ai/api/v1/read_account`, 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 `read_account`.

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

Read the account your connection represents: its sign\-in identities \(provider and verified subject\), standing \(`active` or `suspended`\), and products\.

A session credential also gets the provider\-verified `address`, its `grants`, `signed_in_at`, and `passkeys`\. The sign\-in time is null for a bearer at this revision\. The passkey counts give `held` for passkeys that sign in on this host, and `stranded` for those registered for another host\. The `passkeys` member is null where this host offers no passkey sign\-in\. An authorized computer's token gets `address` alone\. The platform credential and every other minted token get none of the four\.

With your own sign\-in, `image_generation` gives the month's image use\.

## More about this action

Over MCP, `product_states` says whether your account holds each product, and `detail` says what `tzteam` is\.

A session credential, a browser session or an authorized computer's token also gets `image_generation`: the month's `used` and `resets_at`, with `cap` under `plans` or `free_images` under `usage`\. Other minted tokens and the platform credential receive no such member\. If its usage row cannot be read, the member is omitted\.

## Access and action metadata

```json
{
  "name": "read_account",
  "resource": "account",
  "tier": "observe",
  "surface": "account",
  "addresses": [
    "tzcloud",
    "tztools"
  ],
  "admits": [
    "device_sign_in"
  ],
  "clients": [
    "bearer",
    "browser_session"
  ],
  "summary": "The connected identity and its standing. For the session credential and the browser session it also returns the provider-verified address (`address`, null where none is held), the acting credential's grants (`grants`), and the sign-in instant the credential carries (`signed_in_at`: the API cookie's own for a browser session, null for a bearer at this revision), so a page can render a sign-in link in place of each control once the freshness window has passed, and the account's passkey standing (`passkeys`: the counts `held` and `stranded` and nothing of a credential, null where no passkey ceremony is served); an authorized computer's token receives `address` alone, and the platform credential and every other minted token receive none of the four.\n\nA session credential, a browser session or an authorized computer's token also gets `image_generation`: the month's `used` and `resets_at`, with `cap` under `plans` or `free_images` under `usage`. Other minted tokens and the platform credential receive no such member. If its usage row cannot be read, the member is omitted.",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false,
    "idempotentHint": true
  }
}
```

## MCP catalog entry

```json
{
  "name": "read_account",
  "title": "Read account",
  "tier": "observe",
  "scenario": "CHI-L0-04",
  "summary": "Read the account your connection represents: its sign-in identities (provider and verified subject), standing (`active` or `suspended`), and products.\n\nA session credential also gets the provider-verified `address`, its `grants`, `signed_in_at`, and `passkeys`. The sign-in time is null for a bearer at this revision. The passkey counts give `held` for passkeys that sign in on this host, and `stranded` for those registered for another host. The `passkeys` member is null where this host offers no passkey sign-in. An authorized computer's token gets `address` alone. The platform credential and every other minted token get none of the four.\n\nWith your own sign-in, `image_generation` gives the month's image use.",
  "owners": [
    "MAPI-03",
    "WEB-L0-16",
    "ACB-L0-92",
    "ACB-L0-76"
  ]
}
```

## request

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Additional properties: false |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version","account"\] |
| /<wbr>properties/<wbr>contract\_version | Required value: 1 |
| /<wbr>properties/<wbr>reference | The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row\. Quote it when you report the call\.<br><br>Type: string<br>Pattern: ^\[0\-9a\-f\]\{10\}$ |
| /<wbr>properties/<wbr>detail | Over MCP alone: one sentence saying what `tzteam` is\. Absent on the HTTP route\.<br><br>Type: string |
| /<wbr>properties/<wbr>account | Type: object<br>Required fields: \["id","created\_at","standing","identities","synthetic","unbilled"\] |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>id | Type: string |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>created\_at | Type: string |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>standing | Type: string |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>identities | Type: array |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>identities/<wbr>items | Type: object<br>Required fields: \["provider","subject"\] |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>identities/<wbr>items/<wbr>properties/<wbr>provider | Type: string |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>identities/<wbr>items/<wbr>properties/<wbr>subject | Type: string |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>profiles | The products your account holds under the product rule, one item per product, each by its product word, `tzcloud` for tzCloud\. Every account holds `tzcloud` and `tztrack`\. Your account holds each invite\-only product where it is a member of the invite group or an operator account, or once the product is no longer invite\-only\. `tzteam` is tzTeam access, always on and managed by tzTeam, with no tools on the MCP server\.<br><br>Type: array |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>profiles/<wbr>items | Type: object<br>Required fields: \["product"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>profiles/<wbr>items/<wbr>properties/<wbr>product | Type: string |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>uses\_tzcloud | True if this account holds at least one application, excluding deleted applications; false otherwise\. Omitted if that read fails\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>product\_states | Over MCP alone: one item for each product your account can see, `held` saying whether your account holds it\. Absent on the HTTP route\.<br><br>Type: array |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>product\_states/<wbr>items | Type: object<br>Required fields: \["product","held"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>product\_states/<wbr>items/<wbr>properties/<wbr>product | Type: string |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>product\_states/<wbr>items/<wbr>properties/<wbr>held | Type: boolean |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>synthetic | true on a synthetic account, a test fixture that billing and product analytics do not count; false on every other account\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>unbilled | true on an account a super\-admin has marked unbilled, the company's own or a complimentary one, free of the per\-account application limits and never charged; false on every other account\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>address | The provider\-verified address an identity of the account carries, or null; returned to the session credential, the browser session, and an authorized computer's token alone\.<br><br>Type: \["string","null"\] |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>grants | The acting credential's grant markings, `super_admin`\. They are returned to the session kinds alone\.<br><br>Type: array |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>grants/<wbr>items | Type: string |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>signed\_in\_at | The sign\-in instant the credential carries, ISO 8601: the API cookie's own for a browser session, null for a bearer at this revision; returned to the session kinds alone, so a page renders a sign\-in link once the freshness window has passed\.<br><br>Type: \["string","null"\] |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>passkeys | The account's passkey standing: two counts and nothing of a credential — no identifier, name, or date\. A page and a connected tool read whether a passkey is set without the passkey page's fresh\-session read\. It is null where the platform serves no passkey ceremony on this host\. It is returned to the session kinds alone\.<br><br>Type: \["object","null"\]<br>Required fields: \["held","stranded"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>passkeys/<wbr>properties/<wbr>held | How many of the account's passkeys sign in on this host: the ones registered under the current relying\-party identifier\.<br><br>Type: integer<br>Minimum: 0 |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>passkeys/<wbr>properties/<wbr>stranded | How many of the account's passkeys do not sign in on this host: the ones registered for another host, or before the host was recorded; no browser offers them here, and the passkey page removes them\.<br><br>Type: integer<br>Minimum: 0 |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>setup\_mail\_sent | Whether the account's setup email was sent: true once every addressed send of it was accepted by the provider, false otherwise, a claim that sent nothing among it\. Returned to the session kinds alone, so the home's phone card says the setup prompt was emailed only where it was; left out where it could not be read\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>account\_picture\_served | Whether the account picture's acts are served, read at each call\. Always present for a browser session and absent for every other credential\. True only when `account_picture` reads `on`; false for `off`, an absent row, an invalid value, no status record or a failed read\. A hint for the page: each act still checks the setting itself and keeps its own refusals\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>image\_generation | Your account's `generate_image` use this UTC month\. Returned to a signed\-in session and to an authorized computer's token, and absent under every other credential\. Under `usage`, images past `free_images` draw the account's balance\.<br><br>Type: object<br>Required fields: \["used","resets\_at"\] |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>image\_generation/<wbr>properties/<wbr>used | The account's images counted this UTC month: delivered images and calls whose give\-back failed\.<br><br>Type: integer |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>image\_generation/<wbr>properties/<wbr>cap | The account's images per UTC month, returned where pricing reads `plans`\.<br><br>Type: integer |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>image\_generation/<wbr>properties/<wbr>resets\_at | The first instant of the next UTC month, as an ISO 8601 instant\.<br><br>Type: string |
| /<wbr>properties/<wbr>account/<wbr>properties/<wbr>image\_generation/<wbr>properties/<wbr>free\_images | The account's free images per UTC month, returned where pricing reads `usage`\.<br><br>Type: integer |

## Complete payload contract

```json
{
  "request": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "account"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "reference": {
        "type": "string",
        "pattern": "^[0-9a-f]{10}$",
        "description": "The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call."
      },
      "detail": {
        "type": "string",
        "description": "Over MCP alone: one sentence saying what `tzteam` is. Absent on the HTTP route."
      },
      "account": {
        "type": "object",
        "required": [
          "id",
          "created_at",
          "standing",
          "identities",
          "synthetic",
          "unbilled"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "created_at": {
            "type": "string"
          },
          "standing": {
            "type": "string"
          },
          "identities": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "provider",
                "subject"
              ],
              "properties": {
                "provider": {
                  "type": "string"
                },
                "subject": {
                  "type": "string"
                }
              }
            }
          },
          "profiles": {
            "type": "array",
            "description": "The products your account holds under the product rule, one item per product, each by its product word, `tzcloud` for tzCloud (ACB-L0-76). Every account holds `tzcloud` and `tztrack`. Your account holds each invite-only product where it is a member of the invite group or an operator account, or once the product is no longer invite-only. `tzteam` is tzTeam access, always on and managed by tzTeam, with no tools on the MCP server.",
            "items": {
              "type": "object",
              "required": [
                "product"
              ],
              "properties": {
                "product": {
                  "type": "string"
                }
              },
              "additionalProperties": false
            }
          },
          "uses_tzcloud": {
            "type": "boolean",
            "description": "True if this account holds at least one application, excluding deleted applications; false otherwise. Omitted if that read fails."
          },
          "product_states": {
            "type": "array",
            "description": "Over MCP alone: one item for each product your account can see, `held` saying whether your account holds it. Absent on the HTTP route.",
            "items": {
              "type": "object",
              "required": [
                "product",
                "held"
              ],
              "properties": {
                "product": {
                  "type": "string"
                },
                "held": {
                  "type": "boolean"
                }
              },
              "additionalProperties": false
            }
          },
          "synthetic": {
            "type": "boolean",
            "description": "true on a synthetic account, a test fixture that billing and product analytics do not count; false on every other account (ACB-L0-79)."
          },
          "unbilled": {
            "type": "boolean",
            "description": "true on an account a super-admin has marked unbilled, the company's own or a complimentary one, free of the per-account application limits and never charged; false on every other account (ACB-L0-84)."
          },
          "address": {
            "type": [
              "string",
              "null"
            ],
            "description": "The provider-verified address an identity of the account carries, or null; returned to the session credential, the browser session, and an authorized computer's token alone (MAPI-03; MAPI-14; WEB-L0-17)."
          },
          "grants": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "The acting credential's grant markings, `super_admin` (MAPI-09). They are returned to the session kinds alone."
          },
          "signed_in_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "The sign-in instant the credential carries, ISO 8601: the API cookie's own for a browser session, null for a bearer at this revision; returned to the session kinds alone, so a page renders a sign-in link once the freshness window has passed (WEB-L0-16)."
          },
          "passkeys": {
            "type": [
              "object",
              "null"
            ],
            "required": [
              "held",
              "stranded"
            ],
            "additionalProperties": false,
            "properties": {
              "held": {
                "type": "integer",
                "minimum": 0,
                "description": "How many of the account's passkeys sign in on this host: the ones registered under the current relying-party identifier."
              },
              "stranded": {
                "type": "integer",
                "minimum": 0,
                "description": "How many of the account's passkeys do not sign in on this host: the ones registered for another host, or before the host was recorded; no browser offers them here, and the passkey page removes them."
              }
            },
            "description": "The account's passkey standing: two counts and nothing of a credential — no identifier, name, or date. A page and a connected tool read whether a passkey is set without the passkey page's fresh-session read. It is null where the platform serves no passkey ceremony on this host. It is returned to the session kinds alone (ACS-L0-10)."
          },
          "setup_mail_sent": {
            "type": "boolean",
            "description": "Whether the account's setup email was sent: true once every addressed send of it was accepted by the provider, false otherwise, a claim that sent nothing among it. Returned to the session kinds alone, so the home's phone card says the setup prompt was emailed only where it was; left out where it could not be read (ACS-L0-23; WEB-L0-17)."
          },
          "account_picture_served": {
            "type": "boolean",
            "description": "Whether the account picture's acts are served, read at each call. Always present for a browser session and absent for every other credential. True only when `account_picture` reads `on`; false for `off`, an absent row, an invalid value, no status record or a failed read. A hint for the page: each act still checks the setting itself and keeps its own refusals (WEB-L0-28)."
          },
          "image_generation": {
            "type": "object",
            "required": [
              "used",
              "resets_at"
            ],
            "properties": {
              "used": {
                "type": "integer",
                "description": "The account's images counted this UTC month: delivered images and calls whose give-back failed."
              },
              "cap": {
                "type": "integer",
                "description": "The account's images per UTC month, returned where pricing reads `plans`."
              },
              "resets_at": {
                "type": "string",
                "description": "The first instant of the next UTC month, as an ISO 8601 instant."
              },
              "free_images": {
                "type": "integer",
                "description": "The account's free images per UTC month, returned where pricing reads `usage`."
              }
            },
            "description": "Your account's `generate_image` use this UTC month. Returned to a signed-in session and to an authorized computer's token, and absent under every other credential. Under `usage`, images past `free_images` draw the account's balance."
          }
        }
      }
    }
  }
}
```

## 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/)
