read_account #
On this page
Generated automatically from the published 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).
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 #
{
"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 #
{
"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 Additional properties: false |
response #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["contract_version","account"] |
| / |
Required value: 1 |
| / |
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. Type: string Pattern: ^[0-9a-f]{10}$ |
| / |
Over MCP alone: one sentence saying what tzteam is. Absent on the HTTP route.Type: string |
| / |
Type: object Required fields: ["id","created_at","standing","identities","synthetic","unbilled"] |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string |
| / |
Type: array |
| / |
Type: object Required fields: ["provider","subject"] |
| / |
Type: string |
| / |
Type: string |
| / |
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.Type: array |
| / |
Type: object Required fields: ["product"] Additional properties: false |
| / |
Type: string |
| / |
True if this account holds at least one application, excluding deleted applications; false otherwise. Omitted if that read fails. Type: boolean |
| / |
Over MCP alone: one item for each product your account can see, held saying whether your account holds it. Absent on the HTTP route.Type: array |
| / |
Type: object Required fields: ["product","held"] Additional properties: false |
| / |
Type: string |
| / |
Type: boolean |
| / |
true on a synthetic account, a test fixture that billing and product analytics do not count; false on every other account. Type: boolean |
| / |
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. Type: boolean |
| / |
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. Type: ["string","null"] |
| / |
The acting credential's grant markings, super_admin. They are returned to the session kinds alone.Type: array |
| / |
Type: string |
| / |
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. Type: ["string","null"] |
| / |
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. Type: ["object","null"] Required fields: ["held","stranded"] Additional properties: false |
| / |
How many of the account's passkeys sign in on this host: the ones registered under the current relying-party identifier. Type: integer Minimum: 0 |
| / |
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. Type: integer Minimum: 0 |
| / |
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. Type: boolean |
| / |
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.Type: boolean |
| / |
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.Type: object Required fields: ["used","resets_at"] |
| / |
The account's images counted this UTC month: delivered images and calls whose give-back failed. Type: integer |
| / |
The account's images per UTC month, returned where pricing reads plans.Type: integer |
| / |
The first instant of the next UTC month, as an ISO 8601 instant. Type: string |
| / |
The account's free images per UTC month, returned where pricing reads usage.Type: integer |
Complete payload contract #
{
"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: every refusal, by surface, with its cause and its remedy
- schemas/wire_error.schema.json
- schemas/wire_errors.json
- schemas/action_payloads.json (includes shared shapes)
- management_api_contract.md