list_tokens #

View this page as Markdown

On this page

Generated automatically from the published contract sources.

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

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 #

List your account's API tokens and, where your credential permits, its sign-in connections. Tokens include their id, scope, grants, label, creation, expiry, revocation and last-use times, never their values. authorized_computer: true marks a token the turnzero command keeps on a computer it authorized. Its label defaults to that computer's host name. Connections include their id, client, address, sign-in time, last renewal, and expiry, never a token. A token limited by a narrow grant gets its tokens alone. To end a token or connection, use revoke_token with id or connection respectively.

More about this action #

List your account's connections: each connection's id, client, address, sign-in time, last renewal, and expiry, never a token.

Access and action metadata #

{
  "name": "list_tokens",
  "resource": "token",
  "tier": "observe",
  "surface": "account",
  "addresses": [
    "tzcloud"
  ],
  "clients": [
    "bearer",
    "browser_session"
  ],
  "admits": [
    "synthetic_estate",
    "issues",
    "tzmesh",
    "tztrack"
  ],
  "summary": "The account's minted tokens: identities, scopes, grants, labels, stamps, and a space grant's space and level, and `authorized_computer`, true on an authorized computer's token, never values. If no narrow grant bounds the credential, it also returns the account's live connections. Each row gives the tool's refresh family, client, sign-in, last renewal and expiry, never a token.",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false,
    "idempotentHint": true
  }
}

MCP catalog entry #

{
  "name": "list_tokens",
  "title": "List access tokens",
  "tier": "observe",
  "summary": "List your account's API tokens and, where your credential permits, its sign-in connections. Tokens include their id, scope, grants, label, creation, expiry, revocation and last-use times, never their values. `authorized_computer: true` marks a token the turnzero command keeps on a computer it authorized. Its label defaults to that computer's host name. Connections include their id, client, address, sign-in time, last renewal, and expiry, never a token. A token limited by a narrow grant gets its tokens alone. To end a token or connection, use `revoke_token` with `id` or `connection` respectively.",
  "owners": [
    "API-L0-05",
    "MAPI-14",
    "API-L0-21",
    "ACS-L0-11",
    "MCP-10"
  ],
  "scenario": "API-L0-05"
}

request #

JSON pointer Description and constraints
"" (root) Type: object

response #

JSON pointer Description and constraints
"" (root) Type: object
Required fields: ["contract_version","tokens"]
Additional properties: false
/properties/contract_version Required value: 1
/properties/tokens Type: array
/properties/tokens/items Type: object
Required fields: ["id","scope_kind","application","grants","label","created_at","expires_at","revoked_at","last_used_at"]
Additional properties: false
/properties/tokens/items/properties/id Type: string
/properties/tokens/items/properties/scope_kind Allowed values: ["account","application"]
/properties/tokens/items/properties/application Type: ["string","null"]
/properties/tokens/items/properties/grants Type: array
/properties/tokens/items/properties/grants/items Allowed values: ["destructive","super_admin","synthetic_seed_purge","synthetic_estate","publication","feedback_queue","issues","tzmesh","tztrack","test_end_users","support_read"]
/properties/tokens/items/properties/label Type: ["string","null"]
/properties/tokens/items/properties/authorized_computer Whether the token is an authorized computer's: true on a token the turnzero command keeps on a computer it authorized, false on every other.

Type: boolean
/properties/tokens/items/properties/space The space the issues grant applies to; you get it only on a token that holds the grant.

Type: string
Pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
/properties/tokens/items/properties/level The level the issues grant reaches its space at, report, contribute, or owner, or a tzmesh or tztrack token's level, read, chat, or admin, a mark that bounds no call of its product. You get it only on a token that holds one of the three grants.

Allowed values: ["report","contribute","owner","read","chat","admin"]
/properties/tokens/items/properties/created_at Type: string
/properties/tokens/items/properties/expires_at Type: ["string","null"]
/properties/tokens/items/properties/revoked_at Type: ["string","null"]
/properties/tokens/items/properties/last_used_at Type: ["string","null"]
/properties/tokens/items/properties/last_used_note On a product token alone, one holding the tzmesh or tztrack grant: a sentence saying the last-use time counts only requests made to this platform. The product's own service checks the token without asking this platform, so its uses there are not recorded and a null time does not mean the token is unused.

Type: string
/properties/connections Your account's connections, each its id, client, address, sign-in time, last renewal, and expiry, never a token. Absent under a token a narrow grant bounds.

Type: array
/properties/connections/items Type: object
Required fields: ["id","client_id","client_name","client_host","signed_in_at","renewed_at","expires_at","address"]
Additional properties: false
/properties/connections/items/properties/id The connection's identity: its refresh family, which you pass to revoke_token with connection.

Type: string
/properties/connections/items/properties/client_id The registered client the connection was issued to.

Type: string
/properties/connections/items/properties/client_name The name the client's tool registered, or null where it registered none.

Type: ["string","null"]
/properties/connections/items/properties/client_host The host of the address the client's tool registered, or null where it registered none.

Type: ["string","null"]
/properties/connections/items/properties/signed_in_at The instant of the sign-in that opened the connection.

Type: string
/properties/connections/items/properties/renewed_at The instant of the last renewal, or null where none was made.

Type: ["string","null"]
/properties/connections/items/properties/expires_at When the connection's newest refresh credential expires.

Type: string
/properties/connections/items/properties/address The address the connection was made at: turnzero for turnzero.ai/mcp, tzcloud, or tztools. tzop is the address Turn Zero's own operators use; no customer account shows it.

Type: string
Allowed values: ["turnzero","tzcloud","tztools","tzop"]

Complete payload contract #

{
  "request": {
    "type": "object",
    "properties": {}
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "tokens"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "tokens": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "id",
            "scope_kind",
            "application",
            "grants",
            "label",
            "created_at",
            "expires_at",
            "revoked_at",
            "last_used_at"
          ],
          "properties": {
            "id": {
              "type": "string"
            },
            "scope_kind": {
              "enum": [
                "account",
                "application"
              ]
            },
            "application": {
              "type": [
                "string",
                "null"
              ]
            },
            "grants": {
              "type": "array",
              "items": {
                "enum": [
                  "destructive",
                  "super_admin",
                  "synthetic_seed_purge",
                  "synthetic_estate",
                  "publication",
                  "feedback_queue",
                  "issues",
                  "tzmesh",
                  "tztrack",
                  "test_end_users",
                  "support_read"
                ]
              }
            },
            "label": {
              "type": [
                "string",
                "null"
              ]
            },
            "authorized_computer": {
              "type": "boolean",
              "description": "Whether the token is an authorized computer's: true on a token the turnzero command keeps on a computer it authorized, false on every other."
            },
            "space": {
              "type": "string",
              "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$",
              "description": "The space the issues grant applies to; you get it only on a token that holds the grant."
            },
            "level": {
              "enum": [
                "report",
                "contribute",
                "owner",
                "read",
                "chat",
                "admin"
              ],
              "description": "The level the issues grant reaches its space at, report, contribute, or owner, or a `tzmesh` or `tztrack` token's level, read, chat, or admin, a mark that bounds no call of its product. You get it only on a token that holds one of the three grants."
            },
            "created_at": {
              "type": "string"
            },
            "expires_at": {
              "type": [
                "string",
                "null"
              ]
            },
            "revoked_at": {
              "type": [
                "string",
                "null"
              ]
            },
            "last_used_at": {
              "type": [
                "string",
                "null"
              ]
            },
            "last_used_note": {
              "type": "string",
              "description": "On a product token alone, one holding the `tzmesh` or `tztrack` grant: a sentence saying the last-use time counts only requests made to this platform. The product's own service checks the token without asking this platform, so its uses there are not recorded and a null time does not mean the token is unused."
            }
          },
          "additionalProperties": false
        }
      },
      "connections": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "id",
            "client_id",
            "client_name",
            "client_host",
            "signed_in_at",
            "renewed_at",
            "expires_at",
            "address"
          ],
          "properties": {
            "id": {
              "type": "string",
              "description": "The connection's identity: its refresh family, which you pass to `revoke_token` with `connection`."
            },
            "client_id": {
              "type": "string",
              "description": "The registered client the connection was issued to."
            },
            "client_name": {
              "type": [
                "string",
                "null"
              ],
              "description": "The name the client's tool registered, or null where it registered none."
            },
            "client_host": {
              "type": [
                "string",
                "null"
              ],
              "description": "The host of the address the client's tool registered, or null where it registered none."
            },
            "signed_in_at": {
              "type": "string",
              "description": "The instant of the sign-in that opened the connection."
            },
            "renewed_at": {
              "type": [
                "string",
                "null"
              ],
              "description": "The instant of the last renewal, or null where none was made."
            },
            "expires_at": {
              "type": "string",
              "description": "When the connection's newest refresh credential expires."
            },
            "address": {
              "type": "string",
              "enum": [
                "turnzero",
                "tzcloud",
                "tztools",
                "tzop"
              ],
              "description": "The address the connection was made at: `turnzero` for turnzero.ai/mcp, `tzcloud`, or `tztools`. `tzop` is the address Turn Zero's own operators use; no customer account shows it."
            }
          },
          "additionalProperties": false
        },
        "description": "Your account's connections, each its id, client, address, sign-in time, last renewal, and expiry, never a token. Absent under a token a narrow grant bounds."
      }
    },
    "additionalProperties": false
  }
}

Shared contracts #