read_app_sign_in #

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://tzcloud.turnzero.ai/v1/read_app_sign_in, 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_read_app_sign_in.

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 an application's sign-in realm: its configuration (sign-in methods, creation mode, limits, invitation days, session days) and its user and live-session counts. It also lists any secrets the realm refers to, never a value. You also get back the native session cap and the declared native clients, which contain no secret. Each client has versions_seen, the versions its requests stated within the last day. An optional environment (development or production) selects the realm your call reads. Without it, the call selects production. Development's realm exists only once create_environment has turned development on.

More about this action #

The result's callbacks gives the platform's callback addresses on the server you are connected to, for the work-account route and for Sign in with Apple, whether or not either route is configured. Enter callbacks.entra, exactly as returned, as the app registration's web redirect URI, and callbacks.apple as the Services ID's return URL. Both environments use the same addresses, and neither is ever the application's hostname.

Access and action metadata #

{
  "name": "read_app_sign_in",
  "resource": "realm",
  "tier": "observe",
  "surface": "tzcloud",
  "addresses": [
    "tzcloud"
  ],
  "product": "cloud",
  "summary": "A realm's configuration, its declared native clients with the versions each stated within the last day, and its user and session counts with its secret names, never a value.",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false,
    "idempotentHint": true
  }
}

MCP catalog entry #

{
  "name": "read_app_sign_in",
  "title": "Read app sign-in settings",
  "tier": "observe",
  "summary": "Read an application's sign-in realm: its configuration (sign-in methods, creation mode, limits, invitation days, session days) and its user and live-session counts. It also lists any secrets the realm refers to, never a value. You also get back the native session cap and the declared native clients, which contain no secret. Each client has `versions_seen`, the versions its requests stated within the last day. An optional `environment` (`development` or `production`) selects the realm your call reads. Without it, the call selects `production`. Development's realm exists only once `create_environment` has turned development on.",
  "owners": [
    "ACS-L0-01",
    "PLD-L0-40",
    "ACS-L0-09"
  ],
  "scenario": "ACS-L0-07"
}

request #

JSON pointer Description and constraints
"" (root) Type: object
Required fields: ["application"]
Additional properties: false
/properties/application Your account's application id from list_applications, not its name or label.

Type: string
/properties/environment Optional. The environment whose realm you address, development or production; without it, production.

Type: string
Pattern: ^(development|production)$

response #

JSON pointer Description and constraints
"" (root) Type: object
Required fields: ["contract_version","realm"]
Additional properties: false
/properties/contract_version Required value: 1
/properties/realm Type: object
Required fields: ["realm","sign_in_methods","creation","effective_creation","limits","counts","secrets","session_cap_days","clients"]
Additional properties: false
/properties/realm/properties/realm Type: string
/properties/realm/properties/sign_in_methods Type: array
/properties/realm/properties/sign_in_methods/items Allowed values: ["google","github","passkey","email","entra","apple"]
/properties/realm/properties/creation Allowed values: ["open","invited"]
/properties/realm/properties/effective_creation The creation mode the realm enforces: invited under an invited audience, whatever creation holds; creation otherwise.

Allowed values: ["open","invited"]
/properties/realm/properties/limits Type: object
Required fields: ["creation_ceiling","signin_starts_per_hour","code_sends_per_hour"]
Additional properties: false
/properties/realm/properties/limits/properties/creation_ceiling Type: ["integer","null"]
Minimum: 1
/properties/realm/properties/limits/properties/signin_starts_per_hour Type: integer
Minimum: 1
/properties/realm/properties/limits/properties/code_sends_per_hour Emailed sign-in codes sent per address per hour; 5 where none is set.

Type: integer
Minimum: 1
/properties/realm/properties/invitation_days Type: integer
Minimum: 1
/properties/realm/properties/session_days Type: integer
Minimum: 1
Maximum: 30
/properties/realm/properties/counts Type: object
Required fields: ["users","sessions","test_users"]
Additional properties: false
/properties/realm/properties/counts/properties/users Type: integer
/properties/realm/properties/counts/properties/sessions Type: integer
/properties/realm/properties/counts/properties/test_users The realm's unexpired test end users, the rows the expiry pass has not yet removed; counted apart from users, which excludes them.

Type: integer
/properties/realm/properties/secrets Type: array
/properties/realm/properties/secrets/items Type: string
/properties/realm/properties/entra The realm's work-account route (the accounts service's work-account statement): the Entra tenant the issuer is pinned to, the application registration's client id, and the NAME of the client secret in the application's custody scope — never a value.

Type: object
Required fields: ["tenant","client_id","client_secret_name"]
Additional properties: false
/properties/realm/properties/entra/properties/tenant Type: string
/properties/realm/properties/entra/properties/client_id Type: string
/properties/realm/properties/entra/properties/client_secret_name Type: string
/properties/realm/properties/apple The realm's Sign in with Apple route (the accounts service's work-account statement): the Services ID, the team and key identifiers, and the NAME of the signing key in the application's custody scope — never a value.

Type: object
Required fields: ["services_id","team_id","key_id","key_secret_name"]
Additional properties: false
/properties/realm/properties/apple/properties/services_id Type: string
/properties/realm/properties/apple/properties/team_id Type: string
/properties/realm/properties/apple/properties/key_id Type: string
/properties/realm/properties/apple/properties/key_secret_name Type: string
/properties/realm/properties/session_cap_days Type: integer
Minimum: 1
Maximum: 730
/properties/realm/properties/clients The declared native clients, each without any secret: a native client holds none.

Type: array
Maximum items: 10
/properties/realm/properties/clients/items Type: object
Required fields: ["client_id","redirect_uris","versions_seen"]
Additional properties: false
/properties/realm/properties/clients/items/properties/client_id The client's identifier, which it presents at the authorization, token, and revocation endpoints; letters, digits, dots, underscores, colons, and hyphens.

Type: string
/properties/realm/properties/clients/items/properties/redirect_uris The redirect URIs the client presents, each matched exactly, a loopback URI's port excepted: a reverse-domain custom scheme such as com.example.app:/callback, an https URI on one of the application's own hostnames, or a loopback http URI on localhost, [::1], or 127.0.0.0/8. On the production realm an https URI on your application's custom domain is accepted too. Any other form is refused invalid_redirect_uri.

Type: array
Minimum items: 1
Maximum items: 20
/properties/realm/properties/clients/items/properties/redirect_uris/items Type: string
/properties/realm/properties/clients/items/properties/ios Optional. The iOS app's bundle identifier and its ten-character team identifier, for the association files and the native ID-token exchange that later changes serve.

Type: object
Required fields: ["bundle_id","team_id"]
Additional properties: false
/properties/realm/properties/clients/items/properties/ios/properties/bundle_id Type: string
/properties/realm/properties/clients/items/properties/ios/properties/team_id Type: string
/properties/realm/properties/clients/items/properties/android Optional. The Android app's package name and its signing-certificate SHA-256 fingerprints, each 32 upper-case hex pairs separated by colons, for the asset links and the passkey origin that later changes serve.

Type: object
Required fields: ["package","sha256_cert_fingerprints"]
Additional properties: false
/properties/realm/properties/clients/items/properties/android/properties/package Type: string
/properties/realm/properties/clients/items/properties/android/properties/sha256_cert_fingerprints Type: array
Minimum items: 1
Maximum items: 10
/properties/realm/properties/clients/items/properties/android/properties/sha256_cert_fingerprints/items Type: string
/properties/realm/properties/clients/items/properties/google_client_ids Optional. The Google client identifiers a Google ID token issued for this app has as its audience, for the native ID-token exchange a later change serves.

Type: array
Maximum items: 10
/properties/realm/properties/clients/items/properties/google_client_ids/items Type: string
/properties/realm/properties/clients/items/properties/minimum_version Optional. The oldest app version accepted, as major.minor.patch; a request stating a lower version is refused client_upgrade_required.

Type: string
/properties/realm/properties/clients/items/properties/update_url Optional. An https URL where a refused client is sent to update.

Type: string
/properties/realm/properties/clients/items/properties/versions_seen The versions this client's requests stated within the last day, highest first, at most fifty. Read it before you raise minimum_version or promote a version.

Type: array
/properties/realm/properties/clients/items/properties/versions_seen/items Type: object
Required fields: ["version","last_seen"]
Additional properties: false
/properties/realm/properties/clients/items/properties/versions_seen/items/properties/version A version the client stated in its x-turnzero-cloud-client header.

Type: string
/properties/realm/properties/clients/items/properties/versions_seen/items/properties/last_seen When the platform last saw a request stating it, to the minute a router reports.

Type: string
Format: date-time
/properties/callbacks The platform's callback addresses on this estate, returned on an end-user realm alone, whether or not either route is configured. Each is the same for both environments and never your application's hostname. List each exactly as returned.

Type: object
Required fields: ["entra","apple"]
Additional properties: false
/properties/callbacks/properties/entra The work-account route's callback: list it, exactly as returned, as a web redirect URI of your tenant's app registration.

Type: string
/properties/callbacks/properties/apple Sign in with Apple's callback: list it, exactly as returned, as your Services ID's return URL, and its host as your Services ID's domain.

Type: string
/properties/detail Type: string
/properties/page $ref: #/shapes/page

Complete payload contract #

{
  "request": {
    "type": "object",
    "required": [
      "application"
    ],
    "properties": {
      "application": {
        "type": "string",
        "description": "Your account's application `id` from `list_applications`, not its name or label."
      },
      "environment": {
        "type": "string",
        "pattern": "^(development|production)$",
        "description": "Optional. The environment whose realm you address, `development` or `production`; without it, `production`."
      }
    },
    "additionalProperties": false
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "realm"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "realm": {
        "type": "object",
        "required": [
          "realm",
          "sign_in_methods",
          "creation",
          "effective_creation",
          "limits",
          "counts",
          "secrets",
          "session_cap_days",
          "clients"
        ],
        "properties": {
          "realm": {
            "type": "string"
          },
          "sign_in_methods": {
            "type": "array",
            "items": {
              "enum": [
                "google",
                "github",
                "passkey",
                "email",
                "entra",
                "apple"
              ]
            }
          },
          "creation": {
            "enum": [
              "open",
              "invited"
            ]
          },
          "effective_creation": {
            "enum": [
              "open",
              "invited"
            ],
            "description": "The creation mode the realm enforces: `invited` under an invited audience, whatever `creation` holds; `creation` otherwise."
          },
          "limits": {
            "type": "object",
            "required": [
              "creation_ceiling",
              "signin_starts_per_hour",
              "code_sends_per_hour"
            ],
            "properties": {
              "creation_ceiling": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": 1
              },
              "signin_starts_per_hour": {
                "type": "integer",
                "minimum": 1
              },
              "code_sends_per_hour": {
                "type": "integer",
                "minimum": 1,
                "description": "Emailed sign-in codes sent per address per hour; 5 where none is set (ACS-L0-12)."
              }
            },
            "additionalProperties": false
          },
          "invitation_days": {
            "type": "integer",
            "minimum": 1
          },
          "session_days": {
            "type": "integer",
            "minimum": 1,
            "maximum": 30
          },
          "counts": {
            "type": "object",
            "required": [
              "users",
              "sessions",
              "test_users"
            ],
            "properties": {
              "users": {
                "type": "integer"
              },
              "sessions": {
                "type": "integer"
              },
              "test_users": {
                "type": "integer",
                "description": "The realm's unexpired test end users, the rows the expiry pass has not yet removed; counted apart from `users`, which excludes them."
              }
            },
            "additionalProperties": false
          },
          "secrets": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "entra": {
            "type": "object",
            "description": "The realm's work-account route (the accounts service's work-account statement): the Entra tenant the issuer is pinned to, the application registration's client id, and the NAME of the client secret in the application's custody scope — never a value.",
            "required": [
              "tenant",
              "client_id",
              "client_secret_name"
            ],
            "properties": {
              "tenant": {
                "type": "string"
              },
              "client_id": {
                "type": "string"
              },
              "client_secret_name": {
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          "apple": {
            "type": "object",
            "description": "The realm's Sign in with Apple route (the accounts service's work-account statement): the Services ID, the team and key identifiers, and the NAME of the signing key in the application's custody scope — never a value.",
            "required": [
              "services_id",
              "team_id",
              "key_id",
              "key_secret_name"
            ],
            "properties": {
              "services_id": {
                "type": "string"
              },
              "team_id": {
                "type": "string"
              },
              "key_id": {
                "type": "string"
              },
              "key_secret_name": {
                "type": "string"
              }
            },
            "additionalProperties": false
          },
          "session_cap_days": {
            "type": "integer",
            "minimum": 1,
            "maximum": 730
          },
          "clients": {
            "type": "array",
            "maxItems": 10,
            "description": "The declared native clients, each without any secret: a native client holds none.",
            "items": {
              "type": "object",
              "required": [
                "client_id",
                "redirect_uris",
                "versions_seen"
              ],
              "properties": {
                "client_id": {
                  "type": "string",
                  "description": "The client's identifier, which it presents at the authorization, token, and revocation endpoints; letters, digits, dots, underscores, colons, and hyphens."
                },
                "redirect_uris": {
                  "type": "array",
                  "minItems": 1,
                  "maxItems": 20,
                  "items": {
                    "type": "string"
                  },
                  "description": "The redirect URIs the client presents, each matched exactly, a loopback URI's port excepted: a reverse-domain custom scheme such as `com.example.app:/callback`, an `https` URI on one of the application's own hostnames, or a loopback `http` URI on `localhost`, `[::1]`, or 127.0.0.0/8. On the production realm an `https` URI on your application's custom domain is accepted too (ACS-L0-15). Any other form is refused `invalid_redirect_uri`."
                },
                "ios": {
                  "type": "object",
                  "required": [
                    "bundle_id",
                    "team_id"
                  ],
                  "properties": {
                    "bundle_id": {
                      "type": "string"
                    },
                    "team_id": {
                      "type": "string"
                    }
                  },
                  "additionalProperties": false,
                  "description": "Optional. The iOS app's bundle identifier and its ten-character team identifier, for the association files and the native ID-token exchange that later changes serve."
                },
                "android": {
                  "type": "object",
                  "required": [
                    "package",
                    "sha256_cert_fingerprints"
                  ],
                  "properties": {
                    "package": {
                      "type": "string"
                    },
                    "sha256_cert_fingerprints": {
                      "type": "array",
                      "minItems": 1,
                      "maxItems": 10,
                      "items": {
                        "type": "string"
                      }
                    }
                  },
                  "additionalProperties": false,
                  "description": "Optional. The Android app's package name and its signing-certificate SHA-256 fingerprints, each 32 upper-case hex pairs separated by colons, for the asset links and the passkey origin that later changes serve."
                },
                "google_client_ids": {
                  "type": "array",
                  "maxItems": 10,
                  "items": {
                    "type": "string"
                  },
                  "description": "Optional. The Google client identifiers a Google ID token issued for this app has as its audience, for the native ID-token exchange a later change serves."
                },
                "minimum_version": {
                  "type": "string",
                  "description": "Optional. The oldest app version accepted, as `major.minor.patch`; a request stating a lower version is refused `client_upgrade_required`."
                },
                "update_url": {
                  "type": "string",
                  "description": "Optional. An `https` URL where a refused client is sent to update."
                },
                "versions_seen": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "required": [
                      "version",
                      "last_seen"
                    ],
                    "properties": {
                      "version": {
                        "type": "string",
                        "description": "A version the client stated in its `x-turnzero-cloud-client` header."
                      },
                      "last_seen": {
                        "type": "string",
                        "format": "date-time",
                        "description": "When the platform last saw a request stating it, to the minute a router reports."
                      }
                    },
                    "additionalProperties": false
                  },
                  "description": "The versions this client's requests stated within the last day, highest first, at most fifty. Read it before you raise `minimum_version` or promote a version."
                }
              },
              "additionalProperties": false
            }
          }
        },
        "additionalProperties": false
      },
      "callbacks": {
        "type": "object",
        "required": [
          "entra",
          "apple"
        ],
        "properties": {
          "entra": {
            "type": "string",
            "description": "The work-account route's callback: list it, exactly as returned, as a web redirect URI of your tenant's app registration."
          },
          "apple": {
            "type": "string",
            "description": "Sign in with Apple's callback: list it, exactly as returned, as your Services ID's return URL, and its host as your Services ID's domain."
          }
        },
        "additionalProperties": false,
        "description": "The platform's callback addresses on this estate, returned on an end-user realm alone, whether or not either route is configured. Each is the same for both environments and never your application's hostname. List each exactly as returned."
      },
      "detail": {
        "type": "string"
      },
      "page": {
        "$ref": "#/shapes/page"
      }
    },
    "additionalProperties": false
  }
}

Shared contracts #