---
title: "check_app_sign_in"
description: "Generated reference for the management action check_app_sign_in: its description, access metadata, payload contract, and registration status."
slug: /reference/actions/check-app-sign-in
order: 58
visibility: public
redirects_from: ["/reference/actions/check-realm"]
---

# check\_app\_sign\_in

Generated automatically from the [published contract sources](/cloud/reference/about/#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](/cloud/concepts/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 &gt; Overview &gt; 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

```json
{
  "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

```json
{
  "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<br>Required fields: \["application"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>application | Your account's application `id` from `list_applications`, not its name or label\.<br><br>Type: string |
| /<wbr>properties/<wbr>environment | Default `production`; development before `create_environment` is refused `environment_not_created`\.<br><br>Type: string<br>Pattern: ^\(development\|production\)$ |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version","application","environment","sign\_in\_page","routes","detail","page"\] |
| /<wbr>properties/<wbr>contract\_version | Required value: 1 |
| /<wbr>properties/<wbr>reference | 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\.<br><br>Type: string<br>Pattern: ^\[0\-9a\-f\]\{10\}$ |
| /<wbr>properties/<wbr>application | Type: string |
| /<wbr>properties/<wbr>environment | Allowed values: \["development","production"\] |
| /<wbr>properties/<wbr>sign\_in\_page | The address of the realm's sign\-in page the check requested, on the realm's own host, its custom domain where one serves\.<br><br>Type: string |
| /<wbr>properties/<wbr>routes | One entry for each of `entra` and `apple` the realm configures, in that order; empty where it configures neither\.<br><br>Type: array |
| /<wbr>properties/<wbr>routes/<wbr>items | Type: object<br>Required fields: \["name","credential","provider","route"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>routes/<wbr>items/<wbr>properties/<wbr>name | Allowed values: \["entra","apple"\] |
| /<wbr>properties/<wbr>routes/<wbr>items/<wbr>properties/<wbr>credential | 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\.<br><br>Type: object<br>Required fields: \["outcome"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>routes/<wbr>items/<wbr>properties/<wbr>credential/<wbr>properties/<wbr>outcome | Allowed values: \["not\_moved","read","custody\_entry\_missing","unreadable","not\_configured","unknown"\] |
| /<wbr>properties/<wbr>routes/<wbr>items/<wbr>properties/<wbr>provider | 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\.<br><br>Type: object<br>Required fields: \["outcome"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>routes/<wbr>items/<wbr>properties/<wbr>provider/<wbr>properties/<wbr>outcome | Allowed values: \["accepted","refused","unknown","not\_checked"\] |
| /<wbr>properties/<wbr>routes/<wbr>items/<wbr>properties/<wbr>provider/<wbr>properties/<wbr>error | Present where `outcome` is `refused`: the provider's OAuth `error` value\.<br><br>Allowed values: \["invalid\_client","unauthorized\_client"\] |
| /<wbr>properties/<wbr>routes/<wbr>items/<wbr>properties/<wbr>provider/<wbr>properties/<wbr>code | 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\.<br><br>Type: integer<br>Minimum: 1 |
| /<wbr>properties/<wbr>routes/<wbr>items/<wbr>properties/<wbr>provider/<wbr>properties/<wbr>status | Present where `outcome` is `unknown`: the provider's status, null where no answer came within the bound\.<br><br>Type: \["integer","null"\] |
| /<wbr>properties/<wbr>routes/<wbr>items/<wbr>properties/<wbr>route | Whether the realm's sign\-in page offers the route; `unknown` where the page returned 429 or nothing\.<br><br>Type: object<br>Required fields: \["outcome"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>routes/<wbr>items/<wbr>properties/<wbr>route/<wbr>properties/<wbr>outcome | Allowed values: \["serving","not\_serving","unknown"\] |
| /<wbr>properties/<wbr>routes/<wbr>items/<wbr>properties/<wbr>route/<wbr>properties/<wbr>status | Present where `outcome` is `not_serving` or `unknown`: the sign\-in page's status, null where no answer came\.<br><br>Type: \["integer","null"\] |
| /<wbr>properties/<wbr>routes/<wbr>items/<wbr>properties/<wbr>detail | Present where the route needs a step: that step\.<br><br>Type: string |
| /<wbr>properties/<wbr>next | 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\.<br><br>Type: object<br>Required fields: \["action","arguments"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>next/<wbr>properties/<wbr>action | Required value: submit\_manifest |
| /<wbr>properties/<wbr>next/<wbr>properties/<wbr>arguments | Type: object<br>Required fields: \["application","manifest"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>next/<wbr>properties/<wbr>arguments/<wbr>properties/<wbr>application | Type: string |
| /<wbr>properties/<wbr>next/<wbr>properties/<wbr>arguments/<wbr>properties/<wbr>manifest | Type: object |
| /<wbr>properties/<wbr>detail | Type: string |
| /<wbr>properties/<wbr>page | $ref: \#/shapes/page |

## Complete payload contract

```json
{
  "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](/cloud/reference/refusals/): every refusal, by surface, with its cause and its remedy
- [schemas/wire\_error\.schema\.json](/cloud/reference/sources/schemas/wire-error-schema/)
- [schemas/wire\_errors\.json](/cloud/reference/sources/schemas/wire-errors/)
- [schemas/action\_payloads\.json](/cloud/reference/sources/schemas/action-payloads/) (includes shared shapes)
- [management\_api\_contract\.md](/cloud/reference/sources/management-api-contract/)
