configure_app_sign_in #
On this page
Generated automatically from the published contract sources.
A script calls this action over HTTPS at POST https://tzcloud.turnzero.ai/v1/configure_app_sign_in, with a bearer credential and the action's payload as the JSON body. An MCP connection lists this action as the tool tzcloud_configure_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).
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 #
Change one environment's end-user sign-in: methods, creation mode, native clients, limits, invitation and session lifetimes, and Entra settings. The account owner must have requested or agreed to the methods in a sign_in_methods change. The manifest must declare accounts.
Manifest-set realm fields are refused manifest_owned_field, except clients' minimum_version and update_url. Only supplied members change. sign_in_methods and clients replace their lists.
The client_secret_name and key_secret_name members each take the name of a secret already stored with store_secret for the same application and environment, never its value. An entra or apple change is followed by check_app_sign_in, then a person's sign-in test.
More about this action #
On sign_in_methods, email is available where the platform has an email sender. Under a manifest's invited audience, both realms are invitation-only whatever creation is set to.
Only this call sets the limits and the lifetimes, never the manifest. The limits.code_sends_per_hour bound is fixed and you cannot raise it. The realm's ceiling is the size's signin-code-sends-per-hour quantity, the same for both sizes. 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 the platform uses it only to sign Apple's client secret. Its services_id is a Services ID such as com.example.app.signin. On an end-user realm, 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. Enter callbacks.entra, exactly as returned, 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. Where the manifest's realm member lists an environment's clients, a call there sends that same list and changes only minimum_version and update_url. A client the call lists without minimum_version or update_url loses that member, because the call replaces the list whole. Each of its redirect_uris is matched exactly, except a loopback URI's port. 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 only creation, limits.creation_ceiling, and limits.site_public. 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 clears it, and where none is set there is no ceiling. 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. The site is public only where it is true and the creation mode is open. False or null returns the site to private, and null removes the member.
The apple member gives 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 that sign in through the realm, each a client_id with its redirect URIs and app signing identities. Raising a client's minimum_version returns warnings, listing the versions in use that it refuses. 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 are refused. An optional environment (development or production; absent, production) chooses the realm you address.
The clients argument: On an environment the manifest's realm member lists, it is that list with only minimum_version and update_url changed. 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.
The application argument: the application id that list_applications returns.
The sign_in_methods argument: an empty set allows no sign-in, and entra or apple needs its member in this call or an earlier one.
The creation argument: open is the default, and invited refuses the work-account route, which a workforce audience needs.
The limits argument: pass only the members you change. Where none is set, an end-user realm's creation_ceiling is 1000, signin_starts_per_hour is 30, and code_sends_per_hour is 5.
The invitation_days argument: the days an invitation invite_end_user issues stays redeemable, 14 where none is set. The session_days argument: 30 where none is set. The session_cap_days argument: 365 where none is set.
A provider secret moved into the realm vault cannot also back an upstream, setting or push provider. Configure each environment separately; development must already have been turned on with create_environment.
The manifest's realm may set sign_in_methods, creation, entra, apple and each environment's clients.
Access and action metadata #
{
"name": "configure_app_sign_in",
"resource": "realm",
"tier": "reversible",
"surface": "tzcloud",
"addresses": [
"tzcloud"
],
"product": "cloud",
"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 returns a warning listing the versions seen within the last day that the new minimum refuses.",
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"openWorldHint": false
}
}
MCP catalog entry #
{
"name": "configure_app_sign_in",
"title": "Configure app sign-in",
"tier": "reversible",
"summary": "Change one environment's end-user sign-in: methods, creation mode, native clients, limits, invitation and session lifetimes, and Entra settings. The account owner must have requested or agreed to the methods in a `sign_in_methods` change. The manifest must declare accounts.\n\nManifest-set realm fields are refused `manifest_owned_field`, except clients' `minimum_version` and `update_url`. Only supplied members change. `sign_in_methods` and `clients` replace their lists.\n\nThe `client_secret_name` and `key_secret_name` members each take the name of a secret already stored with `store_secret` for the same application and environment, never its value. An `entra` or `apple` change is followed by `check_app_sign_in`, then a person's sign-in test.",
"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 |
| / |
Your account's application id from list_applications, not its name or label.Type: string |
| / |
Replaces the list. Empty disables sign-in. passkey alone is refused. entra and apple need prior or supplied configuration. Invitation-only refuses entra. Workforce allows only entra.$anchor: realm_sign_in_methods Type: array |
| / |
Allowed values: ["google","github","passkey","email","entra","apple"] |
| / |
open admits anyone, invited only invitation holders. An invited audience refuses open with creation_contradicts_audience. Invitation-only refuses entra.Allowed values: ["open","invited"] |
| / |
Type: object Additional properties: false |
| / |
Maximum accounts, or open builder sign-ups. Type: ["integer","null"] Minimum: 1 |
| / |
Per source address. Type: integer Minimum: 1 |
| / |
Per email address, at most 30. Type: integer Minimum: 1 |
| / |
Builder realm only. Refused on end-user realms. Type: ["boolean","null"] |
| / |
Type: integer Minimum: 1 |
| / |
Type: integer Minimum: 1 Maximum: 30 |
| / |
$anchor: realm_entra Type: object Required fields: ["tenant","client_id","client_secret_name"] Additional properties: false |
| / |
Entra tenant GUID. Type: string |
| / |
App registration client id. Type: string |
| / |
Name stored with store_secret, never the secret's value.Type: string |
| / |
Type: object Required fields: ["services_id","team_id","key_id","key_secret_name"] Additional properties: false |
| / |
Web sign-in Services ID. Type: string |
| / |
Type: string Pattern: ^[A-Z0-9]{10}$ |
| / |
Type: string Pattern: ^[A-Z0-9]{10}$ |
| / |
Name of .p8 key stored with store_secret, never its value.Type: string |
| / |
Default production. Development needs create_environment, else environment_not_created.Type: string Pattern: ^(development|production)$ |
| / |
Native session cap from creation, at least session_days.Type: integer Minimum: 1 Maximum: 730 |
| / |
Replaces native public clients. The reference says which realm takes each build. Type: array Maximum items: 10 |
| / |
$anchor: realm_client Type: object Required fields: ["client_id","redirect_uris"] Additional properties: false |
| / |
Letters, digits and ._:-.Type: string |
| / |
Reverse-domain custom scheme, https on the app's hostnames or production custom domain, or loopback http on localhost, [::1] or 127.0.0.0/8. Others are refused invalid_redirect_uri.Type: array Minimum items: 1 Maximum items: 20 |
| / |
Type: string |
| / |
Team id has ten characters. Type: object Required fields: ["bundle_id","team_id"] Additional properties: false |
| / |
Type: string |
| / |
Type: string |
| / |
SHA-256 fingerprints use 32 uppercase 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 |
| / |
Google ID-token audiences. Type: array Maximum items: 10 |
| / |
Type: string |
| / |
Oldest accepted version, major.minor.patch.Type: string |
| / |
App update URL, https.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","effective_creation","limits"] Additional properties: false |
| / |
Type: string |
| / |
$ref: #realm_sign_in_methods |
| / |
Allowed values: ["open","invited"] |
| / |
The creation mode the realm enforces: invited under an invited audience, whatever creation holds; creation otherwise.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. Type: integer Minimum: 1 |
| / |
The platform's builder realm alone, where the operator recorded it: whether the public website is open to every visitor. Type: boolean |
| / |
Type: integer Minimum: 1 |
| / |
Type: integer Minimum: 1 Maximum: 30 |
| / |
The realm's work-account route as declared, its client secret given by name in the application's custody scope and never returned 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, 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. Type: object Required fields: ["entra","apple"] Additional properties: false |
| / |
The work-account route's callback: list it, exactly as returned, as a web redirect URI of your tenant's app registration. Type: string |
| / |
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. 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 still applies; each warning identifies 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": "Your account's application `id` from `list_applications`, not its name or label."
},
"sign_in_methods": {
"$anchor": "realm_sign_in_methods",
"type": "array",
"items": {
"enum": [
"google",
"github",
"passkey",
"email",
"entra",
"apple"
]
},
"description": "Replaces the list. Empty disables sign-in. `passkey` alone is refused. `entra` and `apple` need prior or supplied configuration. Invitation-only refuses `entra`. Workforce allows only `entra`."
},
"creation": {
"enum": [
"open",
"invited"
],
"description": "`open` admits anyone, `invited` only invitation holders. An invited audience refuses `open` with `creation_contradicts_audience`. Invitation-only refuses `entra`."
},
"limits": {
"type": "object",
"properties": {
"creation_ceiling": {
"type": [
"integer",
"null"
],
"minimum": 1,
"description": "Maximum accounts, or open builder sign-ups."
},
"signin_starts_per_hour": {
"type": "integer",
"minimum": 1,
"description": "Per source address."
},
"code_sends_per_hour": {
"type": "integer",
"minimum": 1,
"description": "Per email address, at most 30."
},
"site_public": {
"type": [
"boolean",
"null"
],
"description": "Builder realm only. Refused on end-user realms."
}
},
"additionalProperties": false,
"description": ""
},
"invitation_days": {
"type": "integer",
"minimum": 1,
"description": ""
},
"session_days": {
"type": "integer",
"minimum": 1,
"maximum": 30,
"description": ""
},
"entra": {
"$anchor": "realm_entra",
"type": "object",
"description": "",
"required": [
"tenant",
"client_id",
"client_secret_name"
],
"properties": {
"tenant": {
"type": "string",
"description": "Entra tenant GUID."
},
"client_id": {
"type": "string",
"description": "App registration client id."
},
"client_secret_name": {
"type": "string",
"description": "Name stored with `store_secret`, never the secret's value."
}
},
"additionalProperties": false
},
"apple": {
"type": "object",
"description": "",
"required": [
"services_id",
"team_id",
"key_id",
"key_secret_name"
],
"properties": {
"services_id": {
"type": "string",
"description": "Web sign-in Services ID."
},
"team_id": {
"type": "string",
"pattern": "^[A-Z0-9]{10}$",
"description": ""
},
"key_id": {
"type": "string",
"pattern": "^[A-Z0-9]{10}$",
"description": ""
},
"key_secret_name": {
"type": "string",
"description": "Name of `.p8` key stored with `store_secret`, never its value."
}
},
"additionalProperties": false
},
"environment": {
"type": "string",
"pattern": "^(development|production)$",
"description": "Default production. Development needs `create_environment`, else `environment_not_created`."
},
"session_cap_days": {
"type": "integer",
"minimum": 1,
"maximum": 730,
"description": "Native session cap from creation, at least `session_days`."
},
"clients": {
"type": "array",
"maxItems": 10,
"description": "Replaces native public clients. The reference says which realm takes each build.",
"items": {
"$anchor": "realm_client",
"type": "object",
"required": [
"client_id",
"redirect_uris"
],
"properties": {
"client_id": {
"type": "string",
"description": "Letters, digits and `._:-`."
},
"redirect_uris": {
"type": "array",
"minItems": 1,
"maxItems": 20,
"items": {
"type": "string"
},
"description": "Reverse-domain custom scheme, `https` on the app's hostnames or production custom domain, or loopback `http` on `localhost`, `[::1]` or 127.0.0.0/8. Others are refused `invalid_redirect_uri`."
},
"ios": {
"type": "object",
"required": [
"bundle_id",
"team_id"
],
"properties": {
"bundle_id": {
"type": "string"
},
"team_id": {
"type": "string"
}
},
"additionalProperties": false,
"description": "Team id has ten characters."
},
"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": "SHA-256 fingerprints use 32 uppercase hex pairs separated by colons."
},
"google_client_ids": {
"type": "array",
"maxItems": 10,
"items": {
"type": "string"
},
"description": "Google ID-token audiences."
},
"minimum_version": {
"type": "string",
"description": "Oldest accepted version, `major.minor.patch`."
},
"update_url": {
"type": "string",
"description": "App update URL, `https`."
}
},
"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",
"effective_creation",
"limits"
],
"properties": {
"realm": {
"type": "string"
},
"sign_in_methods": {
"$ref": "#realm_sign_in_methods"
},
"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)."
},
"site_public": {
"type": "boolean",
"description": "The platform's 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 given by name in the application's custody scope and never returned 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 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"
},
"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 still applies; each warning identifies 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