# Set Upstream API Key Policy

The set upstream API key policy attaches a single header (by default
`Authorization`) to the incoming request so it can be forwarded to your
upstream service. It is a focused version of the set headers policy intended
for the common case of authenticating Zuplo to an upstream API using a secret
sourced from an environment variable.

## Configuration

The configuration shows how to configure the policy in the 'policies.json' document.

```json title="config/policies.json"
{
  "name": "my-set-upstream-api-key-inbound-policy",
  "policyType": "set-upstream-api-key-inbound",
  "handler": {
    "export": "SetUpstreamApiKeyInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "header": "Authorization",
      "value": "Bearer $env(UPSTREAM_API_KEY)"
    }
  }
}
```

### Policy Configuration

- `name` <code className="text-green-600">&lt;string&gt;</code> - The name of your policy instance. This is used as a reference in your routes.
- `policyType` <code className="text-green-600">&lt;string&gt;</code> - The identifier of the policy. This is used by the Zuplo UI. Value should be `set-upstream-api-key-inbound`.
- `handler.export` <code className="text-green-600">&lt;string&gt;</code> - The name of the exported type. Value should be `SetUpstreamApiKeyInboundPolicy`.
- `handler.module` <code className="text-green-600">&lt;string&gt;</code> - The module containing the policy. Value should be `$import(@zuplo/runtime)`.
- `handler.options` <code className="text-green-600">&lt;object&gt;</code> - The options for this policy. [See Policy Options](#policy-options) below.

### Policy Options

The options for this policy are specified below. All properties are optional unless specifically marked as required.

- `header` <code className="text-green-600">&lt;string&gt;</code> - The name of the header to set on the request. Defaults to `Authorization`. Defaults to `"Authorization"`.
- `value` **(required)** <code className="text-green-600">&lt;string&gt;</code> - The value of the header. Most commonly an environment variable reference such as `Bearer $env(UPSTREAM_API_KEY)` so the secret is sourced from your environment.
- `overwrite` <code className="text-green-600">&lt;boolean&gt;</code> - Overwrite the value if the header is already present in the request. Defaults to `true`.

## Using the Policy

Many upstream APIs require an API key or bearer token to be passed in a header
on every request. This policy is a focused version of the
`SetHeadersInboundPolicy` that sets a single header (defaulting to
`Authorization`) and is designed to be paired with an environment variable so
the secret never lives in your `policies.json`.

The most common configuration sets a bearer token from an environment variable:

```json
{
  "name": "set-upstream-api-key-inbound-policy",
  "policyType": "set-upstream-api-key-inbound",
  "handler": {
    "export": "SetUpstreamApiKeyInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "value": "Bearer $env(UPSTREAM_API_KEY)"
    }
  }
}
```

You can also customize the header name. For example, if your upstream uses a
custom header rather than `Authorization`:

```json
{
  "name": "set-upstream-api-key-inbound-policy",
  "policyType": "set-upstream-api-key-inbound",
  "handler": {
    "export": "SetUpstreamApiKeyInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "header": "X-API-Key",
      "value": "$env(UPSTREAM_API_KEY)"
    }
  }
}
```

By default the policy overwrites any header with the same name that was sent by
the client. Set `overwrite` to `false` to preserve the incoming value when one
is present.

Read more about [how policies work](/articles/policies)