Request signers

Some data source APIs require cryptographic request signatures to authenticate or verify the integrity of outgoing API requests. Request signers allow you to add HMAC or RSA signatures to your requests without custom code — all logic is defined in the connector JSON configuration.

Most data sources do not require request signing. Use request signers only when the API you are connecting to requires computed cryptographic signatures in headers, query parameters, or the request body.

Note: Request signing is not the same as authentication. Signing verifies the integrity or origin of individual requests, while authentication establishes the identity of the user or application. Some APIs require both — for example, an API key for authentication and a signed hash for request verification. Configure authentication separately using the Authentication component.

How signers work

Signers are defined at the connector root level under the signers property as an array. Each signer:

1. Builds a payload string from a template containing request data, timestamps, nonces, and secrets.
2. Optionally signs the payload using HMAC or RSA with a specified hash algorithm.
3. Produces a signature value that you can inject into request headers, query parameters, or body using the {{signer.signature}} placeholder.

When no algorithm is configured, the signer acts as a template-based string builder — {{signer.signature}} returns the resolved payload directly without cryptographic processing.

Supported signer types

Note: RSA signers do not support sha1 or md5 hashes. Using these with RSA will cause a runtime error.

Configuration template

Below you can find a template for the signers configuration:

{
  "signers": [
    {
      "id": "[unique_signer_id]",
      "payload": "[template string defining the content to sign]",
      "algorithm": {
        "type": "[hmac or rsa]",
        "hash": "[hash algorithm, e.g. sha256]",
        "secret": {
          "source": "secret",
          "value": "[registered secret ID, e.g. customer_secret]"
        }
      },
      "output": {
        "encoding": "[hex, hex_upper, base64, or url_safe_base64]"
      },
      "timestamp": {
        "format": "[U or U.u]"
      },
      "nonce": {
        "length": "[number of characters]"
      },
      "request": {
        "parameters": {
          "sort": "[boolean]",
          "exclude": ["[parameter names to exclude]"],
          "separator": "[separator between parameters]",
          "keyValueSeparator": "[separator between key and value]"
        }
      }
    }
  ]
}

Available placeholders

The following placeholders are available within signer templates:

Signer output

Signer metadata

Request values

Standard placeholders

You can also use standard connector placeholders within signer templates, such as {{secrets.*}}, {{user.properties.*}}, and {{oauth2.*}}.

Example: HMAC-SHA256 signer

Below you can find an example of an HMAC-SHA256 signer that builds a signature from the app secret, request path, and sorted query parameters. This pattern is common for APIs that require a signed query parameter to verify request authenticity.

{
  "signers": {
    "items": [
      {
        "id": "api_hmac",
        "payload": "{{ secrets.app_secret }}{{ signer.request.path }}{{ signer.request.query_params }}{{ secrets.app_secret }}",
        "timestamp": {
          "format": "U"
        },
        "algorithm": {
          "type": "hmac",
          "hash": "sha256",
          "secret": {
            "source": "secret",
            "value": "secret_id"
          }
        },
        "output": {
          "encoding": "hex_upper"
        },
        "request": {
          "parameters": {
            "sort": "asc",
            "exclude": ["sign"],
            "separator": "",
            "keyValueSeparator": ""
          }
        }
      }
    ]
  }
}

And this is how this signer is used in a request

{
  "url": "https://api.example.com/v1/products",
  "signer": { "id": "api_hmac" },
  "headers": [],
  "queryParameters": [
    { "key": "app_key", "value": "{{ user.properties.app_key }}" },
    { "key": "timestamp", "value": "{{ signer.metadata.timestamp }}" },
    { "key": "sign", "value": "{{ signer.signature }}" }
  ]
}

In this example:

• The payload concatenates the app secret, request path, and sorted query parameters (excluding the sign parameter itself).
• The payload is signed using HMAC with SHA-256 and the app secret as the key.
• The output is encoded as uppercase hexadecimal.

Example: RSA-SHA256 signer

Below you can find an example of an RSA-SHA256 signer that signs a payload containing a consumer ID, timestamp, and key version. This pattern is used by APIs that require public-key cryptographic verification.

{
  "signers": {
    "items": [
      {
        "id": "walmart_rsa",
        "payload": "{{ user.properties.consumer_id }}\n{{ signer.metadata.timestamp }}\n{{ user.properties.key_version }}\n",
        "timestamp": {
          "format": "U.u",
          "roundPrecision": 0,
          "useMilliseconds": true
        },
        "algorithm": {
          "type": "rsa",
          "hash": "sha256",
          "secret": {
            "source": "secret",
            "value": "secret_id"
          }
        },
        "output": {
          "encoding": "base64"
        }
      }
    ]
  }
}

How it's used in a request.

{
  "url": "https://developer.api.walmart.com/api-proxy/service/...",
  "signer": { "id": "walmart_rsa" },
  "headers": [
    { "key": "WM_SEC.AUTH_SIGNATURE", "value": "{{ signer.signature }}" },
    { "key": "WM_CONSUMER.ID", "value": "{{ user.properties.consumer_id }}" },
    { "key": "WM_SEC.TIMESTAMP", "value": "{{ signer.metadata.timestamp }}" },
    { "key": "WM_SEC.KEY_VERSION", "value": "{{ user.properties.key_version }}" },
    { "key": "WM_QOS.CORRELATION_ID", "value": "{{ signer.request.id }}" }
  ]
}

In this example:

• The payload combines the consumer ID, a Unix timestamp, and a key version, separated by newlines.
• The payload is signed using RSA with SHA-256 and a PEM private key stored as a secret.
• The output is encoded as Base64.

Example: String builder (no algorithm)

Below you can find an example of a signer without a cryptographic algorithm. In this case, the signer concatenates values into a string, which is useful for APIs that require a simple computed value rather than a cryptographic signature.

{
  "signers": {
    "items": [
      {
        "id": "auth_string",
        "payload": "{{ user.properties.api_key }}:{{ signer.metadata.timestamp }}:{{ signer.metadata.nonce }}",
        "timestamp": {
          "format": "U"
        },
        "nonce": {
          "length": 16
        }
      }
    ]
  }
}

In this example:

• The payload concatenates the API key, a Unix timestamp, and a 32-character random nonce.
• No algorithm is specified, so {{signer.signature}} returns the concatenated string directly.

Property reference

Complete property reference for a signer item:

*Required when the parent object is present.