read_app_sign_in #
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 |
| / |
Your account's application id from list_applications, not its name or label.Type: string |
| / |
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 |
| / |
Required value: 1 |
| / |
Type: object Required fields: ["realm","sign_in_methods","creation","effective_creation","limits","counts","secrets","session_cap_days","clients"] Additional properties: false |
| / |
Type: string |
| / |
Type: array |
| / |
Allowed values: ["google","github","passkey","email","entra","apple"] |
| / |
Allowed values: ["open","invited"] |
| / |
The creation mode the realm enforces: invited under an invited audience, whatever creation holds; creation otherwise.Allowed values: ["open","invited"] |
| / |
Type: object Required fields: ["creation_ceiling","signin_starts_per_hour","code_sends_per_hour"] Additional properties: false |
| / |
Type: ["integer","null"] Minimum: 1 |
| / |
Type: integer Minimum: 1 |
| / |
Emailed sign-in codes sent per address per hour; 5 where none is set. Type: integer Minimum: 1 |
| / |
Type: integer Minimum: 1 |
| / |
Type: integer Minimum: 1 Maximum: 30 |
| / |
Type: object Required fields: ["users","sessions","test_users"] Additional properties: false |
| / |
Type: integer |
| / |
Type: integer |
| / |
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 |
| / |
Type: array |
| / |
Type: string |
| / |
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 |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string |
| / |
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 |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string |
| / |
Type: integer Minimum: 1 Maximum: 730 |
| / |
The declared native clients, each without any secret: a native client holds none. Type: array Maximum items: 10 |
| / |
Type: object Required fields: ["client_id","redirect_uris","versions_seen"] Additional properties: false |
| / |
The client's identifier, which it presents at the authorization, token, and revocation endpoints; letters, digits, dots, underscores, colons, and hyphens. Type: string |
| / |
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 |
| / |
Type: string |
| / |
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 |
| / |
Type: string |
| / |
Type: string |
| / |
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 |
| / |
Type: string |
| / |
Type: array Minimum items: 1 Maximum items: 10 |
| / |
Type: string |
| / |
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 |
| / |
Type: string |
| / |
Optional. The oldest app version accepted, as major.minor.patch; a request stating a lower version is refused client_upgrade_required.Type: string |
| / |
Optional. An https URL where a refused client is sent to update.Type: string |
| / |
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 |
| / |
Type: object Required fields: ["version","last_seen"] Additional properties: false |
| / |
A version the client stated in its x-turnzero-cloud-client header.Type: string |
| / |
When the platform last saw a request stating it, to the minute a router reports. Type: string Format: date-time |
| / |
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 |
| / |
The work-account route's callback: list it, exactly as returned, as a web redirect URI of your tenant's app registration. Type: string |
| / |
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 |
| / |
Type: string |
| / |
$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 #
- 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