configure_app_sign_in #

View this page as Markdown

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
/properties/application Your account's application id from list_applications, not its name or label.

Type: string
/properties/sign_in_methods 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
/properties/sign_in_methods/items Allowed values: ["google","github","passkey","email","entra","apple"]
/properties/creation open admits anyone, invited only invitation holders. An invited audience refuses open with creation_contradicts_audience. Invitation-only refuses entra.

Allowed values: ["open","invited"]
/properties/limits Type: object
Additional properties: false
/properties/limits/properties/creation_ceiling Maximum accounts, or open builder sign-ups.

Type: ["integer","null"]
Minimum: 1
/properties/limits/properties/signin_starts_per_hour Per source address.

Type: integer
Minimum: 1
/properties/limits/properties/code_sends_per_hour Per email address, at most 30.

Type: integer
Minimum: 1
/properties/limits/properties/site_public Builder realm only. Refused on end-user realms.

Type: ["boolean","null"]
/properties/invitation_days Type: integer
Minimum: 1
/properties/session_days Type: integer
Minimum: 1
Maximum: 30
/properties/entra $anchor: realm_entra
Type: object
Required fields: ["tenant","client_id","client_secret_name"]
Additional properties: false
/properties/entra/properties/tenant Entra tenant GUID.

Type: string
/properties/entra/properties/client_id App registration client id.

Type: string
/properties/entra/properties/client_secret_name Name stored with store_secret, never the secret's value.

Type: string
/properties/apple Type: object
Required fields: ["services_id","team_id","key_id","key_secret_name"]
Additional properties: false
/properties/apple/properties/services_id Web sign-in Services ID.

Type: string
/properties/apple/properties/team_id Type: string
Pattern: ^[A-Z0-9]{10}$
/properties/apple/properties/key_id Type: string
Pattern: ^[A-Z0-9]{10}$
/properties/apple/properties/key_secret_name Name of .p8 key stored with store_secret, never its value.

Type: string
/properties/environment Default production. Development needs create_environment, else environment_not_created.

Type: string
Pattern: ^(development|production)$
/properties/session_cap_days Native session cap from creation, at least session_days.

Type: integer
Minimum: 1
Maximum: 730
/properties/clients Replaces native public clients. The reference says which realm takes each build.

Type: array
Maximum items: 10
/properties/clients/items $anchor: realm_client
Type: object
Required fields: ["client_id","redirect_uris"]
Additional properties: false
/properties/clients/items/properties/client_id Letters, digits and ._:-.

Type: string
/properties/clients/items/properties/redirect_uris 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
/properties/clients/items/properties/redirect_uris/items Type: string
/properties/clients/items/properties/ios Team id has ten characters.

Type: object
Required fields: ["bundle_id","team_id"]
Additional properties: false
/properties/clients/items/properties/ios/properties/bundle_id Type: string
/properties/clients/items/properties/ios/properties/team_id Type: string
/properties/clients/items/properties/android SHA-256 fingerprints use 32 uppercase hex pairs separated by colons.

Type: object
Required fields: ["package","sha256_cert_fingerprints"]
Additional properties: false
/properties/clients/items/properties/android/properties/package Type: string
/properties/clients/items/properties/android/properties/sha256_cert_fingerprints Type: array
Minimum items: 1
Maximum items: 10
/properties/clients/items/properties/android/properties/sha256_cert_fingerprints/items Type: string
/properties/clients/items/properties/google_client_ids Google ID-token audiences.

Type: array
Maximum items: 10
/properties/clients/items/properties/google_client_ids/items Type: string
/properties/clients/items/properties/minimum_version Oldest accepted version, major.minor.patch.

Type: string
/properties/clients/items/properties/update_url App update URL, https.

Type: string

response #

JSON pointer Description and constraints
"" (root) Type: object
Required fields: ["contract_version","realm"]
Additional properties: false
/properties/contract_version Required value: 1
/properties/realm Type: object
Required fields: ["realm","sign_in_methods","creation","effective_creation","limits"]
Additional properties: false
/properties/realm/properties/realm Type: string
/properties/realm/properties/sign_in_methods $ref: #realm_sign_in_methods
/properties/realm/properties/creation Allowed values: ["open","invited"]
/properties/realm/properties/effective_creation The creation mode the realm enforces: invited under an invited audience, whatever creation holds; creation otherwise.

Allowed values: ["open","invited"]
/properties/realm/properties/limits Type: object
Required fields: ["creation_ceiling","signin_starts_per_hour","code_sends_per_hour"]
Additional properties: false
/properties/realm/properties/limits/properties/creation_ceiling Type: ["integer","null"]
Minimum: 1
/properties/realm/properties/limits/properties/signin_starts_per_hour Type: integer
Minimum: 1
/properties/realm/properties/limits/properties/code_sends_per_hour Emailed sign-in codes sent per address per hour; 5 where none is set.

Type: integer
Minimum: 1
/properties/realm/properties/limits/properties/site_public The platform's builder realm alone, where the operator recorded it: whether the public website is open to every visitor.

Type: boolean
/properties/realm/properties/invitation_days Type: integer
Minimum: 1
/properties/realm/properties/session_days Type: integer
Minimum: 1
Maximum: 30
/properties/realm/properties/entra 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
/properties/realm/properties/apple 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
/properties/realm/properties/apple/properties/services_id Type: string
/properties/realm/properties/apple/properties/team_id Type: string
/properties/realm/properties/apple/properties/key_id Type: string
/properties/realm/properties/apple/properties/key_secret_name Type: string
/properties/realm/properties/session_cap_days Type: integer
Minimum: 1
Maximum: 730
/properties/realm/properties/clients The declared native clients, each without any secret: a native client holds none.

Type: array
Maximum items: 10
/properties/realm/properties/clients/items $ref: #realm_client
/properties/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.

Type: object
Required fields: ["entra","apple"]
Additional properties: false
/properties/callbacks/properties/entra The work-account route's callback: list it, exactly as returned, as a web redirect URI of your tenant's app registration.

Type: string
/properties/callbacks/properties/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.

Type: string
/properties/detail Type: string
/properties/page $ref: #/shapes/page
/properties/warnings 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
/properties/warnings/items Type: object
Required fields: ["code","client_id","versions"]
Additional properties: false
/properties/warnings/items/properties/code A raised minimum refuses versions seen within the last day.

Required value: clients_in_use
/properties/warnings/items/properties/client_id The declared client whose minimum was raised.

Type: string
/properties/warnings/items/properties/versions The versions seen within the last day that the new minimum refuses and the previous one admitted, highest first.

Type: array
Minimum items: 1
/properties/warnings/items/properties/versions/items 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 #