From cfed34543a2ca1aa1540c85c23ca46cfc596b748 Mon Sep 17 00:00:00 2001
From: Francis Roberts <111994975+franrob-projects@users.noreply.github.com>
Date: Wed, 24 Sep 2025 14:42:04 +0200
Subject: [PATCH 01/17] What is the difference between 'failed' and 'refused'
message statistics?
---
src/pages/docs/metadata-stats/stats.mdx | 4 ++++
1 file changed, 4 insertions(+)
diff --git a/src/pages/docs/metadata-stats/stats.mdx b/src/pages/docs/metadata-stats/stats.mdx
index b4f4b4d32c..283aac6245 100644
--- a/src/pages/docs/metadata-stats/stats.mdx
+++ b/src/pages/docs/metadata-stats/stats.mdx
@@ -371,6 +371,10 @@ The following metadata is returned for each entry:
All messages metrics include all messages types, such as those sent and received by Ably and clients, messages delivered via integrations and push notifications delivered to devices.
+Failed vs. Refused messages:
+- **Failed** messages are those that did not succeed for reasons other than Ably actively rejecting them, such as external integration target rejections or Ably service issues.
+- **Refused** messages are those that Ably actively chose to reject, typically due to rate limiting, malformed messages, or insufficient client permissions.
+
| Metric | Description |
| --- | --- |
| **messages.all.all.count** | Total number of messages that were successfully received and sent by Ably, summed over all message types and transports. |
From e5f84cd47bb8691a2b471d10c93afeb0dbf9d2e4 Mon Sep 17 00:00:00 2001
From: Francis Roberts <111994975+franrob-projects@users.noreply.github.com>
Date: Wed, 24 Sep 2025 15:10:51 +0200
Subject: [PATCH 02/17] How can I restrict connections or requests by origin or
IP?
---
src/pages/docs/auth/token.mdx | 24 +++++++++++++++++++++---
1 file changed, 21 insertions(+), 3 deletions(-)
diff --git a/src/pages/docs/auth/token.mdx b/src/pages/docs/auth/token.mdx
index e2927166f7..acca8dada3 100644
--- a/src/pages/docs/auth/token.mdx
+++ b/src/pages/docs/auth/token.mdx
@@ -7,11 +7,29 @@ Token authentication uses a trusted device with an [API key](/docs/auth#api-key)
Token authentication is the recommended authentication method to use client-side as it provides more fine-grained access control and limits the risk of credentials being exposed.
+## Access restrictions
+
+### Token-based client validation
+
+Token authentication enables you to validate client characteristics (such as origin, IP address, cookies, or any other client features) in your authentication server before issuing tokens. This provides flexible access control as you can implement any validation logic in your auth server as part of the token issuance process.
+
+### API key restrictions
+
+For cases where token authentication is impractical, Ably can add origin or IP address restrictions directly to API keys. However, this approach has significant limitations:
+
+- Less flexible than token authentication.
+- Manual intervention required to modify restrictions.
+- Enterprise support packages only: contact [Ably support](https://ably.com/support) if interested.
+- Not a security boundary: origin headers can be easily spoofed, especially outside browser contexts.
+- Permissive fallback: requests with no origin header are allowed when origin restrictions are set.
+
+For maximum security and flexibility, token authentication with server-side validation is the recommended approach.
+
Any of the following cause an SDK to use token authentication:
-* An [`authUrl`](/docs/api/realtime-sdk/types#client-options) or [`authCallback`](/docs/api/realtime-sdk/types#client-options) is provided that returns an Ably-compatible token or an Ably [`TokenRequest`](/docs/api/realtime-sdk/types#token-request)
-* [`useTokenAuth`](/docs/api/realtime-sdk/types#client-options) is true
-* A [`token`](/docs/api/realtime-sdk/types#client-options) or [`tokenDetails`](/docs/api/realtime-sdk/types#client-options) property is provided
+* An [`authUrl`](/docs/api/realtime-sdk/types#client-options) or [`authCallback`](/docs/api/realtime-sdk/types#client-options) is provided that returns an Ably-compatible token or an Ably [`TokenRequest`](/docs/api/realtime-sdk/types#token-request).
+* [`useTokenAuth`](/docs/api/realtime-sdk/types#client-options) is true.
+* A [`token`](/docs/api/realtime-sdk/types#client-options) or [`tokenDetails`](/docs/api/realtime-sdk/types#client-options) property is provided.
Providing a literal `token` or `tokenDetails` is typically used for testing: since tokens are short-lived, in production you typically want to use an authentication method that allows the client library to renew the token automatically before the current token expires.
From 5d1b4a9b098521a40dbcc30c7c31353767bc694a Mon Sep 17 00:00:00 2001
From: Francis Roberts <111994975+franrob-projects@users.noreply.github.com>
Date: Thu, 25 Sep 2025 10:27:45 +0200
Subject: [PATCH 03/17] Is it possible to restrict which channels or
permissions an API key has?
---
src/pages/docs/platform/account/app/api.mdx | 10 ++++++++++
1 file changed, 10 insertions(+)
diff --git a/src/pages/docs/platform/account/app/api.mdx b/src/pages/docs/platform/account/app/api.mdx
index 7cdebcf2b5..f7a3df90e0 100644
--- a/src/pages/docs/platform/account/app/api.mdx
+++ b/src/pages/docs/platform/account/app/api.mdx
@@ -8,6 +8,10 @@ redirect_from:
The API keys tab lists all API keys associated with your account and provides information on each key's capabilities and restrictions. You can [create a new API key](#create) and manage an existing one.
+
+
## Create a new API key
The following steps create a new API Key:
@@ -44,6 +48,12 @@ Set resource restrictions to control access to channels and queues, ranging from
| **Only queues** | Access any queue but not channels. |
| **Selected channels and queues** | Specify explicit rules for access. |
+When specifying selected channels and queues, you can provide a comma-separated list of resources. Each resource can match a single channel (e.g., `channel-name`) or multiple channels using wildcards (e.g., `namespace:*`). Queues use the prefix `[queue]` and meta channels use `[meta]`. See [capabilities documentation](/docs/auth/capabilities#wildcards) for detailed wildcard syntax.
+
+
+
### Revocable tokens
[Revocable tokens](/docs/auth/revocation#revocable-tokens) enhance security by allowing shorter token lifetimes and the ability to revoke tokens issued via the API key.
From 6ccfeef3358494b830b82e62919c2a4783c5f0ef Mon Sep 17 00:00:00 2001
From: Francis Roberts <111994975+franrob-projects@users.noreply.github.com>
Date: Thu, 25 Sep 2025 17:43:25 +0200
Subject: [PATCH 04/17] Which TLS Version does the ably-js library use?
---
content/partials/types/_client_options.textile | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/content/partials/types/_client_options.textile b/content/partials/types/_client_options.textile
index 943c723fa2..4b213eaef8 100644
--- a/content/partials/types/_client_options.textile
+++ b/content/partials/types/_client_options.textile
@@ -10,7 +10,7 @@ h4.
<%= partial partial_version('shared/_token_auth_methods') %>
-- tlsTls:tls := _true_ A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. "Find out more about TLS":https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls __Type: @Boolean@__
+- tlsTls:tls := _true_ A boolean value, indicating whether or not a TLS ("SSL") secure connection should be used. An insecure connection cannot be used with Basic authentication as it would lead to a possible compromise of the private API key while in transit. The JavaScript library uses the TLS version supported by the browser environment.In Node.js, the TLS version is determined by the Node.js runtime version. "Find out more about TLS":https://faqs.ably.com/are-messages-sent-to-and-received-from-ably-securely-using-tls __Type: @Boolean@__
- clientIdClientIdclient_id:client_id := A client ID, used for identifying this client when publishing messages or for presence purposes. The @clientId@@client_id@@ClientId@ can be any non-empty string. This option is primarily intended to be used in situations where the library is instantiated with a key; note that a @clientId@@client_id@@ClientId@ may also be implicit in a token used to instantiate the library; an error will be raised if a @clientId@@client_id@ specified here conflicts with the @clientId@@client_id@@ClientId@ implicit in the token. "Find out more about client identities":/docs/auth/identified-clients __Type: @String@__
From d822e6c5f50aeb63db1e6121f2cc9a151e460cdd Mon Sep 17 00:00:00 2001
From: Francis Roberts <111994975+franrob-projects@users.noreply.github.com>
Date: Thu, 25 Sep 2025 18:08:51 +0200
Subject: [PATCH 05/17] Do you support multiplexing and channel groups?
---
src/pages/docs/channels/index.mdx | 12 ++++++++++++
src/pages/docs/connect/index.mdx | 14 +++++++++++++-
2 files changed, 25 insertions(+), 1 deletion(-)
diff --git a/src/pages/docs/channels/index.mdx b/src/pages/docs/channels/index.mdx
index 3bcdd9d03f..ee1274ffa6 100644
--- a/src/pages/docs/channels/index.mdx
+++ b/src/pages/docs/channels/index.mdx
@@ -218,3 +218,15 @@ Channel [history](/docs/storage-history/history) enables clients to retrieve mes
## Presence
The [presence](/docs/presence-occupancy/presence) feature enables clients to be aware of other clients that are 'present' on the channel. Client status is updated as they enter or leave the presence set. Clients can also provide an optional payload describing their status or attributes, and trigger an update event at any time.
+
+## Channel groups
+
+Ably does not support channel groups, a concept used by some other providers where channels are placed into groups to work around limitations in dynamically subscribing or unsubscribing from channels.
+
+**Why Ably doesn't need channel groups:**
+
+* With Ably client libraries, you can add or remove subscriptions to channels dynamically at any tie.
+* All channels operate over a single efficient connection.
+* Channel namespaces already provide grouping functionality for configuration purposes.
+
+Instead of channel groups, simply subscribe to the specific channels your client needs access to. The efficient multiplexing ensures optimal performance regardless of the number of channels.
diff --git a/src/pages/docs/connect/index.mdx b/src/pages/docs/connect/index.mdx
index f79cf245c4..fde8e087a3 100644
--- a/src/pages/docs/connect/index.mdx
+++ b/src/pages/docs/connect/index.mdx
@@ -8,7 +8,19 @@ redirect_from:
- /docs/realtime/versions/v0.8/connection
---
-Clients establish and maintain a connection to the Ably service using the most efficient transport available, typically [WebSockets](https://ably.com/topic/websockets). Ably SDKs operate and multiplex all [channel](/docs/channels) traffic over that connection. This maximizes throughput, minimizes bandwidth consumption, and reduces power usage. Once connected, clients can monitor and manage their [connection state](/docs/connect/states).
+Clients establish and maintain a connection to the Ably service using the most efficient transport available, typically [WebSockets](https://ably.com/topic/websockets).
+
+## Connection multiplexing
+
+Ably SDKs operate and multiplex all [channel](/docs/channels) traffic over a single connection. This means you can publish and subscribe to messages on any number of channels simultaneously using just one transport connection. This approach:
+
+* Maximizes throughput by efficiently utilizing the available connection.
+* Minimizes bandwidth consumption by avoiding multiple connection overhead.
+* Reduces power usage by maintaining fewer active connections.
+
+All Ably client libraries support multiplexing by default when using the realtime interface. You can dynamically subscribe and unsubscribe from channels at any time without needing to establish new connections.
+
+Once connected, clients can monitor and manage their [connection state](/docs/connect/states).