# HTTP Entry Point

Forward HTTP requests to a single HTTP/HTTPS destination.

This entry point accepts HTTP requests from an Air for Cellular device and forwards the request to the forwarding destination via HTTP or HTTPS. You can create multiple HTTP entry point configurations, provided the **path** parameter is unique for each configuration.

## Configuration

### Entry Point

Your device should be configured to send data to: `http://beam.soracom.io:8888/{my-custom-path}`.

### Parameters

- **Configuration name** (_string_, required) - A string to identify this configuration.

- **Entry point** - The HTTP entry point configuration.
  - **Path** (_string_, optional) - The URI path where Beam will accept data. This path is appended to the Beam HTTP entry point.

- **Destination** - The forwarding destination.

  - **Protocol** (`HTTP` or `HTTPS`, required) - The protocol to use for forwarding HTTP requests.
  - **Host name** (_string_, required) - The FQDN of the forwarding destination.
  - **Port number** (_number_, required) - The port number of the forwarding destination.
  - **Path** (_string_, optional) - The URI path to use for forwarding HTTP requests.

- **Client Certificate** - The SSL/TLS client authentication configuration.

  - **Use client cert** - Enables the use of a client certificate for authentication.
  - **Credentials set** - The client certificate stored in [Credential Sets](https://docs.soracom.io/en/services/authentication/credential-sets) to use for authentication.

- **Header manipulations** - Operations to perform on the HTTP request headers.

  - **IMSI header** - Adds `X-Soracom-IMSI: {IMSI}` to the HTTP request header.
  - **SIM ID header** - Adds `X-Soracom-SIM-ID: {SIM_ID}` to the HTTP request header.
  - **MSISDN header** - Adds `X-Soracom-MSISDN: {MSISDN}` to the HTTP request header.
  - **IMEI header** - Adds `X-Soracom-IMEI: {IMEI}` to the HTTP request header.
  - **Signature header** - Adds `X-Soracom-Signature: {Signature}` to the HTTP request header. This option requires **IMSI header** or **IMEI header** to be enabled in order to generate the signature.
  - **Pre-Shared Key** - The key to use when generating the **Signature header**.
  - **Custom headers** - Additional options for adding, modifying, or removing headers from HTTP requests before they are forwarded to the destination.
  - **Authorization header** - Adds `Authorization: {Parameter}` to the HTTP request header.

For details on configuring and using header manipulations, refer to the [Header Manipulation](https://docs.soracom.io/en/services/beam/header-manipulation) page.

## Behavior

### Request Behavior

When Beam receives an HTTP request, it will close the original request and forward the request to the forwarding destination.

### Response Behavior

When Beam receives an HTTP response from the forwarding destination, it transfers the response directly to the device. [Hop-by-hop headers](https://www.rfc-editor.org/rfc/rfc9110.html#section-7.6.1), such as `Connection` and `Keep-Alive`, are exceptions and are not guaranteed to be forwarded to the device.

### Example

```bash
curl -v -X POST -H 'Content-Type: application/json' -d '{"key":"value"}' http://beam.soracom.io:8888/

*   Trying 100.127.127.100...
* Connected to beam.soracom.io (100.127.127.100) port 8888 (#0)
> POST / HTTP/1.1
> Host: beam.soracom.io:8888
> User-Agent: curl/7.49.0
> Accept: */*
> Content-Type:application/json
> Content-Length: 15
>
* upload completely sent off: 15 out of 15 bytes
< HTTP/1.1 200 OK
< Content-Type: application/json
< Date: Wed, 21 Dec 2016 02:25:01 GMT
< Connection: close
< Transfer-Encoding: chunked
<
* Closing connection 0
```

## Advanced Configuration

The HTTP entry point can also be configured through the Soracom API or CLI by using the **SoracomBeam** namespace.

Configuration should be performed using `http://beam.soracom.io:8888/` as the configuration **key** value.

### Parameters

- **key** (_string_, required) - `http://beam.soracom.io:8888/`

- **value** (_object_, required) - The configuration parameters.

  - **name** (_string_, optional) - Name to identify this configuration.

  - **destination** (_string_, required) - URL of the forwarding destination.

  - **enabled** (_boolean_, required) - Enables or disables the configuration.

  - **useClientCert** (_boolean_, optional) - Enables or disables the use of an SSL/TLS client certificate for authentication.

  - **clientCerts** (_object_, optional) - The SSL/TLS client certificates to attach.
    - **$credentialsId** (_string_, optional) - ID of the credential set with the appropriate client certificate.

  - **addSubscriberHeader** - (_boolean_, optional) - Enables or disables adding the subscriber IMSI as an HTTP header in the forwarded request.

  - **addSimIdHeader** - (_boolean_, optional) - Enables or disables adding the SIM ID as an HTTP header in the forwarded request.

  - **addMsisdnHeader** - (_boolean_, optional) - Enables or disables adding the SIM MSISDN as an HTTP header in the forwarded request.

  - **customHeaders** (_object_, optional) - Defines custom headers behavior. Each custom header is defined using:

    - `X-Header-Name` (_string_, required) - Name of the custom header.

      - **action** (_string_, required) - Defines the header behavior using one of the following values:

        - `append` - Appends the defined header to the HTTP request.
        - `replace` - Replaces any existing header with the defined header value.
        - `delete` - Deletes the header from the HTTP request.

      - **headerKey** (_string_, required) - The header name.

      - **headerValue** (_string_, required) - The header value.

  - **addSignature** (_boolean_, required) - Enables or disables adding a signature header for subscriber verification

  - **psk.$credentialsId** (_string_, optional) - The ID assigned to the pre-shared key credential set. Used for signing when `addSignature` is set as `true`. This ID is set when the credential is registered in the [Credentials Store](https://docs.soracom.io/en/services/authentication/credential-sets).

  - **addAuthorizationHeader** (_object_, optional) - Defines authorization header behavior. Each authorization header is defined using:

    - **enabled** (_boolean_, required) - Enables or disables adding a authorization header.

    - **type** (_string_, required) - Defines the authorization header type using one of the following values:

      - `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_sig_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.

    - **config** (_object_, required) - The settings for the authorization header based on the **type**.

      - If the **type** is `bearer_jwt`:

        - **jwtClaims** (_object_, required) - The information used to generate the JSON web token. For example:

          ```json
          {
              "iss": "soracom-beam@long-stack-371107.iam.gserviceaccount.com",
              "sub": "soracom-beam@long-stack-371107.iam.gserviceaccount.com",
              "aud": "https://pubsub.googleapis.com/google.pubsub.v1.Publisher"
            }
          ```

          `iat` and `exp` are automatically generated when a device accesses Beam.

        - **credentials.$credentialsId** (_string_, required) - The credential ID of the Google Service Account (JSON) or private key (PEM) registered in the [Credentials Store](https://docs.soracom.io/en/services/authentication/credential-sets).

        - **algorithm** (_string_, required) - Used to specify the signature algorithm. Valid choices are `RS256`, `ES256`, `RS512`, or `ES512`.

      - If the **type** is `aws_sig_v4`:

        - **service** (_string_, required) - Choose `lambda` or `sagemaker`. `geo` and `s3` are not availble as HTTP entry points.
        - **region** (_string_, required) - Specify your AWS resource region. For example: `ap-northeast-1`.
        - **credentials.$credentialsId** (_string_, required) - The credential ID of the AWS IAM role credential registered in the [Credentials Store](https://docs.soracom.io/en/services/authentication/credential-sets).

      - If the **type** is `bearer`:
        - **credentials.$credentialsId** (_string_, required) - The credential ID of the API token credential or pre-shared key credential registered in the [Credentials Store](https://docs.soracom.io/en/services/authentication/credential-sets).

      - If the **type** is `basic`:
        - **credentials.$credentialsId** (_string_, required) - The credential ID of the username/password credential registered in the [Credentials Store](https://docs.soracom.io/en/services/authentication/credential-sets).

### Sample

```json
[
  {
    "key": "http://beam.soracom.io:8888/",
    "value": {
      "name": "My Beam config",
      "destination": "https://myserver.example.com/",
      "enabled": true,
      "addSubscriberHeader": true,
      "addSimIdHeader": true,
      "addMsisdnHeader": true,
      "customHeaders": {
        "X-Group-Name": {
          "action": "replace",
          "headerKey": "X-Group-Name",
          "headerValue": "My header value"
        }
      },
      "addSignature": true,
      "psk": {
        "$credentialsId": "CredentialsID"
      },
      "addAuthorizationHeader": {
        "enabled": false
      }
    }
  }
]
```