configure_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/configure_realm, with a bearer credential and the action's payload as the JSON body.
Contract description
Change how an application's end users sign in: its realm's sign-in methods (`google`, `github`, `passkey`, `email`, `entra`, `apple`) and whether account creation is open or by invitation only. It also sets the account, sign-in, and emailed-code limits, invitation and session lifetimes, and Entra settings.
The `apple` member names the Services ID, the team and key identifiers, and the stored signing key's name. The `session_cap_days` member caps a native session's days. The `clients` member lists the native apps signing in through the realm, each a `client_id` with its redirect URIs and app signing identities. Raising a client's `minimum_version` answers `warnings`, the in-use versions it refuses. Only supplied members change; `sign_in_methods` and `clients` each replace their list. The manifest must declare the accounts service. Omit `application` only as a platform operator to change the builder realm's `creation` mode, `limits.creation_ceiling`, or `limits.site_public`, other members refused. An optional `environment` (`development` or `production`; absent, `production`) names the realm addressed. A field the manifest's `realm` member names is refused `manifest_owned_field`.
The `entra` member's `client_secret_name` and the `apple` member's `key_secret_name` each take the name of a stored secret, never its value. The rest is on the page /cloud/reference/actions/configure-realm/, which `read_documentation` reads as `page` and the platform's origin serves.
More about this action
On `sign_in_methods`, `email` is served where the platform holds a sender. Under a manifest's `invited` audience both realms are invitation-only whatever `creation` holds.
The `limits.code_sends_per_hour` bound of 30 is a bound of its own that no author raises; the realm's own ceiling follows the application's plan. Sessions opened after a call that sets `session_days` take the new value; a session already open keeps its expiry. Each refresh extends a native session by `session_days` up to the `session_cap_days` cap.
On the `entra` route, sign-ins from any tenant other than the declared `tenant` are refused. The `apple` member's key moves into the realm vault and signs Apple's client secret alone. Its `services_id` is a Services ID such as com.example.app.signin. On an end-user realm, the answer's `callbacks` names the platform's callback on this estate for the work-account route and for Sign in with Apple: list `callbacks.entra`, exactly as answered, as the app registration's web redirect URI, and `callbacks.apple` as the Services ID's return URL.
A native client presents its `client_id` at the authorization, token, and revocation endpoints. Each of its `redirect_uris` is matched exactly, a loopback URI's port excepted. A reverse-domain custom scheme is one such as `com.example.app:/callback`. The `ios` member is for the association files and the native ID-token exchange that later changes serve. The `android` member is for the asset links and the passkey origin that later changes serve. The `google_client_ids` member is for the native ID-token exchange a later change serves. A request stating a version lower than `minimum_version` is refused `client_upgrade_required`.
With `application` omitted, the call configures the platform's builder sign-in, requires the `super_admin` grant, and accepts `creation`, `limits.creation_ceiling`, and `limits.site_public` alone. The builder sign-in is invitation-only unless the operator has opened enrollment. For the builder realm, `limits.creation_ceiling` is the operator's configured value, null clearing it, and no ceiling where none is set. The `environment` member is ignored where `application` is absent, because the builder realm has no environment. The members `session_days`, `session_cap_days`, and `clients` are each refused by name with no `application` member.
The `limits.site_public` member is for the builder realm alone, with no application: whether the public website is open to every visitor and indexable. It is read as public only where it is true and the creation mode is open; false or null (null removes it) returns the site to private.
Access and action metadata
{
"name": "configure_realm",
"resource": "realm",
"tier": "reversible",
"summary": "Set a realm's enabled sign-in methods, whether creation is open or invitation-only, the creation ceiling, the per-source sign-in rate, the session lifetime with the cap on a native session's sliding life, and the native clients it declares; refused by name for an application whose manifest declares no accounts service, for sign-in methods contradicting the declared audience, or for a redirect URI outside the admitted forms; with no application member the builder realm's creation mode, its creation ceiling, and its site_public member alone, admitted to super_admin alone. Raising a client's minimum version answers a warning naming the versions seen within the last day that the new minimum refuses.",
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"openWorldHint": false
}
}
MCP catalog entry
{
"name": "configure_realm",
"tier": "reversible",
"summary": "Change how an application's end users sign in: its realm's sign-in methods (`google`, `github`, `passkey`, `email`, `entra`, `apple`) and whether account creation is open or by invitation only. It also sets the account, sign-in, and emailed-code limits, invitation and session lifetimes, and Entra settings.\n\nThe `apple` member names the Services ID, the team and key identifiers, and the stored signing key's name. The `session_cap_days` member caps a native session's days. The `clients` member lists the native apps signing in through the realm, each a `client_id` with its redirect URIs and app signing identities. Raising a client's `minimum_version` answers `warnings`, the in-use versions it refuses. Only supplied members change; `sign_in_methods` and `clients` each replace their list. The manifest must declare the accounts service. Omit `application` only as a platform operator to change the builder realm's `creation` mode, `limits.creation_ceiling`, or `limits.site_public`, other members refused. An optional `environment` (`development` or `production`; absent, `production`) names the realm addressed. A field the manifest's `realm` member names is refused `manifest_owned_field`.\n\nThe `entra` member's `client_secret_name` and the `apple` member's `key_secret_name` each take the name of a stored secret, never its value. The rest is on the page /cloud/reference/actions/configure-realm/, which `read_documentation` reads as `page` and the platform's origin serves.",
"owners": [
"ACS-L0-07",
"ACS-L0-12",
"ACS-L0-01",
"ADM-L0-05",
"ACB-L0-77",
"ACB-L0-80",
"ACS-L0-05",
"ACS-L0-09",
"PLD-L0-40",
"ACS-L0-15"
],
"scenario": "ACS-L0-07"
}
request
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: [] Replaced members: routes was replaced by sign_in_methods Additional properties: false |
| / |
The application id whose realm to configure (see `list_applications`); its manifest must declare the accounts service. Type: string |
| / |
The enabled sign-in methods, replacing the current set. An empty set admits no sign-in, and `passkey` alone is refused. Naming `entra` or `apple` needs that member in this call or an earlier one. An invitation-only realm refuses `entra`, and a workforce audience allows `entra` alone. $anchor: realm_sign_in_methods Type: array |
| / |
Allowed values: ["google","github","passkey","email","entra","apple"] |
| / |
Who may create an account by signing in: `open`, anyone, the default, or `invited`, only the holder of an invitation from `issue_invitation`. Under a manifest's `invited` audience `open` is refused `creation_contradicts_audience`. Allowed values: ["open","invited"] |
| / |
The realm's limits. Pass only the members you change. Type: object Additional properties: false |
| / |
End-user realm: most accounts (1000 unset). Builder realm: most open sign-ups. Type: ["integer","null"] Minimum: 1 |
| / |
Sign-in starts allowed per source address per hour; 30 where none is set. Type: integer Minimum: 1 |
| / |
Emailed sign-in codes sent per address per hour; 5 where none is set, and at most 30. Type: integer Minimum: 1 |
| / |
The builder realm alone, with no application. Refused by name on an application's realm. Type: ["boolean","null"] |
| / |
How many days an invitation from `issue_invitation` stays redeemable; 14 where none is set. Type: integer Minimum: 1 |
| / |
How many days a session the realm opens lives: 30 where none is set. Type: integer Minimum: 1 Maximum: 30 |
| / |
The work-account route for a company's Microsoft Entra tenant. $anchor: realm_entra Type: object Required fields: ["tenant","client_id","client_secret_name"] Additional properties: false |
| / |
The Microsoft Entra tenant id, a GUID. Type: string |
| / |
The client id of the app registration in that tenant. Type: string |
| / |
The name the client secret was stored under with `store_secret` naming this application — the name, never the value. Type: string |
| / |
Sign in with Apple. Type: object Required fields: ["services_id","team_id","key_id","key_secret_name"] Additional properties: false |
| / |
The Services ID registered with Apple for the web sign-in. Type: string |
| / |
The developer team's ten-character identifier. Type: string Pattern: ^[A-Z0-9]{10}$ |
| / |
The Sign in with Apple key's ten-character identifier. Type: string Pattern: ^[A-Z0-9]{10}$ |
| / |
The name the key's `.p8` text was stored under with `store_secret` naming this application — the name, never the value. Type: string |
| / |
The environment whose realm the call addresses, `development` or `production`; absent, `production`. Type: string Pattern: ^(development|production)$ |
| / |
How many days a native session may run from its creation: 365 where none is set, and no smaller than `session_days`. Type: integer Minimum: 1 Maximum: 730 |
| / |
The realm's native public clients, at most ten, replacing the current list. On one environment the production realm takes both builds' redirect URIs; with development turned on, the development realm takes the debug build's and the production realm the store build's. Type: array Maximum items: 10 |
| / |
$anchor: realm_client Type: object Required fields: ["client_id","redirect_uris"] Additional properties: false |
| / |
The client's identifier: letters, digits, dots, underscores, colons, and hyphens. Type: string |
| / |
The redirect URIs the client presents: a reverse-domain custom scheme, 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 |
| / |
The iOS app's bundle identifier and its ten-character team identifier. Type: object Required fields: ["bundle_id","team_id"] Additional properties: false |
| / |
Type: string |
| / |
Type: string |
| / |
The Android app's package name and its signing-certificate SHA-256 fingerprints, each 32 upper-case hex pairs separated by colons. Type: object Required fields: ["package","sha256_cert_fingerprints"] Additional properties: false |
| / |
Type: string |
| / |
Type: array Minimum items: 1 Maximum items: 10 |
| / |
Type: string |
| / |
The Google client identifiers a Google ID token names as its audience. Type: array Maximum items: 10 |
| / |
Type: string |
| / |
The oldest app version the router admits, as `major.minor.patch`. Type: string |
| / |
An `https` URL where a refused client is sent to update. Type: string |
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"] Additional properties: false |
| / |
Type: string |
| / |
$ref: #realm_sign_in_methods |
| / |
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 |
| / |
The builder realm alone, where the operator recorded it: whether the public website is open to every visitor (ACS-L0-07). Type: boolean |
| / |
Type: integer Minimum: 1 |
| / |
Type: integer Minimum: 1 Maximum: 30 |
| / |
The realm's work-account route as declared, its client secret named in the application's custody scope and never answered as a value. $ref: #realm_entra |
| / |
The realm's Sign in with Apple route: 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 |
| / |
$ref: #realm_client |
| / |
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 |
| / |
$ref: #/shapes/page |
| / |
Present only where the call raised a client's `minimum_version` over versions its requests stated within the last day. The write stands; each warning names who is refused from now on. Type: array Minimum items: 1 |
| / |
Type: object Required fields: ["code","client_id","versions"] Additional properties: false |
| / |
A raised minimum refuses versions seen within the last day. Required value: clients_in_use |
| / |
The declared client whose minimum was raised. Type: string |
| / |
The versions seen within the last day that the new minimum refuses and the previous one admitted, highest first. Type: array Minimum items: 1 |
| / |
Type: string |
Complete payload contract
{
"request": {
"type": "object",
"required": [],
"properties": {
"application": {
"type": "string",
"description": "The application id whose realm to configure (see `list_applications`); its manifest must declare the accounts service."
},
"sign_in_methods": {
"$anchor": "realm_sign_in_methods",
"type": "array",
"items": {
"enum": [
"google",
"github",
"passkey",
"email",
"entra",
"apple"
]
},
"description": "The enabled sign-in methods, replacing the current set. An empty set admits no sign-in, and `passkey` alone is refused. Naming `entra` or `apple` needs that member in this call or an earlier one. An invitation-only realm refuses `entra`, and a workforce audience allows `entra` alone."
},
"creation": {
"enum": [
"open",
"invited"
],
"description": "Who may create an account by signing in: `open`, anyone, the default, or `invited`, only the holder of an invitation from `issue_invitation`. Under a manifest's `invited` audience `open` is refused `creation_contradicts_audience`."
},
"limits": {
"type": "object",
"properties": {
"creation_ceiling": {
"type": [
"integer",
"null"
],
"minimum": 1,
"description": "End-user realm: most accounts (1000 unset). Builder realm: most open sign-ups."
},
"signin_starts_per_hour": {
"type": "integer",
"minimum": 1,
"description": "Sign-in starts allowed per source address per hour; 30 where none is set."
},
"code_sends_per_hour": {
"type": "integer",
"minimum": 1,
"description": "Emailed sign-in codes sent per address per hour; 5 where none is set, and at most 30."
},
"site_public": {
"type": [
"boolean",
"null"
],
"description": "The builder realm alone, with no application. Refused by name on an application's realm."
}
},
"additionalProperties": false,
"description": "The realm's limits. Pass only the members you change."
},
"invitation_days": {
"type": "integer",
"minimum": 1,
"description": "How many days an invitation from `issue_invitation` stays redeemable; 14 where none is set."
},
"session_days": {
"type": "integer",
"minimum": 1,
"maximum": 30,
"description": "How many days a session the realm opens lives: 30 where none is set."
},
"entra": {
"$anchor": "realm_entra",
"type": "object",
"description": "The work-account route for a company's Microsoft Entra tenant.",
"required": [
"tenant",
"client_id",
"client_secret_name"
],
"properties": {
"tenant": {
"type": "string",
"description": "The Microsoft Entra tenant id, a GUID."
},
"client_id": {
"type": "string",
"description": "The client id of the app registration in that tenant."
},
"client_secret_name": {
"type": "string",
"description": "The name the client secret was stored under with `store_secret` naming this application — the name, never the value."
}
},
"additionalProperties": false
},
"apple": {
"type": "object",
"description": "Sign in with Apple.",
"required": [
"services_id",
"team_id",
"key_id",
"key_secret_name"
],
"properties": {
"services_id": {
"type": "string",
"description": "The Services ID registered with Apple for the web sign-in."
},
"team_id": {
"type": "string",
"pattern": "^[A-Z0-9]{10}$",
"description": "The developer team's ten-character identifier."
},
"key_id": {
"type": "string",
"pattern": "^[A-Z0-9]{10}$",
"description": "The Sign in with Apple key's ten-character identifier."
},
"key_secret_name": {
"type": "string",
"description": "The name the key's `.p8` text was stored under with `store_secret` naming this application — the name, never the value."
}
},
"additionalProperties": false
},
"environment": {
"type": "string",
"pattern": "^(development|production)$",
"description": "The environment whose realm the call addresses, `development` or `production`; absent, `production`."
},
"session_cap_days": {
"type": "integer",
"minimum": 1,
"maximum": 730,
"description": "How many days a native session may run from its creation: 365 where none is set, and no smaller than `session_days`."
},
"clients": {
"type": "array",
"maxItems": 10,
"description": "The realm's native public clients, at most ten, replacing the current list. On one environment the production realm takes both builds' redirect URIs; with development turned on, the development realm takes the debug build's and the production realm the store build's.",
"items": {
"$anchor": "realm_client",
"type": "object",
"required": [
"client_id",
"redirect_uris"
],
"properties": {
"client_id": {
"type": "string",
"description": "The client's identifier: 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: a reverse-domain custom scheme, 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": "The iOS app's bundle identifier and its ten-character team identifier."
},
"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": "The Android app's package name and its signing-certificate SHA-256 fingerprints, each 32 upper-case hex pairs separated by colons."
},
"google_client_ids": {
"type": "array",
"maxItems": 10,
"items": {
"type": "string"
},
"description": "The Google client identifiers a Google ID token names as its audience."
},
"minimum_version": {
"type": "string",
"description": "The oldest app version the router admits, as `major.minor.patch`."
},
"update_url": {
"type": "string",
"description": "An `https` URL where a refused client is sent to update."
}
},
"additionalProperties": false
}
}
},
"x-renamed": {
"routes": "sign_in_methods"
},
"additionalProperties": false
},
"response": {
"type": "object",
"required": [
"contract_version",
"realm"
],
"properties": {
"contract_version": {
"const": 1
},
"realm": {
"type": "object",
"required": [
"realm",
"sign_in_methods",
"creation",
"limits"
],
"properties": {
"realm": {
"type": "string"
},
"sign_in_methods": {
"$ref": "#realm_sign_in_methods"
},
"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)."
},
"site_public": {
"type": "boolean",
"description": "The builder realm alone, where the operator recorded it: whether the public website is open to every visitor (ACS-L0-07)."
}
},
"additionalProperties": false
},
"invitation_days": {
"type": "integer",
"minimum": 1
},
"session_days": {
"type": "integer",
"minimum": 1,
"maximum": 30
},
"entra": {
"$ref": "#realm_entra",
"description": "The realm's work-account route as declared, its client secret named in the application's custody scope and never answered as a value."
},
"apple": {
"type": "object",
"description": "The realm's Sign in with Apple route: 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": {
"$ref": "#realm_client"
}
}
},
"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"
},
"page": {
"$ref": "#/shapes/page"
},
"warnings": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"required": [
"code",
"client_id",
"versions"
],
"properties": {
"code": {
"const": "clients_in_use",
"description": "A raised minimum refuses versions seen within the last day."
},
"client_id": {
"type": "string",
"description": "The declared client whose minimum was raised."
},
"versions": {
"type": "array",
"minItems": 1,
"items": {
"type": "string"
},
"description": "The versions seen within the last day that the new minimum refuses and the previous one admitted, highest first."
}
},
"additionalProperties": false
},
"description": "Present only where the call raised a client's `minimum_version` over versions its requests stated within the last day. The write stands; each warning names who is refused from now on."
}
},
"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