mint_upload_grant #
On this page
Generated automatically from the published contract sources.
A script calls this action over HTTPS at POST https://tzcloud.turnzero.ai/v1/mint_upload_grant, with a bearer credential and the action's payload as the JSON body. An MCP connection lists this action as the tool tzcloud_mint_upload_grant.
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 #
Create a single-use upload grant for one file or deploy ZIP in an application's storage area, without a long-lived token. It expires after five minutes by default. Declare the area bound to this application first. For a ZIP, upload then call deploy with artifact: { area, name, hash }. The file counts as stored data. Over quota, upload refuses usage_over_quota.
The grant appears once. Run command_npx (command_npx_windows on Windows), or installed command or command_windows, once as returned. If a command cannot run, including missing or refused npx or an incompatible file name, use commands.curl or commands.powershell. They are always returned for POSIX shells and Windows PowerShell respectively. Each sends the grant as bearer with no other header.
With no shell, get the page's address from read_status's dashboard, passing brief: false. Ask your user to open it after signing in and use Upload a file. Do not call this tool for that upload.
More about this action #
Pass the application, a storage area bound to it, and the file's name. The file goes to the partition environment gives. Where you give none, it goes to the partition of the environment the application's deploys go to: production on an application with one environment, development on one with two. The write records the identity deploy, unless identity gives another.
The application's own platform credential cannot call this tool.
The local_path argument: the command passes it as its --path option, and both commands read it. Without it, each reads the file named by the last segment of name, in the folder it runs in. The platform never reads the path. A path that contains a control character, a double quote, $, a backtick, %, !, &, |, <, >, ^, a typographic double quote, a doubled backslash, or a trailing backslash is refused invalid_request. So is ~, or a path that opens with ~/ or ~\, because no shell expands those in double quotes.
The one write that lands uses the grant up. The answer also gives the grant's expiry, the size it accepts, and the file's whole address.
Pass local_path, the file on your machine, where it is not the name's last segment in the folder the command runs from. If an upload's outcome is unknown, mint a new grant and upload with its new command; do not repeat the old single-use command. The answer's max_bytes is the upload bound; a larger body is refused request_too_large.
Access and action metadata #
{
"name": "mint_upload_grant",
"resource": "environment",
"tier": "reversible",
"surface": "tzcloud",
"addresses": [
"tzcloud"
],
"product": "cloud",
"clients": [
"bearer",
"browser_session"
],
"summary": "Mint an upload grant for one file of a declared storage area bound to the named application: a single-use bearer credential for one PUT of that file, expiring after the configured lifetime, five minutes by default. It is admitted to the credentials `deploy` admits for that application, a deploy upload's grant aside, and the application's platform credential is refused. The file goes to the partition `environment` gives, or, where it gives none, to that of the environment the application's deploys go to; the write records the identity deploy unless `identity` gives another.\n\nThe answer carries the grant once, its expiry, the size it admits, and the file's whole address. Where the file's name allows them, it also returns four command forms. `command_npx` uploads the file with turnzero's `put`; `command_npx_windows` is its Windows form. `command` and `command_windows` use the installed turnzero command. An optional `local_path` is the file the command reads. A path outside its allowed form is refused `invalid_request`, so no grant is minted. Where the file's name holds a character a command cannot carry alike in every shell, none of the four command forms is returned. Two ready commands are returned either way: `curl` for a POSIX shell, and Windows PowerShell's `Invoke-WebRequest -UseBasicParsing`, each sending the grant as the bearer and no other header. The one write that lands spends the grant, and every other route refuses it.\n\nWith no shell, get the page's address from `read_status`'s `dashboard`, passing `brief: false`. Ask your user to open it after signing in and use Upload a file; do not call this tool for that upload.",
"annotations": {
"readOnlyHint": false,
"destructiveHint": false,
"openWorldHint": false
}
}
MCP catalog entry #
{
"name": "mint_upload_grant",
"title": "Create file upload link",
"tier": "reversible",
"scenario": "OST-L0-08",
"summary": "Create a single-use upload grant for one file or deploy ZIP in an application's storage area, without a long-lived token. It expires after five minutes by default. Declare the area bound to this application first. For a ZIP, upload then call `deploy` with `artifact: { area, name, hash }`. The file counts as stored data. Over quota, upload refuses `usage_over_quota`.\n\nThe grant appears once. Run `command_npx` (`command_npx_windows` on Windows), or installed `command` or `command_windows`, once as returned. If a command cannot run, including missing or refused npx or an incompatible file name, use `commands.curl` or `commands.powershell`. They are always returned for POSIX shells and Windows PowerShell respectively. Each sends the grant as bearer with no other header.\n\nWith no shell, get the page's address from `read_status`'s `dashboard`, passing `brief: false`. Ask your user to open it after signing in and use Upload a file. Do not call this tool for that upload.",
"owners": [
"OST-L0-08",
"OST-L0-03",
"OST-L0-02",
"OST-L0-04",
"API-L0-17",
"SEC-L0-07",
"PLD-L0-40"
]
}
request #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["application","area","name"] |
| / |
The id of the application the upload is for, from list_applications. The area must be bound to it.Type: string |
| / |
Target area declared for this application with declare_storage_area; undeclared_area if absent, area_scope_refused if bound elsewhere or the platform's export area.Type: string Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$ |
| / |
The file's name within the area, verbatim, slashes included, and the one file the grant reaches; a name a write refuses, one holding a backslash or a segment that ends with a dot, is refused. A write replaces that stored file irreversibly. Type: string Minimum length: 1 |
| / |
The environment whose partition of the area receives the file; absent, the application's deploy target, the partition its deploy reads an artifact from. A stored entry in deploy_files reads its deploy target's partition.Type: string Pattern: ^(development|production)$ |
| / |
The acting identity the write records, fixed by the grant, so the upload sends no identity header. Type: string Minimum length: 1 |
| / |
The file on your machine to upload, absolute or relative to the folder the line runs in; absent, the file named by the last segment of name, in that folder. A path the pattern refuses, ~, or one opening with ~/ or ~\ is refused invalid_request.Type: string Minimum length: 1 Maximum length: 1024 Pattern: ^(?:[^"$`%!&\|<>^\u201c-\u201e\u0000-\u001f\u007f\\]|\\[^"$`%!&\|<>^\u201c-\u201e\u0000-\u001f\u007f\\])+$ |
response #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["contract_version","grant","expires_at","max_bytes","address","commands"] |
| / |
Required value: 1 |
| / |
The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call. Type: string Pattern: ^[0-9a-f]{10}$ |
| / |
The grant's value, returned this once and held by no record: the bearer of one PUT to address.Type: string |
| / |
When the grant stops serving, as an ISO 8601 instant. An unspent grant past it is refused transfer_grant_expired.Type: string |
| / |
The most bytes the one write may carry, the configured bound. Type: integer |
| / |
The file's whole address on the platform's public origin, each segment of its name escaped. Type: string |
| / |
One line, for macOS and Linux, that uploads the file with the turnzero command's put: echo <grant> | turnzero put --area <area> --name <name>, then --origin <origin> off https://turnzero.ai, then --path "<file>", the file both commands read. Run it once, as given, before expires_at. It reads the grant on its standard input and writes the file, ending 0 where the file was written, 2 where that is unknown, and 3 where nothing was written. Absent where the file's name holds a character one line cannot carry alike in every shell, a space among them; commands are present either way.Type: string |
| / |
Present with command: the same line for every Windows shell, with turnzero.cmd where its head says turnzero. On Windows, run this one in command's place, once, as given. The four line members are one command line, so a run of any whose write lands spends the grant.Type: string |
| / |
The same line run through npx, npx --no-update-notifier -y turnzero@<tag> in place of turnzero, the tag latest on production's platform and next on every other. It is present exactly where command is. Run this line first, or command_npx_windows on Windows; it runs whether or not the command is installed. If npx can't run, use command where turnzero --version responds; else use commands.curl in a POSIX shell or commands.powershell in Windows PowerShell. With no shell, the person uses Upload a file on the application's signed-in page. Run npm install -g turnzero@<tag> only if the person wants to keep it. If your tool's permissions blocked the command, tell the person which route you took. A person or a job may run any of the four forms.Type: string |
| / |
command_npx's line for every Windows shell, with npx.cmd where its head says npx.Type: string |
| / |
Type: object Required fields: ["curl","powershell"] Additional properties: false |
| / |
A curl command for a POSIX shell: the grant in the Authorization header, and as the body the file local_path gives, or else the file whose name is the last segment of name, in the folder it runs in.Type: string |
| / |
An Invoke-WebRequest command for Windows PowerShell, with -UseBasicParsing, which Windows PowerShell 5.1 needs: the same header and the same file. Type: string |
| / |
Gives the file, its partition, and the identity, and says that the one write that lands spends the grant and that it expires at expires_at. It then gives the line to run, or says why none is returned, and the local file each reads.Type: string |
Complete payload contract #
{
"request": {
"type": "object",
"required": [
"application",
"area",
"name"
],
"properties": {
"application": {
"type": "string",
"description": "The id of the application the upload is for, from `list_applications`. The area must be bound to it."
},
"area": {
"type": "string",
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$",
"description": "Target area declared for this application with `declare_storage_area`; `undeclared_area` if absent, `area_scope_refused` if bound elsewhere or the platform's export area."
},
"name": {
"type": "string",
"minLength": 1,
"description": "The file's name within the area, verbatim, slashes included, and the one file the grant reaches; a name a write refuses, one holding a backslash or a segment that ends with a dot, is refused. A write replaces that stored file irreversibly."
},
"environment": {
"type": "string",
"pattern": "^(development|production)$",
"description": "The environment whose partition of the area receives the file; absent, the application's deploy target, the partition its deploy reads an artifact from. A stored entry in `deploy_files` reads its deploy target's partition."
},
"identity": {
"type": "string",
"minLength": 1,
"description": "The acting identity the write records, fixed by the grant, so the upload sends no identity header."
},
"local_path": {
"type": "string",
"minLength": 1,
"maxLength": 1024,
"pattern": "^(?:[^\"$`%!&\\|<>^\\u201c-\\u201e\\u0000-\\u001f\\u007f\\\\]|\\\\[^\"$`%!&\\|<>^\\u201c-\\u201e\\u0000-\\u001f\\u007f\\\\])+$",
"description": "The file on your machine to upload, absolute or relative to the folder the line runs in; absent, the file named by the last segment of `name`, in that folder. A path the pattern refuses, `~`, or one opening with `~/` or `~\\` is refused `invalid_request`."
}
}
},
"response": {
"type": "object",
"required": [
"contract_version",
"grant",
"expires_at",
"max_bytes",
"address",
"commands"
],
"properties": {
"contract_version": {
"const": 1
},
"reference": {
"type": "string",
"pattern": "^[0-9a-f]{10}$",
"description": "The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call."
},
"grant": {
"type": "string",
"description": "The grant's value, returned this once and held by no record: the bearer of one PUT to `address`."
},
"expires_at": {
"type": "string",
"description": "When the grant stops serving, as an ISO 8601 instant. An unspent grant past it is refused `transfer_grant_expired`."
},
"max_bytes": {
"type": "integer",
"description": "The most bytes the one write may carry, the configured bound."
},
"address": {
"type": "string",
"description": "The file's whole address on the platform's public origin, each segment of its name escaped."
},
"command": {
"type": "string",
"description": "One line, for macOS and Linux, that uploads the file with the turnzero command's `put`: `echo <grant> | turnzero put --area <area> --name <name>`, then `--origin <origin>` off `https://turnzero.ai`, then `--path \"<file>\"`, the file both `commands` read. Run it once, as given, before `expires_at`. It reads the grant on its standard input and writes the file, ending 0 where the file was written, 2 where that is unknown, and 3 where nothing was written. Absent where the file's name holds a character one line cannot carry alike in every shell, a space among them; `commands` are present either way."
},
"command_windows": {
"type": "string",
"description": "Present with `command`: the same line for every Windows shell, with `turnzero.cmd` where its head says `turnzero`. On Windows, run this one in `command`'s place, once, as given. The four line members are one command line, so a run of any whose write lands spends the grant."
},
"command_npx": {
"type": "string",
"description": "The same line run through npx, `npx --no-update-notifier -y turnzero@<tag>` in place of `turnzero`, the tag `latest` on production's platform and `next` on every other. It is present exactly where `command` is. Run this line first, or `command_npx_windows` on Windows; it runs whether or not the command is installed. If npx can't run, use `command` where `turnzero --version` responds; else use `commands.curl` in a POSIX shell or `commands.powershell` in Windows PowerShell. With no shell, the person uses Upload a file on the application's signed-in page. Run `npm install -g turnzero@<tag>` only if the person wants to keep it. If your tool's permissions blocked the command, tell the person which route you took. A person or a job may run any of the four forms (PLD-L0-94)."
},
"command_npx_windows": {
"type": "string",
"description": "`command_npx`'s line for every Windows shell, with `npx.cmd` where its head says `npx` (PLD-L0-94)."
},
"commands": {
"type": "object",
"required": [
"curl",
"powershell"
],
"properties": {
"curl": {
"type": "string",
"description": "A curl command for a POSIX shell: the grant in the Authorization header, and as the body the file `local_path` gives, or else the file whose name is the last segment of `name`, in the folder it runs in."
},
"powershell": {
"type": "string",
"description": "An Invoke-WebRequest command for Windows PowerShell, with -UseBasicParsing, which Windows PowerShell 5.1 needs: the same header and the same file."
}
},
"additionalProperties": false
},
"detail": {
"type": "string",
"description": "Gives the file, its partition, and the identity, and says that the one write that lands spends the grant and that it expires at `expires_at`. It then gives the line to run, or says why none is returned, and the local file each reads."
}
}
}
}
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