Keep installed clients compatible #
On this page
Prompt:
Stop app versions older than 2.3.0 from calling the backend, and send those users to the store.
Also works: "Which versions of our app are people still using?" "Can I ship this backend change without breaking the old app?" "Force an update of the mobile app."
The app sends its identity and version on every call, in the header x-turnzero-cloud-client (step 1). read_app_sign_in shows which versions are in use (step 2). configure_app_sign_in raises the minimum version (step 3). After that, the platform refuses a request from an older version with status 426 and your store link, and the app opens the link.
What your AI tool does #
- Reads the
mobile-backendskill (read_context, idskill:mobile-backend) and follows its version rules. - Calls
configure_app_sign_inwith the client'sminimum_versionandupdate_urlon the environment's realm, and reports anywarningsthe call returns. - Reads the
x-turnzero-cloud-versionheader on a backend response to confirm which deployed version handled it. - Asks you for the new minimum and the store link. Before it changes the minimum or the backend, it tells you which installed versions the change would refuse.
What you need #
- A native app declared on the realm with its
client_id, as Sign in from a native app describes. - The app's store link, where a refused user is sent to update.
Before your AI starts #
For the AI tool: Check the following before starting.
- A connected, signed-in AI tool (Connect your AI assistant).
- The realm's declared clients, read with
read_app_sign_inon each environment. - The app's release version, in the
major.minor.patchform the store build uses.
Steps #
1. Send the version header from the app #
The app sends its identity and version on every request to the backend, in the header x-turnzero-cloud-client. The value is the declared client_id, a slash, and the app's version, such as com.example.app/2.3.1. The version is major.minor.patch. It may add a pre-release label, such as 2.4.0-beta.1. A pre-release counts as lower than its release, so 2.4.0-beta.1 is below 2.4.0.
Set the header in the one function the app uses for every backend request, next to the bearer token. Handle the refusal from step 3 in the same function. This sample is that function in JavaScript. session and showUpdateScreen are your app's own.
const CLIENT = 'com.example.app/2.3.1';
export async function api(path, init = {}) {
const response = await fetch(`https://<label>.ai.host${path}`, {
...init,
headers: { ...init.headers, authorization: `Bearer ${session.token}`, 'x-turnzero-cloud-client': CLIENT },
});
if (response.status === 426) {
// Below the minimum version: send the user to the store, and never retry the request.
const { update_url } = await response.json();
showUpdateScreen(update_url);
throw new Error('client_upgrade_required');
}
return response;
}
The version check lets a request through if the header is missing, names an undeclared client, or has an unrecognized format. Other access checks still apply. Your backend receives the header as the app sent it.
2. Read the versions in use #
The platform records which versions of each declared client send requests. It updates this record at most once a minute. read_app_sign_in lists the versions seen in the last day under each client, in versions_seen, highest version first.
{
"client_id": "com.example.app",
"redirect_uris": ["com.example.app:/callback"],
"minimum_version": "2.0.0",
"update_url": "https://apps.apple.com/app/id123456789",
"versions_seen": [
{ "version": "2.3.1", "last_seen": "2026-09-27T09:41:00.000Z" },
{ "version": "2.2.0", "last_seen": "2026-09-27T08:15:00.000Z" }
]
}
A version leaves the list a day after its last request. The list holds at most fifty versions per client at a time, and a further version is not recorded. Each environment's realm keeps its own list, so read the realm of the environment you are changing.
3. Raise the minimum version #
Call configure_app_sign_in with the client's minimum_version and its update_url. The change takes effect at once, with no deploy. Use configure_app_sign_in the same way to lower or remove the minimum. The clients list you send replaces the whole list, so send every client with all its current fields.
Your app's manifest may list this environment's clients in its realm member. If so, you still set the minimum with configure_app_sign_in. The call sends every listed client with the fields the manifest gives it, in any order. It changes only minimum_version and update_url. Also send every client's current minimum_version and update_url: a client the call lists without them loses them. Each later submission of the manifest keeps the raised minimum and the update URL.
Also raise the minimum when a contract version of a backend package that your app build depends on is retired at the end of its compatibility window. Set the minimum to the first app version built against a contract still in service. The platform enforces the declared value.
If the new minimum refuses versions seen in the last day that the old minimum accepted, the response lists them in warnings. The change still takes effect.
{
"warnings": [
{ "code": "clients_in_use", "client_id": "com.example.app", "versions": ["2.2.0"] }
]
}
Cloud checks the version on requests to your backend. If a declared client sends a version below the minimum, Cloud returns HTTP 426 (client_upgrade_required) before the request reaches your code or counts against a request limit. The version check skips the realm's own routes under /__account/, the sign-in's authorization, token, and revocation endpoints among them. An older build can sign in, then get 426 on its first backend request that sends the version header.
{
"error": "client_upgrade_required",
"detail": "Version 2.2.0 of com.example.app is below 2.3.0, the oldest version this application accepts; update the app at https://apps.apple.com/app/id123456789 and try again.",
"minimum_version": "2.3.0",
"update_url": "https://apps.apple.com/app/id123456789"
}
Show the user a screen that opens update_url, and do not retry the request. update_url is null if the client declares no update URL.
If iOS and Android share a client_id, they share one update_url. Give each platform its own client_id for separate store links, or use one update page that sends people to the right store.
4. Read the version that responded #
Every response from your backend includes the header x-turnzero-cloud-version. Its value is the deployed version that handled the request, numbered as list_versions numbers it. An environment with no deployed version responds without this header.
5. Before a promote #
A promote changes the backend that every installed app calls. On an application with one environment, each deploy goes straight to production and does the same. First read the versions in use on the production realm. If the new backend drops something an installed version still calls, act first. Raise the minimum, or keep the backend compatible. A quiet day does not prove that no installed copy still needs the old behavior.
A deploy, a promote, or a rollback never changes a minimum version, and none of them gives a warning.
Expected result #
Each request from the app carries x-turnzero-cloud-client, and read_app_sign_in lists that version in the client's versions_seen. After you raise the minimum, the platform refuses a request from an older version with status 426 and the store link. A request from a current version reaches the backend, and the response names the deployed version that served it.
Refusals #
See the refusals reference for other platform errors.
| Refusal | Status | Cause | Remedy |
|---|---|---|---|
client_upgrade_required |
426 | The app sent a version below its client's minimum_version on this realm. |
Update the app from update_url. If you did not mean to refuse that version, lower the minimum with configure_app_sign_in. |
invalid_request |
400 | A minimum_version is not major.minor.patch, or an update_url is not an https URL. |
Send minimum_version as the three numbers alone, such as 2.3.0, and update_url as an https store link. |
Related #
- Sign in from a native app declares the client and calls the backend with the bearer token.
- Manage end users lists every realm setting.
- Manage versions and environments covers promotes, rollbacks, and the version history.