list_secrets #
On this page
Generated automatically from the published contract sources.
A script calls this action over HTTPS at POST https://tzcloud.turnzero.ai/v1/list_secrets, with a bearer credential and the action's payload as the JSON body. It also accepts GET. An MCP connection lists this action as the tool tzcloud_list_secrets.
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 #
List stored secrets by name and scope, with settings, fingerprints and consumers. Values are never returned. Use your signed-in connection or an account-wide token. An application-bounded token is refused. applied_settings shows the running copy's bindings. restart_needed flags a value stored after that copy started. For an upstream key, applied_fingerprint is null because the gateway reads its stored value on every call. Compare non-null fingerprints only with the same key id. Equal marks mean the running copy has the stored value. Different marks need restart_application on that environment. End consumer uses before delete_secret.
More about this action #
Each row gives its storage and last rotation times. Platform-managed entries also appear: credential-<application id> at an environment's scope once minted, development's at the first manifest submission and production's at its first deploy. database-<application id> appears where the manifest declares a database. issue-tracking-<application id> appears on an application with its own issue spaces, and issue-space: entries at account scope. They are not yours to delete or bind. Local runs use development-scoped platform credentials, and database credentials where declared, before development is turned on.
fingerprint marks the currently stored value; applied_fingerprint marks what the running copy received. Compare only non-null marks with the same key id, the part before the dot. The marks are keyed and truncated, not values or offline-testable hashes. An upstream key has no applied mark: the gateway reads its stored value on every call.
settings is the recorded manifest's bindings; applied_settings is what the running copy reads. Rotations reach that copy at its next deploy or promote, or at a restart if the copy already holds the binding. restart_application needs the affected environment and is refused during its deploy, promote or restart, or while a halt is in place.
consumers identifies realm, push and upstream uses at an application's environment scope; setting bindings are in settings and applied_settings. At account scope, consumers can be empty even when an upstream uses the value. delete_secret checks all uses and refuses an in-use secret.
With no arguments, it returns every secret of your account at every scope. Pass application, and optionally environment, to narrow it to that application's scopes or one of them.
Access and action metadata #
{
"name": "list_secrets",
"resource": "secret",
"tier": "observe",
"surface": "tzcloud",
"addresses": [
"tzcloud"
],
"product": "cloud",
"clients": [
"bearer",
"browser_session"
],
"summary": "The custody index: names, scopes, and stamps - never values.",
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"openWorldHint": false,
"idempotentHint": true
}
}
MCP catalog entry #
{
"name": "list_secrets",
"title": "List secrets",
"tier": "observe",
"scenario": "EGW-L0-09",
"summary": "List stored secrets by name and scope, with settings, fingerprints and consumers. Values are never returned. Use your signed-in connection or an account-wide token. An application-bounded token is refused. `applied_settings` shows the running copy's bindings. `restart_needed` flags a value stored after that copy started. For an upstream key, `applied_fingerprint` is null because the gateway reads its stored value on every call. Compare non-null fingerprints only with the same key id. Equal marks mean the running copy has the stored value. Different marks need `restart_application` on that environment. End consumer uses before `delete_secret`.",
"owners": [
"SCRT-03",
"MAN-14"
]
}
request #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object |
| / |
Optional: an application id of your account. Pass it and you get that application's secrets alone, at its environment scopes, and no account-scope name; an id no account holds is refused no_such_application, and another account's application_other_account.Type: string |
| / |
Optional, and only with application: the one environment scope of that application to list, development or production; leave it out for both. Refused if given without application.Type: string Pattern: ^(development|production)$ |
response #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["contract_version","secrets"] |
| / |
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}$ |
| / |
Type: array |
| / |
Type: object Required fields: ["name","scope","created_at"] |
| / |
The secret's name. The platform stores credential-<application id> as the application's platform credential at each environment's application scope: production's at its first deploy, development's at the first manifest submission. It stores database-<application id> as the database credential at an environment's application scope where the manifest declares a database. Both appear like other secrets at that scope; the developer creates neither.Type: string |
| / |
Type: string |
| / |
Type: string |
| / |
Type: ["string","null"] |
| / |
Type: ["string","null"] |
| / |
The environment of the application scope that holds the value, development or production; null at the account scope.Type: ["string","null"] |
| / |
The settings the application's manifest binds to this name, which each deploy and promote of the scope's environment injects into its container, and a restart where the running copy already holds the binding; empty where none does and at the account scope. Type: array |
| / |
Type: string |
| / |
The settings the running copy of the scope's environment reads from this name: those its serving version recorded at its deploy, promote, or restart. A setting in settings and not here reaches the container at that environment's next deploy or promote. Empty where nothing serves, where the running copy reads none from this name, and at the account scope.Type: array |
| / |
Type: string |
| / |
A keyed, truncated mark of the value stored under this name now, <kid>.<8 hex>. It is the first eight hexadecimal characters of HMAC-SHA-256 under a key the platform alone holds, over the account, the scope, the name, and the value, after the four-character id of that key. It is not the value, not a hash of it, and cannot be inverted or tested offline; only an overwrite of the live name compares a guess. Compare it with applied_fingerprint where the two key ids agree. Null where the value was stored before the mark, where the platform held no key at the write, or where the write's answer was unread. The egress gateway keeps no copy of a value: it reads the stored value on every call it forwards. On the row it reads for an upstream, the application's environment scope or the account scope where that holds none, this is also the mark of the value its next call sends. A key newly stored at the application's environment scope while an account-scope choice is held reaches the gateway after that choice expires; until then, the account row's mark applies.Type: ["string","null"] |
| / |
The same mark of the value the running copy of the scope's environment received, recorded by the deploy, promote, or restart that read it. Equal to fingerprint under one key id, the running copy has the stored value; different, a restart_application of that environment applies it. Null where nothing serves, where the running copy reads no setting from this name (including an upstream's key, which the gateway reads on each call), where the row recorded none, and at the account scope.Type: ["string","null"] |
| / |
Uses of this name in the application's environment. A realm entry identifies its work-account client secret or Apple signing key; a push entry identifies a provider credential. An upstream entry identifies an upstream bound to the application that declares this name as its credential. Each entry gives the environment and describes the credential in what. Empty when no such use exists or at the account scope, even when an upstream uses that account-scoped value. Settings supplied by a binding appear in settings and applied_settings, not consumers.Type: array |
| / |
Type: object Required fields: ["kind","environment","what"] |
| / |
Type: string Allowed values: ["realm","push","upstream"] |
| / |
Type: string |
| / |
Type: string |
| / |
True where applied_settings lists a setting and this name was stored or rotated after the running copy started, as read_status lists the setting in rotated_since_read; false otherwise, at the account scope among them. Call restart_application with that environment to apply the value now stored; it is refused while a deploy, promote, or restart of that environment is in progress or a halt is in place.Type: boolean |
| / |
Type: string |
Complete payload contract #
{
"request": {
"type": "object",
"properties": {
"application": {
"type": "string",
"description": "Optional: an application id of your account. Pass it and you get that application's secrets alone, at its environment scopes, and no account-scope name; an id no account holds is refused `no_such_application`, and another account's `application_other_account`."
},
"environment": {
"type": "string",
"pattern": "^(development|production)$",
"description": "Optional, and only with `application`: the one environment scope of that application to list, `development` or `production`; leave it out for both. Refused if given without `application`."
}
}
},
"response": {
"type": "object",
"required": [
"contract_version",
"secrets"
],
"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."
},
"secrets": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"scope",
"created_at"
],
"properties": {
"name": {
"type": "string",
"description": "The secret's name. The platform stores `credential-<application id>` as the application's platform credential (SEC-L0-07) at each environment's application scope: production's at its first deploy, development's at the first manifest submission. It stores `database-<application id>` as the database credential at an environment's application scope where the manifest declares a database (DBS-L0-02). Both appear like other secrets at that scope; the developer creates neither."
},
"scope": {
"type": "string"
},
"created_at": {
"type": "string"
},
"rotated_at": {
"type": [
"string",
"null"
]
},
"application": {
"type": [
"string",
"null"
]
},
"environment": {
"type": [
"string",
"null"
],
"description": "The environment of the application scope that holds the value, `development` or `production`; null at the account scope (SCRT-L0-08)."
},
"settings": {
"type": "array",
"items": {
"type": "string"
},
"description": "The settings the application's manifest binds to this name, which each deploy and promote of the scope's environment injects into its container, and a restart where the running copy already holds the binding; empty where none does and at the account scope (MAN-14)."
},
"applied_settings": {
"type": "array",
"items": {
"type": "string"
},
"description": "The settings the running copy of the scope's environment reads from this name: those its serving version recorded at its deploy, promote, or restart (MAN-14; PLD-L0-63). A setting in `settings` and not here reaches the container at that environment's next deploy or promote. Empty where nothing serves, where the running copy reads none from this name, and at the account scope."
},
"fingerprint": {
"type": [
"string",
"null"
],
"description": "A keyed, truncated mark of the value stored under this name now, `<kid>.<8 hex>`. It is the first eight hexadecimal characters of HMAC-SHA-256 under a key the platform alone holds, over the account, the scope, the name, and the value, after the four-character id of that key (SEC-L0-22). It is not the value, not a hash of it, and cannot be inverted or tested offline; only an overwrite of the live name compares a guess (SEC-L0-22). Compare it with `applied_fingerprint` where the two key ids agree. Null where the value was stored before the mark, where the platform held no key at the write, or where the write's answer was unread. The egress gateway keeps no copy of a value: it reads the stored value on every call it forwards. On the row it reads for an upstream, the application's environment scope or the account scope where that holds none, this is also the mark of the value its next call sends. A key newly stored at the application's environment scope while an account-scope choice is held reaches the gateway after that choice expires; until then, the account row's mark applies."
},
"applied_fingerprint": {
"type": [
"string",
"null"
],
"description": "The same mark of the value the running copy of the scope's environment received, recorded by the deploy, promote, or restart that read it (PLD-L0-63). Equal to `fingerprint` under one key id, the running copy has the stored value; different, a `restart_application` of that environment applies it. Null where nothing serves, where the running copy reads no setting from this name (including an upstream's key, which the gateway reads on each call), where the row recorded none, and at the account scope."
},
"consumers": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"environment",
"what"
],
"properties": {
"kind": {
"type": "string",
"enum": [
"realm",
"push",
"upstream"
]
},
"environment": {
"type": "string"
},
"what": {
"type": "string"
}
}
},
"description": "Uses of this name in the application's environment. A `realm` entry identifies its work-account client secret or Apple signing key; a `push` entry identifies a provider credential. An `upstream` entry identifies an upstream bound to the application that declares this name as its credential. Each entry gives the environment and describes the credential in `what`. Empty when no such use exists or at the account scope, even when an upstream uses that account-scoped value. Settings supplied by a binding appear in `settings` and `applied_settings`, not `consumers`."
},
"restart_needed": {
"type": "boolean",
"description": "True where `applied_settings` lists a setting and this name was stored or rotated after the running copy started, as `read_status` lists the setting in `rotated_since_read`; false otherwise, at the account scope among them (MAN-14). Call `restart_application` with that environment to apply the value now stored; it is refused while a deploy, promote, or restart of that environment is in progress or a halt is in place (PLD-L0-84)."
}
}
}
},
"detail": {
"type": "string"
}
}
}
}
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