> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# AWS IoT Core

> Client-mode REST API connector for a curated AWS IoT Core slice: HTTPS Publish, Device Shadow GET/POST, CreateJob (OTA), and ListThings

Technical Preview

## Overview

A client-mode connector for a **curated cloud-IoT** slice of [AWS IoT Core](https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html) covering registry, Jobs/OTA, classic Device Shadow, and HTTPS data-plane publish (no MQTT bridge):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| GET ListThings | `GET /things` | Control-plane auth smoke |
| POST CreateJob (OTA) | `PUT /jobs/{jobId}` | AWS uses **PUT** (catalog named it POST CreateJob) |
| GET things/\{name}/shadow | `GET /things/{thingName}/shadow` | Classic Device Shadow |
| POST things/\{name}/shadow | `POST /things/{thingName}/shadow` | Classic Device Shadow update |
| POST topics/\{topic} | `POST /topics/{topic}?qos=0\|1` | Data-plane HTTPS publish — switch BASE to ATS endpoint |

Default `BASE_ADDRESS` is control-plane `https://iot.eu-west-1.amazonaws.com` (no trailing slash; substitute `{region}`). Topics use `cloud-iot/aws-iot-core/<object>/<verb>`.

See the base guide: [REST API Connectors](/latest/lot-language/routes/rest-api-routes).

> [!NOTE]
>
> **Data-plane Publish:** set `BASE_ADDRESS` to your ATS endpoint from `aws iot describe-endpoint --endpoint-type iot:Data-ATS` (for example `https://xxxxxx-ats.iot.eu-west-1.amazonaws.com`). SigV4 service name on the data plane is `iotdevicegateway` (port 443). X.509 on `:8443` is AWS-supported but outside this LoT template.

> [!NOTE]
>
> **Control-plane SigV4 service name** is `iot`. Pass `Authorization`, `x-amz-date`, and `x-amz-content-sha256` from an upstream signer via MQTT JSON placeholders. Prefer Hub secrets for AWS keys — never commit them into the `.lot`.

> [!NOTE]
>
> Prefer Hub secrets for AWS keys used by an upstream SigV4 signer. This template has not been verified against a live AWS account. Status remains blocked until an authenticated live smoke succeeds.

## Basic Syntax

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
# Coreflux REST_API template — AWS IoT Core curated slice
# Auth: SigV4 via {value.json.authorization}, {value.json.x_amz_date},
#       {value.json.x_amz_content_sha256}
# BASE_ADDRESS: https://iot.eu-west-1.amazonaws.com (control plane)

DEFINE ROUTE AwsIotCoreRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://iot.eu-west-1.amazonaws.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/json"
    ADD EVENT ListThings
        WITH SOURCE_TOPIC "cloud-iot/aws-iot-core/things/list"
        WITH DESTINATION_TOPIC "cloud-iot/aws-iot-core/things/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/things?maxResults={value.json.max_results}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
    ADD EVENT CreateJob
        WITH SOURCE_TOPIC "cloud-iot/aws-iot-core/jobs/create"
        WITH DESTINATION_TOPIC "cloud-iot/aws-iot-core/jobs/create/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/jobs/{value.json.job_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
        WITH BODY "{payload}"
    ADD EVENT GetThingShadow
        WITH SOURCE_TOPIC "cloud-iot/aws-iot-core/shadow/get"
        WITH DESTINATION_TOPIC "cloud-iot/aws-iot-core/shadow/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/things/{value.json.thing_name}/shadow"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
    ADD EVENT UpdateThingShadow
        WITH SOURCE_TOPIC "cloud-iot/aws-iot-core/shadow/update"
        WITH DESTINATION_TOPIC "cloud-iot/aws-iot-core/shadow/update/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/things/{value.json.thing_name}/shadow"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
        WITH BODY "{payload}"
    ADD EVENT PublishTopic
        WITH SOURCE_TOPIC "cloud-iot/aws-iot-core/topics/publish"
        WITH DESTINATION_TOPIC "cloud-iot/aws-iot-core/topics/publish/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/topics/{value.json.topic}?qos={value.json.qos}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
            ADD "x-amz-date" "{value.json.x_amz_date}"
            ADD "x-amz-content-sha256" "{value.json.x_amz_content_sha256}"
        WITH BODY "{payload}"
```

## Configuration

| Setting | Value |
| - | - |
| Connector name | `AwsIotCoreRestApi` |
| Type | `REST_API` (client) |
| BASE\_ADDRESS | `https://iot.eu-west-1.amazonaws.com` (control plane; change region as needed) |
| Topic prefix | `cloud-iot/aws-iot-core/...` |
| Default Content-Type | `application/json` |
| Auth | SigV4 headers from MQTT placeholders |
| Status | Technical preview — needs AWS keys (+ data endpoint for Publish) |

## MQTT topics

| Event | Source | Response |
| - | - | - |
| ListThings | `cloud-iot/aws-iot-core/things/list` | `.../things/list/response` |
| CreateJob | `cloud-iot/aws-iot-core/jobs/create` | `.../jobs/create/response` |
| GetThingShadow | `cloud-iot/aws-iot-core/shadow/get` | `.../shadow/get/response` |
| UpdateThingShadow | `cloud-iot/aws-iot-core/shadow/update` | `.../shadow/update/response` |
| PublishTopic | `cloud-iot/aws-iot-core/topics/publish` | `.../topics/publish/response` |

## Auth details

1. Sign each request with AWS Signature Version 4 using the correct **service name** (`iot` on control plane; `iotdevicegateway` on data-plane Publish).
2. Map signed values into MQTT JSON: `authorization`, `x_amz_date`, `x_amz_content_sha256` (and optional STS session token).
3. Store `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` as Hub secrets for the upstream signer — never in the deployable `.lot`.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [Amazon S3](/latest/lot-language/routes/rest-api-apps/amazon-s3) (same SigV4 placeholder pattern)
* [AWS IoT ListThings](https://docs.aws.amazon.com/iot/latest/apireference/API_ListThings.html)
* [AWS IoT CreateJob](https://docs.aws.amazon.com/iot/latest/apireference/API_CreateJob.html)
* [Device Shadow REST API](https://docs.aws.amazon.com/iot/latest/developerguide/device-shadow-rest-api.html)
* [HTTPS publish](https://docs.aws.amazon.com/iot/latest/developerguide/http.html)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.