User Guide

A walkthrough for getting from "I have an invite" to "I'm sending and receiving messages." Plain-English version. If you want the architecture, see Docs.

What this is

Akamai Cloud Queues + Notifications gives you two messaging primitives over one tenant-isolated control plane:

Queues — point-to-point work queues. One producer, one consumer per message. Messages persist until acknowledged.
Topics + Subscriptions — pub/sub fan-out. Publish once, every subscription receives a copy. Each subscription can deliver via webhook, queue, or live SSE stream.

The system runs as a single logical service across 27 Akamai regions. You talk to one hostname (mq.connected-cloud.io) and the request lands in the closest region.

This is a research POC. You'll see references to NATS JetStream under the hood — that's the engine, not the contract. The contract is the REST API.

Get access

From the front page, click request invite and fill in your name, email, and what you want to try. An admin reviews this — usually fast for internal Akamai folks.
When approved, you receive a claim link of the form https://mq.connected-cloud.io/claim/<invite-token>. Open it.
The claim page mints a tenant bearer (a long hex string) and shows it once. Copy it immediately — you can't recover it later from the UI. (Admins can re-mint new tokens, but the original is shown once.)

The bearer is your access. Anyone with it can act as your tenant. Treat it like a password.

Save your bearer

Open Dashboard. The first card is "Your tenant bearer" — paste your token and click Save. It's stored in the browser's localStorage; nothing leaves your laptop except as the Authorization: Bearer … header on subsequent requests.

To switch tenants, paste a different bearer over the existing one. Clear wipes it from localStorage.

Send and receive your first message (queues)

Queues are the simplest pattern: one producer drops a message, one consumer pulls and acknowledges it. Try it in the Playground:

In the Playground, click + Queue. Name it orders. Hit Create.
In the Send panel, queue = orders, body = {"order_id":"42"}. Hit Send. You'll see the message ID echo back.
In the Receive panel, queue = orders, wait = 5 seconds. Hit Receive. The message comes back along with an ack_token.
Paste the ack_token into the Ack panel and hit Ack. The message is gone from the queue.

If you don't ack within the visibility window, the message becomes available again and another consumer (or the same one) will see it on the next Receive. That's the at-least-once guarantee.

Subscribe to a live stream (topics + SSE)

Topics let multiple subscribers each receive every message. Live SSE delivery means the browser holds an open connection and frames stream in as they're published.

In the Playground, click + Topic. Name it events. Hit Create.
Click + Subscription. Topic = events, filter = leave blank (catches everything), delivery = sse. Hit Create. A subscription ID appears.
On that subscription row, click Live Subscribe. The output panel below should immediately show a : connected frame.
In the Publish panel, topic = events, subject = created, body = anything. Hit Publish. Within a fraction of a second, the message appears in your Live Subscribe output.

Heartbeat lines (: keepalive) appear every 15 seconds — those are normal and tell you the connection is still healthy.

SSE is one of two delivery types per subscription today. Pick the one that matches your consumer shape:

sse — browser or curl holds a long-lived HTTP connection; messages stream in. No durability if the client disconnects.
http_push (webhook) — service POSTs each message to a URL you specify. Retries with backoff if the target 5xx's; persistent failures go to a per-subscription DLQ.

A third delivery type — drain a subscription into a tenant-owned queue for durable fan-out with backpressure — is planned but not yet implemented. Today, if you need that pattern, point a webhook at POST /v1/queues/<name>/send.

Webhook delivery

To have the service POST each message to your endpoint:

Stand up an HTTP endpoint that accepts JSON POST. A quick option for testing: webhook.site.
Create a subscription with delivery = webhook and target = your URL.
Publish to the topic. The service POSTs each message body to your endpoint with a few X-Mq-* headers identifying the topic/subscription/message ID.
Return 2xx to ack. Return 5xx and the message is retried with exponential backoff; persistent failures eventually move the message to a per-subscription dead-letter queue you can inspect.

Call the API directly

The UI is a convenience — the real interface is HTTPS REST. Anything you can do in the Playground, you can do with curl:

BEARER="paste-your-bearer-here"
BASE="https://mq.connected-cloud.io/v1"

# create a queue
curl -X POST -H "Authorization: Bearer $BEARER" \
  -H "Content-Type: application/json" \
  $BASE/queues -d '{"name":"orders"}'

# send a message
curl -X POST -H "Authorization: Bearer $BEARER" \
  $BASE/queues/orders/send -d '{"order_id":"42"}'

# receive (long-poll up to 30s)
curl -H "Authorization: Bearer $BEARER" \
  "$BASE/queues/orders/receive?wait=30"

# ack (use the ack_token from the receive response)
curl -X POST -H "Authorization: Bearer $BEARER" \
  $BASE/queues/orders/ack/$ACK_TOKEN

For live SSE from any browser or third-party page (the API allows cross-origin):

const es = new EventSource(
  "https://mq.connected-cloud.io/v1/subscriptions/" + subId +
  "/stream?bearer=" + encodeURIComponent(bearer)
);
es.onmessage = (e) => console.log(e.data);

EventSource can't set headers, so the bearer travels in a query parameter as a fallback. The Authorization header is still preferred for any non-SSE request.

The full OpenAPI spec is at /openapi.yaml, and the API explorer lets you call every endpoint from the browser with one click.

Concepts cheat sheet

Term	What it is	Lifetime
`tenant`	Your isolated namespace. Every resource you create is scoped to it. Other tenants can't see your queues, topics, subscriptions, or messages.	Until an admin suspends or deletes it.
`bearer`	The token that proves you're acting as a tenant. Goes in the `Authorization` header (or `?bearer=` for SSE).	Until revoked or rotated.
`queue`	A named work queue. Producers send, consumers pull and ack. At-least-once delivery.	Until deleted.
`topic`	A named pub/sub channel. Publishes fan out to all attached subscriptions.	Until deleted.
`subscription`	A named delivery endpoint attached to a topic. Each subscription independently receives every message matching its filter.	Until deleted.
`ack_token`	A one-shot handle returned by Receive. POST it back to `/ack` to acknowledge, `/nak` to redeliver immediately, or `/extend` to request more processing time.	Until the visibility window expires.

Where to go next

Playground — every operation in this guide, click-driven.
API explorer — Swagger UI over the OpenAPI spec; "Try it" with your bearer.
Docs — architecture, wiring, and tradeoffs against SQS+SNS / Pub/Sub / Service Bus.
Verify — automated correctness check against your tenant.
Loadtest — short throughput probe so you can see the in-region performance.
Topology — which region your last request landed in, and which regions are healthy.