declare_outbound_api #
On this page
Generated automatically from the published contract sources.
A script calls this action over HTTPS at POST https://tzcloud.turnzero.ai/v1/declare_outbound_api, with a bearer credential and the action's payload as the JSON body. An MCP connection lists this action as the tool tzcloud_declare_outbound_api.
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 #
Declare or remove an outside API your application calls through the proxy. Its key must already be stored with store_secret. Where the manifest has upstreams, the API is declared there instead of with this tool.
Calls to /egress/v0/<upstream>/<path> use Authorization: Bearer with the platform credential or an egress key. The proxy adds the stored key. Code reads the gateway address and credential from settings. sdk_settings configures an unchanged SDK on each environment's next deploy, promote or restart_application. Declaration leaves running settings unchanged. Direct key binding in manifest settings is only for a client host fixed in code the task forbids changing. For that binding, declare no upstream and list its host in manifest egress. No check proves your code uses the proxy. Check the first call with read_logs for undeclared egress.
More about this action #
The call is refused credential_not_in_custody for a key not stored. Declaring the same name again revises the entry, except its application, which cannot change: a different application is refused binding_refused. An upstream that the application's manifest lists in upstreams belongs to the manifest, and a change to it here is refused manifest_owned_field. A stored name that a setting binds is refused upstream_key_is_bound. That covers a binding in the manifest's settings, in either environment's running copy, or in a deploy, promote, or restart still in progress.
The egress gateway never gives the key to the application, though an upstream that echoes the key returns it.
With sdk_settings, a provider's SDK reaches the API from a deployed container with no code change. Each deploy, promote, and restart_application sets the setting that base_url gives to the gateway's address for this upstream. It sets the setting that key gives to an egress key: a credential the platform mints for this upstream and this environment's container, which the gateway swaps for the stored key. The OpenAI SDKs read OPENAI_BASE_URL and OPENAI_API_KEY. The Anthropic SDKs read ANTHROPIC_BASE_URL and their bearer setting, ANTHROPIC_AUTH_TOKEN.
After the first call, check that the client called through the gateway. Call read_logs with filter: "undeclared" and source: "egress", then again with source: "harness". Either read shows a call the client made to the provider's host directly, which skipped /egress/v0/, and a failed attempt shows too. In read_status, application.egress lists the undeclared hosts the serving version reached, where its read is logs, leaving out failed attempts. It also lists this upstream in upstreams, beside its host. A host the manifest's egress lists shows in neither.
The sdk_settings argument: optional. It lists the settings that an unchanged client of this upstream, such as a provider's SDK, reads in a deployed container. The platform fills these settings, so the stored key stays at the gateway. The manifest's settings is a different member, which binds a stored value into the container. The egress key works on this upstream alone. A revision that omits sdk_settings keeps the current ones.
Passing null removes them, and sdk_settings without key drops the key setting. Either ends the upstream's egress keys in both environments, and the response's egress_keys_ended gives how many ended.
The sdk_settings.base_url member: required where you give sdk_settings. It is the name of the setting that receives the gateway's address for this upstream: the gateway origin the deploy injects, then /egress/v0/<name>, then base_path. The name starts with an upper-case letter, contains only upper-case letters, digits, or underscores, and ends in a letter or a digit.
The sdk_settings.key member: the name of the setting that receives the egress key. The setting holds an egress key, never the provider's key; code you write should send its platform credential or, if it reads this setting, use a name such as WEATHER_EGRESS_KEY. The key reaches this upstream's route alone, and the gateway swaps it for the stored key, so the stored key never enters the container. The name follows the rules for base_url.
The base_url argument: required to declare, the upstream's public https:// base URL. Mail ports are refused. A declaration without a valid value is refused 400 invalid_request. Leave it out with remove: true.
The credential_name argument: required to declare, the name you stored the key under with store_secret. A declaration without a valid custody name is refused 400 invalid_request. Leave it out with remove: true.
The application argument: required to declare, the id of your application. Only the account's own credentials reach this action; the platform credential and a token bounded to an application are refused. Without it, a declaration is refused 400 application_required. Leave it out with remove: true, which takes name alone.
The remove argument: with true, the call ends the upstream given by name and takes no other argument; a declaring argument beside it is refused invalid_request. It ends an upstream whether this tool or the manifest's upstreams member declared it. It frees the name and ends the upstream's egress keys in both environments, and a failed call ends nothing. The proxy then refuses its calls from any running copy once its short cache interval passes.
The result lists the environments whose deployed copies lost a key, and those whose serving version or deploy in flight was given the upstream's sdk_settings. The stored key stays in custody; you can then delete it with delete_secret when nothing else refers to it. Submitting a manifest never ends an upstream.
An upstream your application's manifest lists in upstreams is refused manifest_owned_field: remove the entry, submit the manifest, and promote the version that no longer calls the upstream, then remove it. For an undeclared name, the call returns with nothing changed. To bring it back, declare it again, then deploy or promote each environment.
The auth_header argument: required to declare, a valid HTTP header name, for example Authorization or x-api-key. A declaration without a valid header name is refused 400 invalid_request. Leave it out with remove: true. The auth_format argument: for example Bearer {value}.
The sdk_settings.base_path member: for example /v1, for a client that appends /chat/completions to its base URL.
The sdk_settings.key member: the platform mints the egress key for this upstream and environment at each deploy, promote, and restart.
For code you write, take the gateway origin from TURNZERO_CLOUD_GATEWAY_URL, falling back to TURNZERO_CLOUD_API, and the platform credential from TURNZERO_CLOUD_APP_TOKEN. Call that origin at /egress/v0/<name>/<path> with Authorization: Bearer and that credential. A revision that drops sdk_settings.key ends the old egress keys at once. A copy that held one has no working key until you declare again with key, then deploy, promote or restart_application its environment. The x-egress-upstream response header identifies a response from the upstream, not a gateway refusal.
Access and action metadata #
{
"name": "declare_outbound_api",
"resource": "upstream",
"tier": "reversible",
"surface": "tzcloud",
"addresses": [
"tzcloud"
],
"product": "cloud",
"summary": "Declare or revise an upstream: base URL, custody credential name, auth form, and the optional `sdk_settings`; the tier noted for its credential-binding weight. With `remove: true` and `name` alone, it ends one declaration instead: the declaration is removed and the name freed, and the upstream's egress keys end in both environments; a call that fails ends nothing. The gateways then refuse its calls from any running copy once their short cache interval passes. The stored key stays in custody, and delete_secret is then admitted where nothing else refers to it. A removal of an upstream the bound application's manifest lists in `upstreams` is refused `manifest_owned_field`: remove the entry, submit the manifest, and promote the version that no longer calls the upstream first. No submission ends an upstream, and for an absent name the removal returns unchanged. The route for every external API an application calls on a stored key: the value goes into custody under the name first (`store_secret`), and the gateway applies it at its own edge. The gateway never gives the key to the application, though an upstream that echoes the key returns it. With `sdk_settings`, each deploy, promote, and restart sets the named base-URL setting to the gateway's route and the key setting to an egress key the gateway swaps for the stored key, so an unchanged SDK reaches the API. A stored name a setting binds, in the manifest's `settings`, in either environment's running copy, or in an act in flight, is refused `upstream_key_is_bound`. An upstream that the bound application's manifest lists in `upstreams` belongs to the manifest, and a change to it is refused `manifest_owned_field`. The declaration is recorded in the project's own requirements, the platform's example applications showing one form that works, reached through the served library-first guide.",
"annotations": {
"readOnlyHint": false,
"destructiveHint": true,
"openWorldHint": false
}
}
MCP catalog entry #
{
"name": "declare_outbound_api",
"title": "Allow or remove outbound API",
"tier": "reversible",
"scenario": "EGW-L0-09",
"summary": "Declare or remove an outside API your application calls through the proxy. Its key must already be stored with `store_secret`. Where the manifest has `upstreams`, the API is declared there instead of with this tool.\n\nCalls to `/egress/v0/<upstream>/<path>` use `Authorization: Bearer` with the platform credential or an egress key. The proxy adds the stored key. Code reads the gateway address and credential from settings. `sdk_settings` configures an unchanged SDK on each environment's next deploy, promote or `restart_application`. Declaration leaves running settings unchanged. Direct key binding in manifest `settings` is only for a client host fixed in code the task forbids changing. For that binding, declare no upstream and list its host in manifest `egress`. No check proves your code uses the proxy. Check the first call with `read_logs` for undeclared egress.",
"owners": [
"EGW-L0-03",
"EGW-L0-01",
"EGW-L0-07",
"EGW-L0-08",
"SEC-L0-18",
"MAN-14",
"EGW-L0-17",
"EGW-L0-02"
]
}
request #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["name"] |
| / |
Upstream name, unique within the account, and <upstream> in the proxy path. Reusing it revises the entry. Changing or removing an upstream the manifest's upstreams lists is refused manifest_owned_field.Type: string Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$ |
| / |
Required to declare: public https:// base URL. The key applies under it. Mail ports are refused. Without a valid URL, a declaration is refused invalid_request. Omitted with remove: true.Type: string Minimum length: 9 Maximum length: 2000 |
| / |
Required to declare: the key's stored name from store_secret. Without a valid name, a declaration is refused invalid_request. Omitted with remove: true.Type: string Pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$ |
| / |
Required to declare: the HTTP header that carries the key. Without a valid header name, a declaration is refused invalid_request. Omitted with remove: true.Type: string Pattern: ^[a-zA-Z0-9-]{1,64}$ |
| / |
Header value with {value} replaced by the key. Default: {value}.Type: string Minimum length: 7 Maximum length: 200 |
| / |
Token-count format of the upstream's responses. Omitted where it reports none. Type: string Pattern: ^(gemini|anthropic)$ |
| / |
Settings filled for an unchanged client in a deployed container. Omission on revision keeps them. null or no key revokes this upstream's egress keys in both environments.Type: ["object","null"] Additional properties: false Required fields: ["base_url"] |
| / |
Setting for this upstream's gateway address. A name the platform sets, a manifest binding uses, or another upstream of the application uses is refused invalid_request.Type: string Pattern: ^[A-Z](?:[A-Z0-9_]{0,62}[A-Z0-9])?$ |
| / |
Setting for the egress key sent as Authorization: Bearer <key>. Omission gives the container no key setting.Type: string Pattern: ^[A-Z](?:[A-Z0-9_]{0,62}[A-Z0-9])?$ |
| / |
The path base_url's value ends with; without it, the value ends at the upstream's name.Type: string Pattern: ^(/[A-Za-z0-9._~%-]+)+$ Maximum length: 200 |
| / |
Deprecated alias of sdk_settings. Giving both is refused invalid_request.Type: ["object","null"] |
| / |
Application id, required to declare, else application_required. A different application on revision is refused binding_refused.Type: string |
| / |
With true, takes name alone and frees it. This upstream's egress keys end in both environments. Calls from running copies stop after the cache interval. The stored key stays. Otherwise declares or revises.Type: boolean |
response #
| JSON pointer | Description and constraints |
|---|---|
| "" (root) | Type: object Required fields: ["contract_version","upstream","outcome"] |
| / |
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 upstream as declared; with remove: true, the declaration removed, as it was, or null where no upstream by the name was declared.Type: ["object","null"] |
| / |
created or revised for a declaration; with remove: true, removed where the declaration was removed and the name freed, and unchanged where no upstream by the name was declared, so a second call returns the same state.Type: string Pattern: ^(created|revised|removed|unchanged)$ |
| / |
Present where the declaration holds sdk_settings (or settings, its former name): what a deployed container of the bound application reads for this upstream. The settings arrive at each environment's next deploy or promote, and a running container keeps its settings until then.Type: object Required fields: ["base_url","path"] |
| / |
The setting that receives the gateway's address for this upstream. Type: string |
| / |
The path that address ends with, /egress/v0/<name> followed by base_path, after the gateway origin the deploy injects.Type: string |
| / |
The setting that receives the egress key for this upstream; absent where the declaration holds none. Type: string |
| / |
Present where the call ended egress keys: a revision that gave sdk_settings (or settings, its former name) as null or without key, or a removal with remove: true. It counts the upstream's egress keys ended, in both environments, zero where no deployed copy held one. A copy that held one has no working key until the environment's next deploy, promote, or restart_application after a declaration that gives key again, and the detail lists those environments.Type: integer Minimum: 0 |
| / |
Type: string |
| / |
$ref: #/shapes/page |
Complete payload contract #
{
"request": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$",
"description": "Upstream name, unique within the account, and `<upstream>` in the proxy path. Reusing it revises the entry. Changing or removing an upstream the manifest's `upstreams` lists is refused `manifest_owned_field`."
},
"base_url": {
"type": "string",
"minLength": 9,
"maxLength": 2000,
"description": "Required to declare: public `https://` base URL. The key applies under it. Mail ports are refused. Without a valid URL, a declaration is refused `invalid_request`. Omitted with `remove: true`."
},
"credential_name": {
"type": "string",
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$",
"description": "Required to declare: the key's stored name from `store_secret`. Without a valid name, a declaration is refused `invalid_request`. Omitted with `remove: true`."
},
"auth_header": {
"type": "string",
"pattern": "^[a-zA-Z0-9-]{1,64}$",
"description": "Required to declare: the HTTP header that carries the key. Without a valid header name, a declaration is refused `invalid_request`. Omitted with `remove: true`."
},
"auth_format": {
"type": "string",
"minLength": 7,
"maxLength": 200,
"description": "Header value with `{value}` replaced by the key. Default: `{value}`."
},
"token_shape": {
"type": "string",
"pattern": "^(gemini|anthropic)$",
"description": "Token-count format of the upstream's responses. Omitted where it reports none."
},
"sdk_settings": {
"type": [
"object",
"null"
],
"additionalProperties": false,
"required": [
"base_url"
],
"description": "Settings filled for an unchanged client in a deployed container. Omission on revision keeps them. `null` or no `key` revokes this upstream's egress keys in both environments.",
"properties": {
"base_url": {
"type": "string",
"pattern": "^[A-Z](?:[A-Z0-9_]{0,62}[A-Z0-9])?$",
"description": "Setting for this upstream's gateway address. A name the platform sets, a manifest binding uses, or another upstream of the application uses is refused `invalid_request`."
},
"key": {
"type": "string",
"pattern": "^[A-Z](?:[A-Z0-9_]{0,62}[A-Z0-9])?$",
"description": "Setting for the egress key sent as `Authorization: Bearer <key>`. Omission gives the container no key setting."
},
"base_path": {
"type": "string",
"pattern": "^(/[A-Za-z0-9._~%-]+)+$",
"maxLength": 200,
"description": "The path `base_url`'s value ends with; without it, the value ends at the upstream's name."
}
}
},
"settings": {
"type": [
"object",
"null"
],
"description": "Deprecated alias of `sdk_settings`. Giving both is refused `invalid_request`."
},
"application": {
"type": "string",
"description": "Application id, required to declare, else `application_required`. A different application on revision is refused `binding_refused`."
},
"remove": {
"type": "boolean",
"description": "With `true`, takes `name` alone and frees it. This upstream's egress keys end in both environments. Calls from running copies stop after the cache interval. The stored key stays. Otherwise declares or revises."
}
}
},
"response": {
"type": "object",
"required": [
"contract_version",
"upstream",
"outcome"
],
"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."
},
"upstream": {
"type": [
"object",
"null"
],
"description": "The upstream as declared; with `remove: true`, the declaration removed, as it was, or null where no upstream by the name was declared."
},
"outcome": {
"type": "string",
"pattern": "^(created|revised|removed|unchanged)$",
"description": "`created` or `revised` for a declaration; with `remove: true`, `removed` where the declaration was removed and the name freed, and `unchanged` where no upstream by the name was declared, so a second call returns the same state."
},
"sdk_settings": {
"type": "object",
"description": "Present where the declaration holds `sdk_settings` (or `settings`, its former name): what a deployed container of the bound application reads for this upstream. The settings arrive at each environment's next deploy or promote, and a running container keeps its settings until then.",
"required": [
"base_url",
"path"
],
"properties": {
"base_url": {
"type": "string",
"description": "The setting that receives the gateway's address for this upstream."
},
"path": {
"type": "string",
"description": "The path that address ends with, `/egress/v0/<name>` followed by `base_path`, after the gateway origin the deploy injects."
},
"key": {
"type": "string",
"description": "The setting that receives the egress key for this upstream; absent where the declaration holds none."
}
}
},
"egress_keys_ended": {
"type": "integer",
"minimum": 0,
"description": "Present where the call ended egress keys: a revision that gave `sdk_settings` (or `settings`, its former name) as null or without `key`, or a removal with `remove: true`. It counts the upstream's egress keys ended, in both environments, zero where no deployed copy held one. A copy that held one has no working key until the environment's next deploy, promote, or `restart_application` after a declaration that gives `key` again, and the detail lists those environments."
},
"detail": {
"type": "string"
},
"page": {
"$ref": "#/shapes/page"
}
}
}
}
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