Header Manipulation

When Soracom Beam fowards connections from an Air device to your endpoint, you can optionally enable header manipulation in order to add device information to the connection requests.

For example, a device may be configured to only send raw sensor data to Beam. Once Beam receives the data, it can add additional information to the data transmission (such as the SIM IMSI or device IMEI number), allowing your server to identify the source of the data or verify authorization. This lets you reduce cellular data usage by removing the need of including a device ID to the initial payload, and also removes the need of storing pre-shared keys directly on each device.

The types of header manipulations available vary based on the type of device (cellular, Sigfox, or LoRaWAN) and destination protocol (HTTP/HTTPS, TCP/TCPS, or MQTT/MQTTS).

Device Type HTTP/HTTPS TCP/TCPS MQTT/MQTTS
Air for Cellular IMSI
IMEI
Signature
Custom
IMSI
IMEI
Signature
IMSI
Air for Sigfox
Air for LoRaWAN
Operator ID
Device ID
Signature
Custom
- -

Header Manipulation Options

IMSI Header

Air for Cellular only

Adds the SIM card IMSI to the header or message topic.


IMEI Header

Air for Cellular only

Adds the device IMEI to the request header or packet data.


Device ID Header

Air for Sigfox and Air for LoRaWAN only

Appends X-Soracom-LoRa-Device-Id: {device id} or X-Soracom-Sigfox-Device-Id: {device id} to the HTTP/HTTPS request header.


Signature Header

All Air devices

Adds a SHA-256 signature to the header for authenticating the validity of the request against a pre-shared key. Because headers are added by Beam in the cloud, the device itself does not need to perform SHA-256 calculations (save energy), append additional headers (reduce data usage), or store pre-shared keys (improve security).

Usage with Air for Cellular devices

Enabling the Signature option requires either the IMSI Header or IMEI Header option to be enabled, and will append a signature version and timestamp header to the request. A pre-shared key must also be selected.

When selecting HTTP/HTTPS as the destination protocol, the following headers are appended to the request:

When selecting TCP/TCPS as the destination protocol, the following data is added to the packet data as the first line:

Once you receive the connection request on your endpoint server, you can verify the SHA-256 signature by combining the header information and pre-shared key:

SHA256("{PSK}x-soracom-imei={IMEI}x-soracom-imsi={IMSI}x-soracom-timestamp={timestamp}")

For information on how to use the Signature header to verify incoming data, refer to the Signature Verification documentation.

Note: If you are forwarding data using MQTT/MQTTS to a cloud-based MQTT broker (such as Azure IoT Hub, Google IoT Core, PubNub, Watson IoT Platform, or other broker), authentication is performed using MQTT authentication and credential sets rather than pre-shared keys. Refer to MQTT Entry Point configuration for further information.

Usage with Air for Sigfox and Air for LoRaWAN devices

Enabling the Signature option requires the Device ID option to be enabled, and will append a timestamp header to the request. A pre-shared key must also be selected.

The HTTP/HTTPS request will contain the following headers:

Once you receive the connection request on your endpoint server, you can verify the SHA-256 signature by combining the header information and pre-shared key:

SHA256("{pre-shared key}x-soracom-lora-device-id={device id}x-soracom-timestamp={timestamp}")
# or
SHA256("{pre-shared key}x-soracom-sigfox-device-id={device id}x-soracom-timestamp={timestamp}")

Custom Headers

All Air devices

Appends, replaces, or deletes headers from HTTP/HTTPS requests. Headers will be added, replaced, or removed based on the rules set before being forwarded to your destination endpoint.