# Header Manipulation

Add, remove, or rewrite HTTP request headers for forwarded device data.

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).

**Additional Header Options**

Beam's header manipulation feature now also supports MSISDN and SIM ID values.

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

## Header Manipulation Options

### IMEI Header

**Air for Cellular** only

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

- When selecting **HTTP/HTTPS** as the destination protocol, `x-soracom-imei: {IMEI}` is appended to the request header.
- When selecting **TCP/TCPS** as the destination protocol, `imei={IMEI}` is added as part of the first line of the packet data.

---

### IMSI Header

**Air for Cellular** only

Adds the SIM card IMSI to the request header, packet data, or message topic.

- When the destination protocol is **HTTP/HTTPS**, `x-soracom-imsi: {IMSI}` is appended to the request header.
- When the destination protocol is **TCP/TCPS**, `imsi={IMSI}` is added as part of the first line of the packet data.
- When the destination protocol is **MQTT/MQTTS**, `/{IMSI}` is appended to the message topic. For example, if your device is configured to publish to `/my/topic`, the messages will be published to `/my/topic/{IMSI}`.

---

### MSISDN Header

**Air for Cellular** only

Adds the SIM card MSISDN to the header or packet data.

- When the destination protocol is **HTTP/HTTPS**, `x-soracom-msisdn: {MSISDN}` is appended to the request header.
- When the destination protocol is **TCP/TCPS**, `msisdn={MSISDN}` is added as part of the first line of the packet data.

---

### SIM ID Header

**Air for Cellular** only

Adds the SIM ID to the header or packet data. Useful if your SIM contains multiple [Subscription Containers](https://docs.soracom.io/en/services/air/subscription-containers) and you want to identify the incoming request by SIM rather than by its individual IMSIs.

- When the destination protocol is **HTTP/HTTPS**, `x-soracom-sim-id: {SIM-ID}` is appended to the request header.
- When the destination protocol is **TCP/TCPS**, `simId={SIM ID}` is added as part of the first line of the 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 one or more of the **IMEI Header**, **IMSI Header**, **MSISDN Header**, or **SIM ID Header** options to be enabled, and will append **SHA-256 signature**, **signature version**, and **timestamp** data to the request header or packet data. A **pre-shared key** must also be selected.

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

- `x-soracom-imei: {IMEI}`
- `x-soracom-imsi: {IMSI}`
- `x-soracom-msisdn: {MSISDN}`
- `x-soracom-sim-id: {SIM-ID}`
- `x-soracom-timestamp: {timestamp}`
- `x-soracom-signature: {SHA-256 signature}`
- `x-soracom-signature-version: 20151001`

On your server application, you can then combine the header data using the following format, and calculate the SHA-256 value to verify that it matches the value in the `x-soracom-signature` header:

```
SHA256("{pre-shared key}x-soracom-imei={IMEI}x-soracom-imsi={IMSI}x-soracom-msisdn={MSISDN}x-soracom-sim-id={SIM-ID}x-soracom-timestamp={timestamp}")
```

> [!NOTE]
>
> Note that the `header: value` format in the HTTP request header is replaced with a `header=value` format, and that each header, including the pre-shared key and timestamp, should be concatenated _without_ spaces in between.
>
> Additionally, as the HTTP request headers may arrive in a different order, your server application should always concatenate these headers in the following order:
>
> - Pre-shared key
> - IMEI
> - IMSI
> - MSISDN
> - SIM ID
> - Timestamp

> [!WARNING]
>
> Depending on which header manipulations you have enabled, some headers may not be appended to the HTTP/HTTPS request. If you have not enabled certain header manipulation options, simply omit them from the concatenated string when calculating the SHA-256 signature value.

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

- `imei={IMEI} imsi={IMSI} msisdn={MSISDN} simId={SIM-ID} timestamp={timestamp};signature={SHA-256 signature} version=20151001`

On your server application, you can simply combine your pre-shared key with the header manipulation values _before_ the semicolon `;`, and calculate the SHA-256 value to verify that it matches the value in the `signature` data:

```
SHA256("{pre-shared key}imei={IMEI} imsi={IMSI} msisdn={MSISDN} simId={SIM-ID} timestamp={timestamp}")
```

For information on how to use the Signature header to verify incoming data, refer to the [Signature Verification](https://docs.soracom.io/en/services/beam/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, 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:

- `x-soracom-lora-device-id: {DEVICE-ID}` or `x-soracom-sigfox-device-id: {DEVICE-ID}`
- `x-soracom-timestamp: {timestamp}`

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.

---

### Authorization Header

**HTTP or Website entry points only**

Adds an `Authorization` header to the HTTP request. There are 4 types in this header. Also see [Credential Sets](https://docs.soracom.io/en/services/authentication/credential-sets) to understand credential sets.

| Type | Description |
| - | - |
| Bearer JWT | Add an `Authorization: Bearer {token}` header to use the Bearer scheme defined in [RFC 6750](https://www.rfc-editor.org/rfc/rfc6750). In `{token}`, a JSON Web Token (JWT) issued using "Google Service Account (JSON)" credential set or "Private Key (PEM)" credential set will be inserted. |
| AWS Signature V4 | Add [AWS Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/signing-aws-api-requests.html). AWS Signature version 4 is generated using "AWS credentials" credential set or "AWS IAM Role credentials" credential set. |
| Bearer | Add an `Authorization: Bearer {token}` header to use the Bearer scheme defined in [RFC 6750](https://www.rfc-editor.org/rfc/rfc6750). In `{token}`, "API Token credentials" or "Pre-Shared Key" credential set will be inserted. |
| Basic | Add an `Authorization: Basic {credentials}` header to use Basic authentication as defined in [RFC 7617](https://www.rfc-editor.org/rfc/rfc7617.txt). In `{credentials}`, a Base64 string generated from the user name and password set in "Username password credentials" credential set is inserted. |