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

# read\_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/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](/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

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

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

```json
{
  "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<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 | Optional\. The environment whose realm you address, `development` or `production`; without it, `production`\.<br><br>Type: string<br>Pattern: ^\(development\|production\)$ |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version","realm"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>contract\_version | Required value: 1 |
| /<wbr>properties/<wbr>realm | Type: object<br>Required fields: \["realm","sign\_in\_methods","creation","effective\_creation","limits","counts","secrets","session\_cap\_days","clients"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>realm | Type: string |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>sign\_in\_methods | Type: array |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>sign\_in\_methods/<wbr>items | Allowed values: \["google","github","passkey","email","entra","apple"\] |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>creation | Allowed values: \["open","invited"\] |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>effective\_creation | The creation mode the realm enforces: `invited` under an invited audience, whatever `creation` holds; `creation` otherwise\.<br><br>Allowed values: \["open","invited"\] |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>limits | Type: object<br>Required fields: \["creation\_ceiling","signin\_starts\_per\_hour","code\_sends\_per\_hour"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>limits/<wbr>properties/<wbr>creation\_ceiling | Type: \["integer","null"\]<br>Minimum: 1 |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>limits/<wbr>properties/<wbr>signin\_starts\_per\_hour | Type: integer<br>Minimum: 1 |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>limits/<wbr>properties/<wbr>code\_sends\_per\_hour | Emailed sign\-in codes sent per address per hour; 5 where none is set\.<br><br>Type: integer<br>Minimum: 1 |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>invitation\_days | Type: integer<br>Minimum: 1 |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>session\_days | Type: integer<br>Minimum: 1<br>Maximum: 30 |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>counts | Type: object<br>Required fields: \["users","sessions","test\_users"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>counts/<wbr>properties/<wbr>users | Type: integer |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>counts/<wbr>properties/<wbr>sessions | Type: integer |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>counts/<wbr>properties/<wbr>test\_users | The realm's unexpired test end users, the rows the expiry pass has not yet removed; counted apart from `users`, which excludes them\.<br><br>Type: integer |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>secrets | Type: array |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>secrets/<wbr>items | Type: string |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>entra | 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\.<br><br>Type: object<br>Required fields: \["tenant","client\_id","client\_secret\_name"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>entra/<wbr>properties/<wbr>tenant | Type: string |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>entra/<wbr>properties/<wbr>client\_id | Type: string |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>entra/<wbr>properties/<wbr>client\_secret\_name | Type: string |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>apple | 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\.<br><br>Type: object<br>Required fields: \["services\_id","team\_id","key\_id","key\_secret\_name"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>apple/<wbr>properties/<wbr>services\_id | Type: string |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>apple/<wbr>properties/<wbr>team\_id | Type: string |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>apple/<wbr>properties/<wbr>key\_id | Type: string |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>apple/<wbr>properties/<wbr>key\_secret\_name | Type: string |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>session\_cap\_days | Type: integer<br>Minimum: 1<br>Maximum: 730 |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>clients | The declared native clients, each without any secret: a native client holds none\.<br><br>Type: array<br>Maximum items: 10 |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>clients/<wbr>items | Type: object<br>Required fields: \["client\_id","redirect\_uris","versions\_seen"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>clients/<wbr>items/<wbr>properties/<wbr>client\_id | The client's identifier, which it presents at the authorization, token, and revocation endpoints; letters, digits, dots, underscores, colons, and hyphens\.<br><br>Type: string |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>clients/<wbr>items/<wbr>properties/<wbr>redirect\_uris | 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`\.<br><br>Type: array<br>Minimum items: 1<br>Maximum items: 20 |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>clients/<wbr>items/<wbr>properties/<wbr>redirect\_uris/<wbr>items | Type: string |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>clients/<wbr>items/<wbr>properties/<wbr>ios | 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\.<br><br>Type: object<br>Required fields: \["bundle\_id","team\_id"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>clients/<wbr>items/<wbr>properties/<wbr>ios/<wbr>properties/<wbr>bundle\_id | Type: string |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>clients/<wbr>items/<wbr>properties/<wbr>ios/<wbr>properties/<wbr>team\_id | Type: string |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>clients/<wbr>items/<wbr>properties/<wbr>android | 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\.<br><br>Type: object<br>Required fields: \["package","sha256\_cert\_fingerprints"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>clients/<wbr>items/<wbr>properties/<wbr>android/<wbr>properties/<wbr>package | Type: string |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>clients/<wbr>items/<wbr>properties/<wbr>android/<wbr>properties/<wbr>sha256\_cert\_fingerprints | Type: array<br>Minimum items: 1<br>Maximum items: 10 |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>clients/<wbr>items/<wbr>properties/<wbr>android/<wbr>properties/<wbr>sha256\_cert\_fingerprints/<wbr>items | Type: string |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>clients/<wbr>items/<wbr>properties/<wbr>google\_client\_ids | 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\.<br><br>Type: array<br>Maximum items: 10 |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>clients/<wbr>items/<wbr>properties/<wbr>google\_client\_ids/<wbr>items | Type: string |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>clients/<wbr>items/<wbr>properties/<wbr>minimum\_version | Optional\. The oldest app version accepted, as `major.minor.patch`; a request stating a lower version is refused `client_upgrade_required`\.<br><br>Type: string |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>clients/<wbr>items/<wbr>properties/<wbr>update\_url | Optional\. An `https` URL where a refused client is sent to update\.<br><br>Type: string |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>clients/<wbr>items/<wbr>properties/<wbr>versions\_seen | 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\.<br><br>Type: array |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>clients/<wbr>items/<wbr>properties/<wbr>versions\_seen/<wbr>items | Type: object<br>Required fields: \["version","last\_seen"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>clients/<wbr>items/<wbr>properties/<wbr>versions\_seen/<wbr>items/<wbr>properties/<wbr>version | A version the client stated in its `x-turnzero-cloud-client` header\.<br><br>Type: string |
| /<wbr>properties/<wbr>realm/<wbr>properties/<wbr>clients/<wbr>items/<wbr>properties/<wbr>versions\_seen/<wbr>items/<wbr>properties/<wbr>last\_seen | When the platform last saw a request stating it, to the minute a router reports\.<br><br>Type: string<br>Format: date\-time |
| /<wbr>properties/<wbr>callbacks | 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\.<br><br>Type: object<br>Required fields: \["entra","apple"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>callbacks/<wbr>properties/<wbr>entra | The work\-account route's callback: list it, exactly as returned, as a web redirect URI of your tenant's app registration\.<br><br>Type: string |
| /<wbr>properties/<wbr>callbacks/<wbr>properties/<wbr>apple | 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\.<br><br>Type: string |
| /<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": "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](/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/)
