--- title: "check_realm" description: "Generated reference for the management action check_realm: its description, access metadata, payload contract, and registration status." slug: /reference/actions/check-realm order: 72 visibility: public redirects_from: [] --- # check\_realm Generated automatically from the [published contract sources](/cloud/reference/about/#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 ```json { "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 ```json { "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 ```json { "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](/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/)