read_realm
Generated automatically from the published contract sources.
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.
A script calls this action over HTTPS at POST https://turnzero.ai/api/v1/actions/read_realm, with a bearer credential and the action's payload as the JSON body. It also accepts GET.
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 names any secrets the realm references — never a value. The answer also carries the native session cap and the declared native clients, which hold no secret. Each client carries `versions_seen`, the versions its requests stated within the last day. An optional `environment` (`development` or `production`; absent, `production`) names the realm the call addresses, development's standing only once `create_environment` has turned development on. The rest is on the page /cloud/reference/actions/read-realm/, which `read_documentation` reads as `page` and the platform's origin serves.
More about this action
The answer's `callbacks` names the platform's callback on this estate for the work-account route and for Sign in with Apple, whether or not either route is configured. List `callbacks.entra`, exactly as answered, 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
{
"name": "read_realm",
"resource": "realm",
"tier": "observe",
"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
{
"name": "read_realm",
"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 names any secrets the realm references — never a value. The answer also carries the native session cap and the declared native clients, which hold no secret. Each client carries `versions_seen`, the versions its requests stated within the last day. An optional `environment` (`development` or `production`; absent, `production`) names the realm the call addresses, development's standing only once `create_environment` has turned development on. The rest is on the page /cloud/reference/actions/read-realm/, which `read_documentation` reads as `page` and the platform's origin serves.",
"owners": [
"ACS-L0-01",
"PLD-L0-40",
"ACS-L0-09"
],
"scenario": "ACS-L0-07"
}
request
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["application"] Additional properties: false |
| / |
The application id whose realm to read. Type: string |
| / |
Optional. The environment whose realm the call addresses, `development` or `production` (the accounts service PRD's realm statement); absent, `production`. Type: string Pattern: ^(development|production)$ |
response
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["contract_version","realm"] Additional properties: false |
| / |
Required value: 1 |
| / |
Type: object Required fields: ["realm","sign_in_methods","creation","limits","counts","secrets","session_cap_days","clients"] Additional properties: false |
| / |
Type: string |
| / |
Type: array |
| / |
Allowed values: ["google","github","passkey","email","entra","apple"] |
| / |
Allowed values: ["open","invited"] |
| / |
Type: object Required fields: ["creation_ceiling","signin_starts_per_hour","code_sends_per_hour"] Additional properties: false |
| / |
Type: ["integer","null"] Minimum: 1 |
| / |
Type: integer Minimum: 1 |
| / |
Emailed sign-in codes sent per address per hour; 5 where none is set (ACS-L0-12). Type: integer Minimum: 1 |
| / |
Type: integer Minimum: 1 |
| / |
Type: integer Minimum: 1 Maximum: 30 |
| / |
Type: object Required fields: ["users","sessions"] Additional properties: false |
| / |
Type: integer |
| / |
Type: integer |
| / |
Type: array |
| / |
Type: string |
| / |
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. Type: object Required fields: ["tenant","client_id","client_secret_name"] Additional properties: false |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string |
| / |
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. Type: object Required fields: ["services_id","team_id","key_id","key_secret_name"] Additional properties: false |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string |
| / |
Type: string |
| / |
Type: integer Minimum: 1 Maximum: 730 |
| / |
The declared native clients, each without any secret: a native client holds none. Type: array Maximum items: 10 |
| / |
Type: object Required fields: ["client_id","redirect_uris","versions_seen"] Additional properties: false |
| / |
The client's identifier, which it presents at the authorization, token, and revocation endpoints; letters, digits, dots, underscores, colons, and hyphens. Type: string |
| / |
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. Any other form is refused `invalid_redirect_uri`. Type: array Minimum items: 1 Maximum items: 20 |
| / |
Type: string |
| / |
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. Type: object Required fields: ["bundle_id","team_id"] Additional properties: false |
| / |
Type: string |
| / |
Type: string |
| / |
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. Type: object Required fields: ["package","sha256_cert_fingerprints"] Additional properties: false |
| / |
Type: string |
| / |
Type: array Minimum items: 1 Maximum items: 10 |
| / |
Type: string |
| / |
Optional. The Google client identifiers a Google ID token names as its audience, for the native ID-token exchange a later change serves. Type: array Maximum items: 10 |
| / |
Type: string |
| / |
Optional. The oldest app version the router admits, as `major.minor.patch`; a request stating a lower version is refused `client_upgrade_required`. Type: string |
| / |
Optional. An `https` URL where a refused client is sent to update. Type: string |
| / |
The versions this client's requests stated within the last day, highest first, at most fifty. Read it before raising `minimum_version` or promoting a version. Type: array |
| / |
Type: object Required fields: ["version","last_seen"] Additional properties: false |
| / |
A version the client stated in its `x-turnzero-cloud-client` header. Type: string |
| / |
When the platform last saw a request stating it, to the minute a router reports. Type: string Format: date-time |
| / |
The platform's callback addresses on this estate, answered on an end-user realm alone, whether or not either route is configured. Each is the same for both environments and never the application's hostname. List each exactly as answered. Type: object Required fields: ["entra","apple"] Additional properties: false |
| / |
The work-account route's callback: list it, exactly as answered, as a web redirect URI of the tenant's app registration. Type: string |
| / |
Sign in with Apple's callback: list it, exactly as answered, as the Services ID's return URL, and its host as the Services ID's domain. Type: string |
| / |
Type: string |
Complete payload contract
{
"request": {
"type": "object",
"required": [
"application"
],
"properties": {
"application": {
"type": "string",
"description": "The application id whose realm to read."
},
"environment": {
"type": "string",
"pattern": "^(development|production)$",
"description": "Optional. The environment whose realm the call addresses, `development` or `production` (the accounts service PRD's realm statement); absent, `production`."
}
},
"additionalProperties": false
},
"response": {
"type": "object",
"required": [
"contract_version",
"realm"
],
"properties": {
"contract_version": {
"const": 1
},
"realm": {
"type": "object",
"required": [
"realm",
"sign_in_methods",
"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"
]
},
"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"
],
"properties": {
"users": {
"type": "integer"
},
"sessions": {
"type": "integer"
}
},
"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. 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 names as its audience, for the native ID-token exchange a later change serves."
},
"minimum_version": {
"type": "string",
"description": "Optional. The oldest app version the router admits, 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 raising `minimum_version` or promoting 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 answered, as a web redirect URI of the tenant's app registration."
},
"apple": {
"type": "string",
"description": "Sign in with Apple's callback: list it, exactly as answered, as the Services ID's return URL, and its host as the Services ID's domain."
}
},
"additionalProperties": false,
"description": "The platform's callback addresses on this estate, answered on an end-user realm alone, whether or not either route is configured. Each is the same for both environments and never the application's hostname. List each exactly as answered."
},
"detail": {
"type": "string"
}
},
"additionalProperties": false
}
}
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