> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/adapters/configure/headers/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Configure headers

> How adapters handle request and response headers, and how to add static or dynamic headers to specific calls or all calls.

Adapters automatically add `Content-Type` and `Accept` headers based on the `requestDatatype` and `responseDatatype` defined in `action.json`. They also calculate and add a `Content-Length` header to any call that includes a payload. Both can be overridden. Authentication headers should be configured through `auth_field` and `auth_field_format` in the service instance configuration — not through the methods described here.

## Choosing where to add a header

The right place to add a header depends on two questions:

1. Is the header value **static** (the same on every call) or **dynamic** (different per call)?
2. Should the header apply to a **specific call** or to **all calls**?

|             | Specific call                                                       | All calls                                                           |
| ----------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- |
| **Static**  | `headers` object in `action.json`                                   | `global_request.addlHeaders` in the service instance configuration  |
| **Dynamic** | `addlHeaders` in the `reqObj` in `adapter.js`, or via `iapMetadata` | `addlHeaders` in the `reqObj` in `adapter.js`, or via `iapMetadata` |

Both static approaches override the headers the adapter sets automatically from `requestDatatype`.

Setting an incorrect `requestDatatype` can have unintended side effects beyond just the headers, since the default is `JSON`.

## Static headers

To add a static header to a **specific call**, define it in the `headers` object in `action.json`. See [Action field definitions](/adapters/configure/schemas/field-definitions) for details and examples.

To add a static header to **all calls**, define it in `global_request.addlHeaders` in the service instance configuration. See [Request properties](/adapters/configure/service-instance-configuration/properties/request-properties) for details and examples.

## Dynamic headers

To add a dynamic header — one whose value is not known until the call is made — pass it in `addlHeaders` on the `reqObj` in `adapter.js`. This requires exposing a parameter in the adapter method and in `pronghorn.json` to accept the dynamic value.

If the adapter method exposes an `iapMetadata` object, you can pass dynamic headers through that object without any code changes. See [Add dynamic headers](./add-dynamic-headers) for details and examples.

---

title: Add dynamic headers
sidebar-title: Add dynamic headers
slug: headers/add-dynamic-headers
description: How to add headers with values that are not known until call time, using iapMetadata or adapter.js code changes.
-----------------------------------------------------------------------------------------------------------------------------

A header is dynamic when its value is not known until the call is made. Static header configuration in `action.json` or the service instance configuration cannot accommodate this — the header value must be supplied at call time.

## Using iapMetadata (no code change required)

If the adapter method exposes an `iapMetadata` parameter, pass the headers inside an `addlHeaders` object on that parameter. You can construct the `iapMetadata` object usingItential Platform workflow capabilities such as `query` and `merge`.

Structure:

```json
{
  "addlHeaders": {
    "<header1_name>": "<value1>",
    "<header2_name>": "<value2>"
  }
}
```

Example:

```json
{
  "addlHeaders": {
    "x_custom_header": "63121931219fdd",
    "Session-id": "AB9637462349"
  }
}
```

If the adapter method does not have an `iapMetadata` parameter, you can request that the Adapter Team add it. Note that adding `iapMetadata` requires creating new methods — Itential does not modify existing method signatures to avoid breaking changes.

## Using adapter.js (code change required)

If the adapter does not support `iapMetadata`, you can expose the dynamic header value as a parameter in the adapter method and set it in `addlHeaders` on the `reqObj`. This approach also requires updating `pronghorn.json` to match the new method signature.

See [Call properties authentication](/adapters/customize/examples#individual-call-properties) for an example of this pattern applied to authentication, which follows the same approach.

## Static headers

If the header value does not change between calls, use the static header options instead.

> How adapters handle request and response headers, and how to add static or dynamic headers to specific calls or all calls.