---
title: Egress
description: Call an external API with a stored key through the egress gateway, tell the gateway's refusals from the upstream's responses, and read streamed responses.
slug: /backend-packages/egress
order: 6
visibility: public
redirects_from: []
---

# Egress

Egress is your application's side of the [egress gateway](/cloud/concepts/glossary/#egress-gateway). The gateway lets a backend on Turn Zero Cloud call an external application programming interface (API) with a stored key. The gateway adds the key to the request and never gives it to your process. It removes the key's header from the [upstream](/cloud/concepts/glossary/#declared-upstream)'s response and passes the rest through. So an upstream that echoes the key in its body returns it to your process.

This package's client sends the call, tells you whether a response came from the gateway or from the upstream, and reads a streamed response frame by frame. [Egress firewall and request limits](/cloud/concepts/egress-firewall-and-request-limits/#how-the-gateway-handles-a-call) describes the gateway itself, and [Call an external API with an API key](/cloud/guides/call-an-external-api-with-an-api-key/) the task.

## Use it when

Use Egress by default for an API with a stored key, such as an AI provider, a payments API, or a search API. If the client's host is fixed in code the task forbids changing, follow [the binding exception](/cloud/getting-started/store-a-secret/#the-rule-in-code) instead. Store the key once, declare the upstream against the key's name, and call `/egress/v0/<upstream>/<path>` through the client under your application's [platform credential](/cloud/concepts/glossary/#platform-credential). The provider bills your own provider account. When you rotate the key in [custody](/cloud/concepts/glossary/#custody), no application code changes.

To use a provider's SDK (client library) unchanged, declare the upstream with `sdk_settings`; no Egress package is needed. Each deploy gives the SDK an [egress key](/cloud/concepts/glossary/#egress-key), which the gateway replaces with your stored provider key. The SDK does not receive this package's typed [refusals](/cloud/concepts/glossary/#refusal) ([An unchanged SDK](/cloud/guides/call-an-external-api-with-an-api-key/#an-unchanged-sdk)).

For a destination that needs no stored key, add its host to the [manifest](/cloud/concepts/glossary/#manifest)'s `egress` list. Ordinary `fetch` then reaches it through the [HTTPS tunnel](/cloud/concepts/glossary/#https-tunnel) ([Egress firewall and request limits](/cloud/concepts/egress-firewall-and-request-limits/)).

## What it provides

- A client, `EgressClient`, which calls through a transport function your application supplies. [The client](#the-client) describes it.
- One call per request. The method `call(upstream, path, init)` sends the method, the headers, the body, and the query string unchanged. It returns the upstream's own response, whatever its status, when the response has the gateway's marker header `x-egress-upstream`. The gateway adds that header to every response that came from an upstream.
- A typed refusal, `GatewayRefusal`, thrown for every response without the marker header. That covers the gateway's own refusals, the platform's authentication challenge, and a response to a request that never reached the gateway. Each has the refusal's name, its status, its detail, and a `kind` that says what to do.
- A frame reader, `readEventStream`, for an upstream that responds with an event stream. It returns each frame in order as it arrives, and it follows your abort signal. It throws `egress_error`, the one final event the gateway can send inside the stream, as the same typed refusal.
- A [test double](/cloud/concepts/glossary/#test-double), `createEgressDouble` at `@turnzero/egress/testing`, which takes the gateway's place behind the unchanged client. [Test with the double](#test-with-the-double) shows it in use.

The client adds no header, no retry, no timeout, and no limit of its own. The gateway removes some headers before the request reaches the upstream, among them the forwarding headers a proxy adds and the platform's own: [What the upstream receives](/cloud/concepts/egress-firewall-and-request-limits/#what-the-upstream-receives) lists them. The gateway limits the request size, the response size, and the upstream's time, and refuses a call over each limit by name. The package never switches to another provider: write any fallback in your application.

If the manifest includes `upstreams`, declare the upstream there. Otherwise call `declare_outbound_api` ([Declare in the manifest](/cloud/guides/call-an-external-api-with-an-api-key/#declare-in-the-manifest)). Edit a manifest-declared upstream in the manifest; `declare_outbound_api` refuses to change it with `manifest_owned_field`.

## Availability

Version 0.19.2 is the package's current version, and this page describes it. Until the library's next publish, `read_library` can return an earlier version, the one you can take, so this page can describe a change that version lacks. The entry includes the `testing` subpath. The entry contains the compiled client, the package's [product statement and detailed contract](/cloud/concepts/glossary/#product-statement-and-detailed-contract), and its integration guide. The platform runs the egress gateway and counts use per upstream.

## Related feature packages

[Secrets](/cloud/backend-packages/secrets/) stores the keys the gateway adds. [Logging](/cloud/backend-packages/logging/) records what your backend does with an upstream's response. [Node.js Runtime](/cloud/backend-packages/nodejs-runtime/) routes calls through the tunnel to destinations that use no stored key. [AI Allowance](/cloud/backend-packages/ai-allowance/) is the platform's own upstream, with its own package.

## The client

The package is published in the library as the npm package `@turnzero/egress`, not on the npm registry; [Use the library](/cloud/guides/use-the-library/#5-install-a-package-s-compiled-code) installs it with one line. [Call it from a route](/cloud/guides/call-an-external-api-with-an-api-key/#3-call-it-from-a-route) shows the client in a complete backend route, which a test checks.

### Construction

Build the client with `new EgressClient(transport)`. Your function `transport(path, init)` adds the gateway's origin and your credential, sends the request, and returns the response. A deployed transport reads the gateway's origin from `TURNZERO_CLOUD_GATEWAY_URL`, or from `TURNZERO_CLOUD_API` where that is unset, and the credential from `TURNZERO_CLOUD_APP_TOKEN`, among the settings [a deployed copy receives](/cloud/concepts/the-settings-a-deployed-copy-receives/).

Where your backend runs under a [minted token](/cloud/concepts/glossary/#minted-token) or a [session](/cloud/concepts/glossary/#session), rather than its platform credential, set the environment once on its transport with the header `x-turnzero-cloud-environment`. Every gateway call then sends it. The Storage package's `withEnvironment` wraps a transport used only for storage the same way.

### Methods and results

- The method `call(upstream, path, init)` sends one call to `/egress/v0/<upstream><path>` and returns the upstream's response. Its `init` takes `method`, `headers`, `body`, and `signal`, each passed through unchanged.
- The method `upstream(name)` returns a function bound to one upstream, `(path, init) => call(name, path, init)`.
- The static method `EgressClient.pathFor(upstream, path)` returns the path a call sends. A malformed upstream name throws `TypeError` before any call.
- The function `readEventStream(response, { signal })` returns the frames of an event stream in order, each `{ event, data, id }`.

### Confirm a call went through the gateway

After you deploy, trigger the code that calls the provider. In your signed-in AI tool, call `list_outbound_apis` and find the upstream bound to your application. Compare `last_call.at` with the time of your test. The entry shows the latest HTTP call the gateway tried to forward for that upstream and application in the past seven days.

Read `outcome` for the gateway's result and `status` for the provider's HTTP status. If `status` is null, no HTTP response reached the gateway. The result covers both environments, so test when you can distinguish your call from other traffic.

If `last_call` is missing or older than your test, check that your code called the declared upstream through the gateway. The entry leaves out `CONNECT` tunnels and calls the gateway refused before forwarding. See the [`list_outbound_apis` reference](/cloud/reference/actions/list-outbound-apis/) for the outcome values.

### Failures

A `GatewayRefusal` has `error`, the refusal's name, and `status`, `detail`, `kind`, `upstream`, and `path`. Where supplied, `scope` describes what the credential is bound to. The refusal's `challenge` carries the `WWW-Authenticate` header where the response is the platform's authentication challenge. Choose what to do by its `kind`:

| `kind` | Names | What to do |
| --- | --- | --- |
| `declaration` | `unknown_upstream`, `undeclared_upstream`, `upstream_scope_refused`, `refused_base_url`, `refused_platform_host`, and the address refusals `egress_private_address`, `egress_loopback_address`, `egress_link_local_address`, `egress_reserved_address`, and `egress_platform_address` | Correct the upstream's declaration. An address refusal means the declared host resolved, at the call, to an address that is not public ([Address and host checks](/cloud/concepts/egress-firewall-and-request-limits/#address-and-host-checks)). |
| `credential` | `credential_not_in_custody`, `credential_unreadable`, `platform_minted_name` | Store the credential the declaration gives. For `platform_minted_name`, the declaration gives a credential the platform mints for its own use: store your key under a name of your own and declare the upstream with it. |
| `bounds` | `request_too_large`, `response_too_large`, `upstream_timeout` | Stay within the platform limit the refusal gives. |
| `transport` | `upstream_unreachable`, `internal`, `store_unavailable`, `credential_lookup_busy` | Retry the call. For `credential_lookup_busy`, wait one second, then call again. |
| `authentication` | `authentication_required`, `insufficient_scope`, `account_suspended`, `end_user_credential_not_admitted`, `transfer_grant_not_admitted`, `egress_key_not_admitted` | Refresh your application's own credential. For `egress_key_not_admitted`, an egress key was sent outside its own upstream: send it only to that upstream. |
| `environment` | `environment_required`, `environment_mismatch` | Set the environment on the request. |
| `admission` | `rate_capped`, `egress_daily_bytes_capped` | The platform's rate limit refused the call, or the application reached its outbound-byte limit for the UTC day. Wait, then call again: for the day limit, after the reset time the refusal's detail gives. |
| `address` | `retired_host`, `misdirected_origin` | The request did not reach the platform through its public address. It used a retired hostname, a service's internal hostname, or a missing or wrong header from the platform's public entry service. Use the address in the refusal's detail. Retrying the same address fails again. |
| `unrecognized` | Any other name | This client version does not recognize the name. Read its `error` and status. |
| `unmarked` | `unmarked` | The request never reached the gateway. Check the route your transport builds. |

A refused tunnel connection raises a different error: the [runtime harness](/cloud/concepts/glossary/#runtime-harness)'s `EgressRefusedError`, found in the `cause` of a rejected `fetch`. [Node.js Runtime](/cloud/backend-packages/nodejs-runtime/) describes it.

## Test with the double

The function `createEgressDouble()` from `@turnzero/egress/testing` takes the gateway's place behind the real client. Declare each upstream with `double.declare(name, handler, { application })`, giving the application it is bound to, and the handler responds to that upstream's calls. Build `EgressClient` over `double.transport`, or stub the global `fetch` with `double.fetch` where your own transport wraps it. Calling `reset()` empties the recorded `calls` and keeps the declarations. Where your transport sends the environment header, as a local run under your own sign-in does, create the double with `credential: 'session'`. A test runs this sample over the double.

```js
import assert from 'node:assert/strict';
import { EgressClient, GatewayRefusal } from '@turnzero/egress';
import { createEgressDouble } from '@turnzero/egress/testing';

const egress = createEgressDouble();
egress.declare('weather', (request) => ({ json: { path: request.path, query: request.query } }), { application: 'app' });
const client = new EgressClient(egress.transport);

const answer = await client.call('weather', '/v1/now?city=Oslo');
assert.equal(answer.status, 200);
assert.deepEqual(await answer.json(), { path: '/v1/now', query: 'city=Oslo' });
// An upstream the test never declared is the gateway's own refusal, thrown by the client.
await assert.rejects(client.call('maps', '/v1/route'), (error) => error instanceof GatewayRefusal && error.error === 'undeclared_upstream');
```

The client throws `GatewayRefusal`, with the refusal's name in `error` and its `kind`, as [Failures](#failures) lists. Where a refusal is the test's subject, assert the name instead of applying the remedy. The double returns these refusals for faults in its own setup:

| Refusal | Cause | Remedy |
| --- | --- | --- |
| `undeclared_upstream`, `unknown_upstream` | The call named an upstream the test never declared, or none. A name containing a NUL character (U+0000) or an unpaired UTF-16 surrogate reads as no name. | Declare the upstream with `double.declare`, and send its name without the character. |
| `upstream_scope_refused` | The upstream is declared for an application the double's credential does not reach. | Declare it for the application of the double's `scope`. |
| `credential_not_in_custody` | The upstream was declared with `credentialHeld: false`. | Declare it with the credential held. |
| `request_too_large`, `response_too_large` | The request or the response passed a size limit. | Keep the body within `requestBytes` or `responseBytes`. |
| `upstream_unreachable` | The handler threw, or responded with `fail`. | Return a response from the handler. |
| `authentication_required`, `environment_required`, `environment_mismatch` | The double requires a bearer and got none, or the environment header is missing or wrong. | Send `Bearer` and the credential, and send the environment that the double's `environment` option gives. |
| `unmarked` | The request did not use the gateway path that includes its upstream key. | Call through the client. |
| `TypeError` from `declare` | The upstream's name is outside the allowed form, or the options give no application (`application_required`), or an empty or non-string application (`invalid_request`). | Use the name the application declares, and pass `{ application }`, the application's id as a string. |
