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.


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 <string> - The name of your policy instance. This is used as a reference in your routes.
policyType <string> - The identifier of the policy. This is used by the Zuplo UI. Value should be set-upstream-api-key-inbound.
handler.export <string> - The name of the exported type. Value should be SetUpstreamApiKeyInboundPolicy.
handler.module <string> - The module containing the policy. Value should be $import(@zuplo/runtime).
handler.options <object> - The options for this policy. See Policy Options below.

Policy Options

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

header <string> - The name of the header to set on the request. Defaults to Authorization. Defaults to "Authorization".
value (required) <string> - 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 <boolean> - 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:


Code
{
  "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:


Code
{
  "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.