Management action tiers and approvals

A management action tier is the class the platform's catalog gives every management action: observe, reversible, or destructive. This page explains the three tiers and the pending action, the record through which a destructive action runs only after a person approves it in the browser. It also lists the credentials each caller acts under.

The three management action tiers

Every management action has a tier set by the platform's catalog:

  • Observe reads state without changing it. Examples include read_status, read_logs, list_applications, and list_secrets.
  • Reversible performs its operation with no browser approval step. Examples include deploy, promote, roll_back, create_environment, halt_environment, resume_environment, revoke_realm_keys, submit_manifest, store_secret, and configure_realm. Retry behaviour belongs to each action: do not assume that repeating a call has no further effect, or that the tier offers a general undo. A response that is not the platform's own, such as a gateway's error page or a closed connection, says nothing about whether the action ran. Read its status before repeating it.
  • Destructive needs a person's approval in the browser before it runs. Examples include delete_application, delete_environment, rename_application, purge_logs, delete_end_user, and delete_account. A rename permanently retires both previous hostnames, the production one and the development one.

The read to make before repeating depends on the action:

  • deploy, promote, roll_back, and restart_application: read_status with wait_seconds.
  • run_schedule: read_schedules, and repeat the call only with the same request_id.
  • Another reversible action: read what it changes before repeating it, such as list_secrets for store_secret and read_realm for configure_realm.

An action is complete when the operation it defines is complete, which is not always the end of the work it starts:

  • run_schedule starts a run and returns the run's current record, while the scheduled job may still be running. It requires request_id, and repeating that identifier returns the same run. With wait_seconds, the response waits while the run runs, and settled says whether the record it returns has ended. Where it has not, read_schedules reports the job's final outcome. Every response is 200.
  • deploy and promote return 202 with state: "deploying" once their checks pass, and the work continues on the platform. With wait_seconds, the response waits while the work runs. It is 200 with deployed or failed where the work ended within the wait, and otherwise 202 with next. Read the result with read_status or list_versions.

The catalog also lists actions no build serves: the tool list leaves them out, and a call to one answers 501 not_yet_provisioned. Check an action's page in the action reference before you rely on it. Renaming or removing an action, or changing its tier, is a versioned change to the catalog.

The pending action

Calling a destructive action asks for approval; it does not run the action. The platform creates a pending-action record and returns its description of the proposed changes, with an approval link. A signed-in person approves or declines on the platform's browser page. No tool, resource, prompt, or token can approve an action. read_pending_action, given the returned record identifier, reads the record's state and outcome.

Supply your own request_id so a retry is recognised. For the same requesting account and action, a repeated identifier returns the existing record while that record is live: requested, approved, or executing. Without an identifier, each call creates a new record.

When the subject changes before approval

The subject can change between the request and the approval, for example after a deploy or a change to an application's storage. At approval, the platform describes the subject again and compares the two descriptions. If they differ:

  • the record ends declined with the outcome description_changed;
  • both descriptions are returned; and
  • the action does not run.

To go ahead, request the action again and approve its current description.

What runs after approval

The approved description binds what runs. After approval, the action runs from what the record stored: the subject, the input, and the state the description was drawn from, never a fresh reading of the subject. rename_application takes the hostname it retires from the approved description. If another rename or a deletion changed the application after the approval, the rename changes nothing and returns renamed: false with the reason.

When execution is interrupted

If execution is interrupted, the record can stay executing. A recovery pass runs when the service starts and every ten minutes. It marks a record that has been executing for more than thirty minutes as failed, with the outcome interrupted.

That outcome does not prove that nothing changed before the interruption. Read the record and check the current subject before you retry. A new request after a failure creates a new pending action; give it a fresh request_id to tell the attempts apart. Every new attempt still needs a person's approval in the browser.

Credentials

What a caller may do depends on its credential, the credential's scope, and its grants. Requests to the management Hypertext Transfer Protocol (HTTP) application programming interface (API), and your tool's Model Context Protocol (MCP) requests, include a bearer credential. The HTTP API also accepts a signed-in page's API cookie on a same-origin JSON post, and browser pages use cookies.

  • Browser cookies and Open Authorization (OAuth) session tokens, issued at sign-in, authenticate browser pages, your tool, and management HTTP requests. A signed-in session has the destructive grant.
  • A minted token is for unattended use: a script, a pipeline, or a contractor's tool. It is bounded to the whole account or to one application and has only the grants the minting session had and asked for. You can revoke it at any time. A token bounded to one application cannot halt production: halt_environment on production under it is refused 403 account_credential_required. Mint a token shows how to mint one.
  • A token with the issues grant reaches one issue space of your account and nothing else. An issue space contains issues and the reports filed about them. Any signed-in session of the account can mint one, giving the space and a grant level (Mint a token). The account must have Turn Zero Blueprint, by invitation during the private beta. Otherwise the mint and every relay_issue_act call are refused 403 blueprint_required.
  • The application's platform credential is what a running backend calls the platform with, supplied as TURNZERO_CLOUD_TOKEN. There is one per environment. The provision line your tool runs re-mints the development value with rotate_secret over the HTTP API; the production value is never shown.
  • An end-user session, issued by an application's own realm, identifies a user of that application. It does not authorize management actions.

Sign-in, sessions, and tokens explains how each credential is obtained, how long it lasts, and what ends it.

The same tier and grant checks apply whether a person or a program sends the request. A minted token needs the destructive grant to request a destructive action, and it still cannot approve that action.

Actions for platform staff

The catalog also contains actions that only Turn Zero's own staff can use. They need grants that exist only in the company's own accounts, which no customer credential has. Your tool does not list them, and a call to one from your tool is treated as a call to an unknown tool. On the management HTTP API, such a call is refused 403 grant_required.

issue_invitation, revoke_invitation, list_invitations, and configure_realm called with no application apply to the platform's own realm, which only platform staff manage. From a signed-in session or an account-wide token they are refused grant_required, and from a token bound to one application they are refused token_scope_refused. Name your application to reach your own application's realm.

The feedback queue is platform staff's too, under a grant of its own, feedback_queue. Under it, read_feedback reads the queue and any issue of the platform's own issue space by its id, and settle_feedback settles a report in that space. The grant allows no other staff or account action.

From a signed-in session or an account-wide token, reading the queue and settling in the platform's space are refused grant_required naming feedback_queue. A request by id for a report another account filed returns not_found, never grant_required. From a token bound to one application, reading the queue and settling are refused token_scope_refused.

Your own reports and the spaces your account has need no grant. Without queue, read_feedback returns your own reports. With space, the feedback actions read and write a space your account has (Feedback and ratings). A token bounded to one application is refused them and reaches its space through the gateway.

The company's own test harness has two staff actions too, both under the grant platform staff give their test harnesses. One posts each run of a monitored check into the platform's issue space, and the other tells platform staff how a harness's run ended. Your tool lists neither.

What is recorded

Every action writes a record that is never changed afterwards. It contains the actor, the exact credential used (not only its kind), the action, its subject, the outcome, and any confirmation. An action reports success only when it completed fully; otherwise it reports a failure that states what did not complete.

  • Sign-in, sessions, and tokens explains how each credential is obtained, how long it lasts, and what ends it.
  • Mint a token explains how to mint a token bounded to the account or to one application for a script, a pipeline, or a contractor's tool.
  • Applications and environments describes the three destructive actions on an application: deleting it, deleting its development environment, and renaming it.
  • Feedback and ratings explains how a report is filed and which feedback reads are platform staff's.
  • Actions lists every management action with its inputs and outputs.