---
title: "declare_outbound_api"
description: "Generated reference for the management action declare_outbound_api: its description, access metadata, payload contract, and registration status."
slug: /reference/actions/declare-outbound-api
order: 51
visibility: public
redirects_from: ["/reference/actions/undeclare-upstream","/reference/actions/declare-upstream"]
---

# declare\_outbound\_api

Generated automatically from the [published contract sources](/cloud/reference/about/#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](/cloud/concepts/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

```json
{
  "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

```json
{
  "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<br>Required fields: \["name"\] |
| /<wbr>properties/<wbr>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`\.<br><br>Type: string<br>Pattern: ^\[a\-zA\-Z0\-9\]\[a\-zA\-Z0\-9\_\-\]\{0,63\}$ |
| /<wbr>properties/<wbr>base\_url | 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`\.<br><br>Type: string<br>Minimum length: 9<br>Maximum length: 2000 |
| /<wbr>properties/<wbr>credential\_name | 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`\.<br><br>Type: string<br>Pattern: ^\[a\-zA\-Z0\-9\]\[a\-zA\-Z0\-9\_\-\]\{0,63\}$ |
| /<wbr>properties/<wbr>auth\_header | 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`\.<br><br>Type: string<br>Pattern: ^\[a\-zA\-Z0\-9\-\]\{1,64\}$ |
| /<wbr>properties/<wbr>auth\_format | Header value with `{value}` replaced by the key\. Default: `{value}`\.<br><br>Type: string<br>Minimum length: 7<br>Maximum length: 200 |
| /<wbr>properties/<wbr>token\_shape | Token\-count format of the upstream's responses\. Omitted where it reports none\.<br><br>Type: string<br>Pattern: ^\(gemini\|anthropic\)$ |
| /<wbr>properties/<wbr>sdk\_settings | 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\.<br><br>Type: \["object","null"\]<br>Additional properties: false<br>Required fields: \["base\_url"\] |
| /<wbr>properties/<wbr>sdk\_settings/<wbr>properties/<wbr>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`\.<br><br>Type: string<br>Pattern: ^\[A\-Z\]\(?:\[A\-Z0\-9\_\]\{0,62\}\[A\-Z0\-9\]\)?$ |
| /<wbr>properties/<wbr>sdk\_settings/<wbr>properties/<wbr>key | Setting for the egress key sent as `Authorization: Bearer <key>`\. Omission gives the container no key setting\.<br><br>Type: string<br>Pattern: ^\[A\-Z\]\(?:\[A\-Z0\-9\_\]\{0,62\}\[A\-Z0\-9\]\)?$ |
| /<wbr>properties/<wbr>sdk\_settings/<wbr>properties/<wbr>base\_path | The path `base_url`'s value ends with; without it, the value ends at the upstream's name\.<br><br>Type: string<br>Pattern: ^\(/\[A\-Za\-z0\-9\.\_\~%\-\]\+\)\+$<br>Maximum length: 200 |
| /<wbr>properties/<wbr>settings | Deprecated alias of `sdk_settings`\. Giving both is refused `invalid_request`\.<br><br>Type: \["object","null"\] |
| /<wbr>properties/<wbr>application | Application id, required to declare, else `application_required`\. A different application on revision is refused `binding_refused`\.<br><br>Type: string |
| /<wbr>properties/<wbr>remove | 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\.<br><br>Type: boolean |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version","upstream","outcome"\] |
| /<wbr>properties/<wbr>contract\_version | Required value: 1 |
| /<wbr>properties/<wbr>reference | 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\.<br><br>Type: string<br>Pattern: ^\[0\-9a\-f\]\{10\}$ |
| /<wbr>properties/<wbr>upstream | The upstream as declared; with `remove: true`, the declaration removed, as it was, or null where no upstream by the name was declared\.<br><br>Type: \["object","null"\] |
| /<wbr>properties/<wbr>outcome | `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\.<br><br>Type: string<br>Pattern: ^\(created\|revised\|removed\|unchanged\)$ |
| /<wbr>properties/<wbr>sdk\_settings | 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\.<br><br>Type: object<br>Required fields: \["base\_url","path"\] |
| /<wbr>properties/<wbr>sdk\_settings/<wbr>properties/<wbr>base\_url | The setting that receives the gateway's address for this upstream\.<br><br>Type: string |
| /<wbr>properties/<wbr>sdk\_settings/<wbr>properties/<wbr>path | The path that address ends with, `/egress/v0/<name>` followed by `base_path`, after the gateway origin the deploy injects\.<br><br>Type: string |
| /<wbr>properties/<wbr>sdk\_settings/<wbr>properties/<wbr>key | The setting that receives the egress key for this upstream; absent where the declaration holds none\.<br><br>Type: string |
| /<wbr>properties/<wbr>egress\_keys\_ended | 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\.<br><br>Type: integer<br>Minimum: 0 |
| /<wbr>properties/<wbr>detail | Type: string |
| /<wbr>properties/<wbr>page | $ref: \#/shapes/page |

## Complete payload contract

```json
{
  "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](/cloud/reference/refusals/): every refusal, by surface, with its cause and its remedy
- [schemas/wire\_error\.schema\.json](/cloud/reference/sources/schemas/wire-error-schema/)
- [schemas/wire\_errors\.json](/cloud/reference/sources/schemas/wire-errors/)
- [schemas/action\_payloads\.json](/cloud/reference/sources/schemas/action-payloads/) (includes shared shapes)
- [management\_api\_contract\.md](/cloud/reference/sources/management-api-contract/)
