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

# Amazon SNS

> Client-mode REST API connector for a curated Amazon SNS slice: Publish to topic ARN, Publish SMS, ListTopics, GetTopicAttributes, CreateTopic, and Subscribe from MQTT; HTTPS subscription confirm/receive is an ENABLE_SERVER companion

Technical Preview

## Overview

A client-mode connector for a **curated messaging / notifications** slice of [Amazon SNS](https://docs.aws.amazon.com/sns/latest/dg/welcome.html):

| Catalog connector event | Entity / path | Notes |
| - | - | - |
| POST Publish (topic) | `POST /` on `sns.{region}.amazonaws.com` | Query `Action=Publish&Version=2010-03-31` + `TopicArn` + `Message`; SigV4 service `sns`; expect **200** XML `MessageId` |
| POST Publish SMS | `POST /` (same host) | Same Publish action with `PhoneNumber` (E.164) instead of `TopicArn` |
| ListTopics | `POST /` | Preferred auth smoke → **200** XML topic list |
| GetTopicAttributes | `POST /` | Topic property map |
| CreateTopic | `POST /` | Create / idempotent get by name |
| Subscribe | `POST /` | e.g. `Protocol=https` + `Endpoint`; pending until confirmed |
| Confirm / receive HTTPS subscription | inbound HTTPS | **ENABLE\_SERVER companion** (docs only — not in this client `.lot`); client `ConfirmSubscription` Query action optional in a fork |

Default `BASE_ADDRESS` is `https://sns.eu-west-1.amazonaws.com`. Topics use `messaging/amazon-sns/<object>/<verb>`. Official protocol is **Query** form-urlencoded (XML responses), not CloudWatch-style JSON `X-Amz-Target`.

> [!NOTE]
>
> Prefer Hub secrets for `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_REGION` used by an upstream SigV4 signer. Pass `Authorization`, `x-amz-date`, and `x-amz-content-sha256` on each MQTT payload — this is **not** Bearer auth. 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 — Amazon SNS (Query API 2010-03-31)
# Auth: SigV4 headers from MQTT payload (NOT Bearer)
# BASE_ADDRESS: https://sns.eu-west-1.amazonaws.com

DEFINE ROUTE AmazonSnsRestApi WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://sns.eu-west-1.amazonaws.com"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '60'
        WITH DEFAULT_CONTENT_TYPE "application/x-www-form-urlencoded"
    ADD EVENT Publish
        WITH SOURCE_TOPIC "messaging/amazon-sns/topic/publish"
        WITH DESTINATION_TOPIC "messaging/amazon-sns/topic/publish/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/xml"
            ADD "Content-Type" "application/x-www-form-urlencoded"
            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 Publishsms
        WITH SOURCE_TOPIC "messaging/amazon-sns/sms/publish"
        WITH DESTINATION_TOPIC "messaging/amazon-sns/sms/publish/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/xml"
            ADD "Content-Type" "application/x-www-form-urlencoded"
            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 Listtopics
        WITH SOURCE_TOPIC "messaging/amazon-sns/topics/list"
        WITH DESTINATION_TOPIC "messaging/amazon-sns/topics/list/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/xml"
            ADD "Content-Type" "application/x-www-form-urlencoded"
            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 Gettopicattributes
        WITH SOURCE_TOPIC "messaging/amazon-sns/topic/get-attributes"
        WITH DESTINATION_TOPIC "messaging/amazon-sns/topic/get-attributes/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/xml"
            ADD "Content-Type" "application/x-www-form-urlencoded"
            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 Createtopic
        WITH SOURCE_TOPIC "messaging/amazon-sns/topic/create"
        WITH DESTINATION_TOPIC "messaging/amazon-sns/topic/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/xml"
            ADD "Content-Type" "application/x-www-form-urlencoded"
            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 Subscribe
        WITH SOURCE_TOPIC "messaging/amazon-sns/topic/subscribe"
        WITH DESTINATION_TOPIC "messaging/amazon-sns/topic/subscribe/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/"
        WITH HEADERS
            ADD "Accept" "application/xml"
            ADD "Content-Type" "application/x-www-form-urlencoded"
            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}"
```

## Authentication

| Mode | Header | Notes |
| - | - | - |
| AWS Signature Version 4 | `Authorization: {value.json.authorization}` (+ `x-amz-date`, `x-amz-content-sha256`) | Default in this template — **not** Bearer |

Sign with service name `sns` and a region matching the host. Store `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_REGION` (optional `AWS_SESSION_TOKEN`) in Hub secrets and resolve via an upstream signer + `GET SECRET` — never commit credentials.

## MQTT examples

**ListTopics** (preferred smoke; form body):

```
Action=ListTopics&Version=2010-03-31
```

Expect **HTTP 200**.

**Publish** to topic:

```
Action=Publish&Version=2010-03-31&TopicArn=arn%3Aaws%3Asns%3Aeu-west-1%3A123456789012%3Acoreflux-plant&Message=vibration_rms%3D12.4&Subject=Plant%20alarm
```

Expect **HTTP 200** with `MessageId`.

**Publish SMS:**

```
Action=Publish&Version=2010-03-31&PhoneNumber=%2B351912345678&Message=Plant%20alarm
```

**Subscribe** HTTPS:

```
Action=Subscribe&Version=2010-03-31&TopicArn=arn%3Aaws%3Asns%3Aeu-west-1%3A123456789012%3Acoreflux-plant&Protocol=https&Endpoint=https%3A%2F%2Fbroker.example.com%2Fsns%2Fplant&ReturnSubscriptionArn=true
```

Include SigV4 header fields (`authorization`, `x_amz_date`, `x_amz_content_sha256`) on the MQTT JSON envelope; put the form string in the HTTP body (`{payload}`).

## ENABLE\_SERVER companion

When SNS delivers **SubscriptionConfirmation** / **Notification** / **UnsubscribeConfirmation** to your HTTPS endpoint, handle them with a separate `ENABLE_SERVER` connector (not packaged here). Confirm with the client [ConfirmSubscription](https://docs.aws.amazon.com/sns/latest/api/API_ConfirmSubscription.html) Query action (`Token` + `TopicArn`) or by GETting the `SubscribeURL` from the confirmation payload.

## Related

* [REST API Connectors](/latest/lot-language/routes/rest-api-routes)
* [Amazon CloudWatch](/latest/lot-language/routes/rest-api-apps/amazon-cloudwatch) (SigV4 pattern; SNS alarm companion)
* AWS docs: [Publish](https://docs.aws.amazon.com/sns/latest/api/API_Publish.html), [ListTopics](https://docs.aws.amazon.com/sns/latest/api/API_ListTopics.html), [HTTPS subscribers](https://docs.aws.amazon.com/sns/latest/dg/sns-http-https-endpoint-as-subscriber.html)


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