check_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/check_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_check_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 #
Check an application's work-account and Apple sign-in routes without signing anyone in. Call it after configure_app_sign_in or the manifest's realm member sets entra or apple. It cannot check registered callback URLs or work-account ID-token claims. A person proves the route by signing in through its provider. For each route you get credential, whether the secret reads. You also get provider, the token endpoint's test response, and route, whether sign-in is served. serving means the sign-in page offers a method enabled in sign_in_methods, even before a deploy. read_status gives the deploy's state. A route needing action carries detail. If the answer carries next, make that submit_manifest call to move the stored secret into the realm vault.
More about this action #
The check cannot see the Entra web redirect URI, Apple's Services ID return URL, or the work-account ID token's email and xms_edov claims; have a person test them by signing in through the provider.
credential is read, not_moved (stored, but not yet in the realm vault), custody_entry_missing, unreadable, not_configured, or unknown. provider is accepted, refused with the provider's error and optional Entra code, unknown with the HTTP status when available and optional Entra code, or not_checked where the credential did not read. For Entra, the platform makes a client-credentials request for a deliberately nonexistent resource. For Apple, it exchanges a code no sign-in issued.
For an Entra result of refused or unknown, code is the first error_codes entry when it is a positive integer. Apple carries no code. It is a diagnostic number; error still decides the outcome.
For Entra codes 700016 and 7000229, read the client identifier and tenant with read_app_sign_in, correcting them with configure_app_sign_in if needed. If they are right, check the registration's service principal and consent in that tenant. Sign in through the route once, or ask the tenant's administrator to grant consent or create the missing service principal, then check again. These two codes call for no secret replacement.
For code 90002, Entra found no tenant under the configured name. A placeholder or a mistyped tenant can cause this; read the real Tenant ID in the Microsoft Entra admin center under Entra ID > Overview > Properties. For code 900023, Entra could not read the configured tenant name. Read the tenant with read_app_sign_in. If the manifest sets realm.entra, correct it there and submit the manifest with submit_manifest. Otherwise correct it with configure_app_sign_in. Then check again. This result does not call for a new secret.
For Entra, accepted means the probe returned invalid_resource; this mapping treats the client identifier and secret as accepted, and that refusal issues no token. Its accepted response still awaits a live check with the stored secret.
For Apple, accepted means invalid_grant; its mapping is inferred and unverified, and the response proves neither the client identifier nor the secret. A successful sign-in is still needed to prove each route. invalid_client or unauthorized_client reads refused. Any other answer is unknown, including a successful token response. No token is kept.
route is serving, not_serving with the page's status, or unknown where the page returned 429 or nothing.
The call ends within 20 seconds. One account makes at most ten checks a minute, and each realm takes at most ten a minute; past either, the call is refused rate_capped. Where the platform cannot reach the service that reads the credentials, the call is refused realm_check_unavailable; call it again.
Access and action metadata #
{
"name": "check_app_sign_in",
"resource": "realm",
"tier": "observe",
"surface": "tzcloud",
"addresses": [
"tzcloud"
],
"product": "cloud",
"summary": "Check a realm's work-account and Apple sign-in routes with no one signing in: for each, whether its stored credential reads, the provider token endpoint's test response, and whether the realm's sign-in page offers the route.",
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"openWorldHint": true
}
}
MCP catalog entry #
{
"name": "check_app_sign_in",
"title": "Check app sign-in routes",
"tier": "observe",
"summary": "Check an application's work-account and Apple sign-in routes without signing anyone in. Call it after `configure_app_sign_in` or the manifest's `realm` member sets `entra` or `apple`. It cannot check registered callback URLs or work-account ID-token claims. A person proves the route by signing in through its provider. For each route you get `credential`, whether the secret reads. You also get `provider`, the token endpoint's test response, and `route`, whether sign-in is served. `serving` means the sign-in page offers a method enabled in `sign_in_methods`, even before a deploy. `read_status` gives the deploy's state. A route needing action carries `detail`. If the answer carries `next`, make that `submit_manifest` call to move the stored secret into the realm vault.",
"owners": [
"MAPI-30",
"ACS-L0-24",
"PLD-L0-67"
],
"scenario": "ACS-L0-24"
}
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 |
| / |
Default production; development before create_environment is refused environment_not_created.Type: string Pattern: ^(development|production)$ |
response #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["contract_version","application","environment","sign_in_page","routes","detail","page"] |
| / |
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}$ |
| / |
Type: string |
| / |
Allowed values: ["development","production"] |
| / |
The address of the realm's sign-in page the check requested, on the realm's own host, its custom domain where one serves. Type: string |
| / |
One entry for each of entra and apple the realm configures, in that order; empty where it configures neither.Type: array |
| / |
Type: object Required fields: ["name","credential","provider","route"] Additional properties: false |
| / |
Allowed values: ["entra","apple"] |
| / |
Whether the stored credential reads: not_moved where it is stored but not yet in the realm vault, unknown where the read did not finish within its bound.Type: object Required fields: ["outcome"] Additional properties: false |
| / |
Allowed values: ["not_moved","read","custody_entry_missing","unreadable","not_configured","unknown"] |
| / |
The token endpoint's test response. Entra's accepted (invalid_resource) checks the client identifier and secret; its live acceptance reading is pending. Apple's accepted (invalid_grant) is inferred and unverified. A sign-in proves the route. not_checked where the credential did not read.Type: object Required fields: ["outcome"] Additional properties: false |
| / |
Allowed values: ["accepted","refused","unknown","not_checked"] |
| / |
Present where outcome is refused: the provider's OAuth error value.Allowed values: ["invalid_client","unauthorized_client"] |
| / |
Present on an Entra refused outcome or an Entra unknown outcome with a status, when the first error_codes entry is a positive integer. On an Entra unknown, 90002 means no tenant was found, and 900023 means its name could not be read; no client was checked, so follow detail's tenant step. The number can choose the next step. It does not change the outcome.Type: integer Minimum: 1 |
| / |
Present where outcome is unknown: the provider's status, null where no answer came within the bound.Type: ["integer","null"] |
| / |
Whether the realm's sign-in page offers the route; unknown where the page returned 429 or nothing.Type: object Required fields: ["outcome"] Additional properties: false |
| / |
Allowed values: ["serving","not_serving","unknown"] |
| / |
Present where outcome is not_serving or unknown: the sign-in page's status, null where no answer came.Type: ["integer","null"] |
| / |
Present where the route needs a step: that step. Type: string |
| / |
Present where a credential is not_moved and the recorded manifest's realm member gives that route's credential: the one submit_manifest call with the recorded manifest, which moves the value into the realm vault.Type: object Required fields: ["action","arguments"] Additional properties: false |
| / |
Required value: submit_manifest |
| / |
Type: object Required fields: ["application","manifest"] Additional properties: false |
| / |
Type: string |
| / |
Type: object |
| / |
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": "Default `production`; development before `create_environment` is refused `environment_not_created`."
}
},
"additionalProperties": false
},
"response": {
"type": "object",
"required": [
"contract_version",
"application",
"environment",
"sign_in_page",
"routes",
"detail",
"page"
],
"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."
},
"application": {
"type": "string"
},
"environment": {
"enum": [
"development",
"production"
]
},
"sign_in_page": {
"type": "string",
"description": "The address of the realm's sign-in page the check requested, on the realm's own host, its custom domain where one serves."
},
"routes": {
"type": "array",
"description": "One entry for each of `entra` and `apple` the realm configures, in that order; empty where it configures neither.",
"items": {
"type": "object",
"required": [
"name",
"credential",
"provider",
"route"
],
"properties": {
"name": {
"enum": [
"entra",
"apple"
]
},
"credential": {
"type": "object",
"required": [
"outcome"
],
"properties": {
"outcome": {
"enum": [
"not_moved",
"read",
"custody_entry_missing",
"unreadable",
"not_configured",
"unknown"
]
}
},
"additionalProperties": false,
"description": "Whether the stored credential reads: `not_moved` where it is stored but not yet in the realm vault, `unknown` where the read did not finish within its bound."
},
"provider": {
"type": "object",
"required": [
"outcome"
],
"properties": {
"outcome": {
"enum": [
"accepted",
"refused",
"unknown",
"not_checked"
]
},
"error": {
"enum": [
"invalid_client",
"unauthorized_client"
],
"description": "Present where `outcome` is `refused`: the provider's OAuth `error` value."
},
"code": {
"type": "integer",
"minimum": 1,
"description": "Present on an Entra `refused` outcome or an Entra `unknown` outcome with a status, when the first `error_codes` entry is a positive integer. On an Entra `unknown`, 90002 means no tenant was found, and 900023 means its name could not be read; no client was checked, so follow `detail`'s tenant step. The number can choose the next step. It does not change the outcome."
},
"status": {
"type": [
"integer",
"null"
],
"description": "Present where `outcome` is `unknown`: the provider's status, null where no answer came within the bound."
}
},
"additionalProperties": false,
"description": "The token endpoint's test response. Entra's `accepted` (`invalid_resource`) checks the client identifier and secret; its live acceptance reading is pending. Apple's `accepted` (`invalid_grant`) is inferred and unverified. A sign-in proves the route. `not_checked` where the credential did not read."
},
"route": {
"type": "object",
"required": [
"outcome"
],
"properties": {
"outcome": {
"enum": [
"serving",
"not_serving",
"unknown"
]
},
"status": {
"type": [
"integer",
"null"
],
"description": "Present where `outcome` is `not_serving` or `unknown`: the sign-in page's status, null where no answer came."
}
},
"additionalProperties": false,
"description": "Whether the realm's sign-in page offers the route; `unknown` where the page returned 429 or nothing."
},
"detail": {
"type": "string",
"description": "Present where the route needs a step: that step."
}
},
"additionalProperties": false
}
},
"next": {
"type": "object",
"required": [
"action",
"arguments"
],
"properties": {
"action": {
"const": "submit_manifest"
},
"arguments": {
"type": "object",
"required": [
"application",
"manifest"
],
"properties": {
"application": {
"type": "string"
},
"manifest": {
"type": "object"
}
},
"additionalProperties": false
}
},
"additionalProperties": false,
"description": "Present where a credential is `not_moved` and the recorded manifest's `realm` member gives that route's credential: the one `submit_manifest` call with the recorded manifest, which moves the value into the realm vault."
},
"detail": {
"type": "string"
},
"page": {
"$ref": "#/shapes/page"
}
}
}
}
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