check_realm #

Generated automatically from the published contract sources.

A script calls this action over HTTPS at POST https://turnzero.ai/api/v1/actions/check_realm, with a bearer credential and the action's payload as the JSON body. It also accepts GET.

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 with no one signing in. Call it after configure_realm or a manifest's realm member sets entra or apple, before you tell the person the route works. For each route you get credential, whether the stored secret reads; provider, whether Microsoft or Apple accepts the client; and route, whether the realm's sign-in page offers it. A route that needs a step carries detail with that step. Where the answer carries next, make that submit_manifest call to move a stored secret into the realm vault. An optional environment (development or production; absent, production) selects the realm your call checks.

More about this action #

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, unknown with the status it returned, or not_checked where the credential did not read. The platform asks the provider's token endpoint to exchange a code no sign-in issued, and a refusal of the code itself shows the client was accepted. 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_realm",
  "resource": "realm",
  "tier": "observe",
  "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, whether its provider accepts the client, and whether the realm's sign-in page offers the route.",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": true
  }
}

MCP catalog entry #

{
  "name": "check_realm",
  "title": "Check app sign-in routes",
  "tier": "observe",
  "summary": "Check an application's work-account and Apple sign-in routes with no one signing in. Call it after `configure_realm` or a manifest's `realm` member sets `entra` or `apple`, before you tell the person the route works. For each route you get `credential`, whether the stored secret reads; `provider`, whether Microsoft or Apple accepts the client; and `route`, whether the realm's sign-in page offers it. A route that needs a step carries `detail` with that step. Where the answer carries `next`, make that `submit_manifest` call to move a stored secret into the realm vault. An optional `environment` (`development` or `production`; absent, `production`) selects the realm your call checks.",
  "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
/properties/application	The application id whose realm to check. Type: string
/properties/environment	Optional. The environment whose realm you check, `development` or `production`; without it, `production`. 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"]
/properties/contract_version	Required value: 1
/properties/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. Type: string Pattern: ^[0-9a-f]{10}$
/properties/application	Type: string
/properties/environment	Allowed values: ["development","production"]
/properties/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. Type: string
/properties/routes	One entry for each of `entra` and `apple` the realm configures, in that order; empty where it configures neither. Type: array
/properties/routes/items	Type: object Required fields: ["name","credential","provider","route"] Additional properties: false
/properties/routes/items/properties/name	Allowed values: ["entra","apple"]
/properties/routes/items/properties/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. Type: object Required fields: ["outcome"] Additional properties: false
/properties/routes/items/properties/credential/properties/outcome	Allowed values: ["not_moved","read","custody_entry_missing","unreadable","not_configured","unknown"]
/properties/routes/items/properties/provider	Whether the route's provider accepts the client; `not_checked` where the credential did not read. Type: object Required fields: ["outcome"] Additional properties: false
/properties/routes/items/properties/provider/properties/outcome	Allowed values: ["accepted","refused","unknown","not_checked"]
/properties/routes/items/properties/provider/properties/error	Present where `outcome` is `refused`: the error code the provider returned. Allowed values: ["invalid_client","unauthorized_client"]
/properties/routes/items/properties/provider/properties/status	Present where `outcome` is `unknown`: the provider's status, null where no answer came within the bound. Type: ["integer","null"]
/properties/routes/items/properties/route	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
/properties/routes/items/properties/route/properties/outcome	Allowed values: ["serving","not_serving","unknown"]
/properties/routes/items/properties/route/properties/status	Present where `outcome` is `not_serving` or `unknown`: the sign-in page's status, null where no answer came. Type: ["integer","null"]
/properties/routes/items/properties/detail	Present where the route needs a step: that step. Type: string
/properties/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. Type: object Required fields: ["action","arguments"] Additional properties: false
/properties/next/properties/action	Required value: submit_manifest
/properties/next/properties/arguments	Type: object Required fields: ["application","manifest"] Additional properties: false
/properties/next/properties/arguments/properties/application	Type: string
/properties/next/properties/arguments/properties/manifest	Type: object
/properties/detail	Type: string
/properties/page	$ref: #/shapes/page

Complete payload contract #

{
  "request": {
    "type": "object",
    "required": [
      "application"
    ],
    "properties": {
      "application": {
        "type": "string",
        "description": "The application id whose realm to check."
      },
      "environment": {
        "type": "string",
        "pattern": "^(development|production)$",
        "description": "Optional. The environment whose realm you check, `development` or `production`; without it, `production`."
      }
    },
    "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 error code the provider returned."
                },
                "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": "Whether the route's provider accepts the client; `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