[FTF-468] Several docs changes to highlight token auth over API key auth, as well as more info on using JWTs #3085

umair-ably · 2026-01-07T17:37:09Z

Description

Restructures auth documentation to recommend token authentication (specifically Ably JWT) as the default for client-side applications
Adds new dedicated authentication pages for Chat and Spaces products
Expands token auth documentation with a comparison table of token mechanisms and clearer guidance on choosing between Ably JWT, TokenRequest, and Embedded JWT
Updates auth landing page with a quick reference table and starter code example
Streamlines capabilities and identified-clients pages for clarity

Motivations/Objectives:

JWT Token Auth becomes the obvious and clear auth pattern for production code.
Customer's are easily able to navigate the docs site to find the appropriate auth info e.g. product specific auth guidance is nested in the product section. Auth is moved under platform. (Will be added in a later PR)

Checklist

Commits have been rebased.
Linting has been run against the changed file(s).
The PR adheres to the writing style guide and contribution guide.

coderabbitai · 2026-01-07T17:37:16Z

Important

Review skipped

Auto reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

paddybyers

I've commented on much of this but stopped around half way through. I think it needs significant revision to make JWT the primary recommended route. The narrative and examples all need updating to reflect this.

A lot of this is slop - it's been AI-generated and not critically reviewed.

paddybyers · 2026-01-07T18:16:20Z

src/pages/docs/auth/quick-reference.mdx

+```javascript
+// ALWAYS use token authentication in browsers
+const realtime = new Ably.Realtime({
+  authUrl: '/api/ably-token',


Why are we suggesting authURL instead of callback here? Does it not need at least some comment?

paddybyers · 2026-01-07T18:17:37Z

src/pages/docs/auth/quick-reference.mdx

+
+## Server auth endpoint template
+
+Your server needs an endpoint that creates tokens. Here's a minimal example:


Why is this using native tokens, instead of generating a JWT?

paddybyers · 2026-01-07T18:22:03Z

src/pages/docs/auth/quick-reference.mdx

+```
+</Code>
+
+## Security comparison


I'm not convinced this section adds anything. It feels like slop.

really a duplciate of https://ably-docs-authchanges-py2loc0j.herokuapp.com/docs/auth#selecting-auth. I do thinkg repetition is good at times, but why here?

paddybyers · 2026-01-07T18:29:31Z

src/pages/docs/auth/quick-reference.mdx

+- [Token authentication reference](/docs/auth/token) - Full token auth documentation
+- [Capabilities](/docs/auth/capabilities) - Fine-grained permission control
+
+## Troubleshooting


These are not the only things that could go wrong, or even the most likely things that could go wrong.

Error 40103: Token expired

Not according to https://github.com/ably/ably-common/blob/main/protocol/errors.json#L40

If we're going to retain this section we should also refer to:
40160: incorrect capabilities
80019: error in auth callback/url
40171: no means to renew token

Perhaps we should defer adding this section until we've got the more thorough error code documentation landed?

Why do we need troubleshooting at all? We have error codes and paths. Do we think people are going to read this and pre-empty troubles?

paddybyers · 2026-01-07T18:32:32Z

src/pages/docs/auth/token.mdx

+
+### TokenRequest <a id="choosing-tokenrequest"/>
+
+**Best for:** Standard web and mobile applications using Ably SDKs.


I don't agree with this. We recommend JWT in all circumstances that they can be used. There are only two situations where you would use native tokens:

where the capabilities list is so large that a literal token is unworkable;

where the capabilities or clientId are sensitive in some way, and there is a desired to keep them confidential, even if inspecting the token.

Of these, I'm not sure we should even mention the second one because it's such an unusual case.

paddybyers · 2026-01-07T18:36:18Z

src/pages/docs/chat/rooms/occupancy.mdx

 Occupancy generates messages on any client entering/leaving a room, and so increases the number of billable messages sent in a room - as such, it is disabled by default and needs to be [enabled](/docs/chat/rooms#create) when creating or retrieving a room.
 </Aside>

+<Aside data-type='note'>


This is irrelevant. I suggest removing it.

paddybyers · 2026-01-07T18:37:17Z

src/pages/docs/chat/rooms/presence.mdx

 The presence feature of a chat room enables online users to advertise to others that they are online. Use this feature to build online status indicators to display who is online in a chat room. Users can also share additional information such as avatar URLs or custom statuses.

+<Aside data-type='note'>
+**Authentication required:** Presence requires an authenticated client with a `clientId`. Clients without a `clientId` cannot enter the presence set. Use [token authentication](/docs/auth/token) with server-assigned client IDs for production applications. See the [Chat setup guide](/docs/chat/setup#authentication) for examples.


This should refer to identified clients.

paddybyers · 2026-01-07T18:38:07Z

src/pages/docs/chat/rooms/reactions.mdx


 Room reactions are ephemeral and not stored or aggregated by Ably. The intention being that they show the overall sentiment of a room at a point in time.

+<Aside data-type='note'>


This is incorrect advice. It should state instead that a client needs to be identified in order to use certain reaction types. It does not imply the use of token auth.

paddybyers · 2026-01-07T18:39:07Z

src/pages/docs/chat/rooms/typing.mdx

 Typing indicators enable you to display which users are currently writing a message in a room. This feature can be used to display a message such as *Sandi is typing...*, or when a certain threshold is reached you could instead display *Multiple people are typing...* or *12 people are typing...*. Typing events are emitted whenever a user starts or stops typing.

+<Aside data-type='note'>
+**Authentication required:** Typing indicators display the `clientId` of users who are typing. Use [token authentication](/docs/auth/token) to ensure these identities are trustworthy. See the [Chat setup guide](/docs/chat/setup#authentication) for examples.


I don't understand why this comment is here. Doesn't the chat SDK ensure that a client is always identified?

Yes it does, this is needless information as they cannot connect without a clientId

paddybyers · 2026-01-07T18:39:49Z

src/pages/docs/chat/authentication.mdx

+
+Your server needs an endpoint that:
+1. Verifies the user is authenticated (check session, JWT, etc.)
+2. Creates an Ably TokenRequest with the user's identity


Again, we should be recommending JWT auth.

mattheworiordan

Thanks for submitting. Good to see you take a stab at dealing with the LLM auth issues, but I think this PR needs a lot more human review by yourself before it's sent for others to review. Lots of obvious problems as it appears to have been pumped out directly from an LLM, which is great to move quickly, but thiks is our docs, and is representative of whether we care to customers.

mattheworiordan · 2026-01-07T20:26:31Z

src/pages/docs/auth/jwt-integration.mdx

+
+## Approach 1: Separate Ably JWT <a id="separate-jwt"/>
+
+Your existing auth flow validates the user, then you create an Ably JWT using any JWT library. No Ably SDK is required on your server.


I am not sure this is what we'd recommend, always sending both tokens instead of just the one you need? Why would a single endpoint be used for Ably and app auth, when both only need one of the two JWTs?

mattheworiordan · 2026-01-07T20:29:01Z

src/pages/docs/auth/jwt-integration.mdx

+  authCallback: async (tokenParams, callback) => {
+    // On token refresh, fetch new Ably JWT
+    try {
+      const response = await fetch('/auth/ably-token', {


This URL doesn't match the server example you have above

mattheworiordan · 2026-01-07T20:30:22Z

src/pages/docs/auth/jwt-integration.mdx

+    // On token refresh, fetch new Ably JWT
+    try {
+      const response = await fetch('/auth/ably-token', {
+        headers: { 'Authorization': `Bearer ${appToken}` },


This approach is broken in that a new app token cannot be generated as it's cached at the time of login, instead of obtaining one at the time it's needed

mattheworiordan · 2026-01-07T20:31:48Z

src/pages/docs/platform/auth/jwt-integration.mdx

+      'x-ably-token': ablyToken.token,
+    },
+    process.env.APP_JWT_SECRET,
+    { expiresIn: '1h' } // Must not exceed Ably token expiry


If that's teh case, why are you not specifying a TTL when issuing the token?

mattheworiordan · 2026-01-07T20:36:22Z

src/pages/docs/auth/jwt-integration.mdx

+```
+</Code>
+
+## Integrating with AWS Cognito <a id="cognito"/>


I am not sure we should be just listing out integrations with random providers like this. It doesn't really flow, at the start we're talking about issuing JWTs ,then we are showing random integrations where with this one we're just showing how to issue a token with Lambda, and then we move onto token renewal. It doesn' feel well thought through, why this order?

mattheworiordan · 2026-01-07T21:08:25Z

src/pages/docs/spaces/authentication.mdx

+
+If your `authUrl` endpoint is slow or unreliable, tokens may expire before refresh completes. Ensure your auth endpoint responds quickly (under 5 seconds) and is highly available.
+
+## Next steps


Why have you introduced Next Steps? We've not used this in the docs.

mattheworiordan · 2026-01-07T21:08:40Z

src/pages/docs/auth/jwt-integration.mdx

+
+The Ably SDK automatically calls your `authCallback` before the current token expires, ensuring seamless token rotation.
+
+## Next steps


Why have you introduced Next Steps? We've not used this in the docs.

mattheworiordan · 2026-01-07T21:09:00Z

src/pages/docs/chat/authentication.mdx

+
+If your `authUrl` endpoint is slow or unreliable, tokens may expire before refresh completes. Ensure your auth endpoint responds quickly (under 5 seconds) and is highly available.
+
+## Next steps


Why have you introduced Next Steps? We've not used this in the docs.

mattheworiordan · 2026-01-07T21:09:34Z

src/pages/docs/chat/rooms/typing.mdx

 Typing indicators enable you to display which users are currently writing a message in a room. This feature can be used to display a message such as *Sandi is typing...*, or when a certain threshold is reached you could instead display *Multiple people are typing...* or *12 people are typing...*. Typing events are emitted whenever a user starts or stops typing.

+<Aside data-type='note'>
+**Authentication required:** Typing indicators display the `clientId` of users who are typing. Use [token authentication](/docs/auth/token) to ensure these identities are trustworthy. See the [Chat setup guide](/docs/chat/setup#authentication) for examples.


Yes it does, this is needless information as they cannot connect without a clientId

mattheworiordan · 2026-01-07T21:14:57Z

src/pages/docs/spaces/avatar.mdx

 Subscribe to the `space.members` namespace in order to keep your avatar stack updated in realtime.

+<Aside data-type='note'>
+**Authentication required:** This feature uses the client's `clientId` for identification. Use [token authentication](/docs/auth/token) with server-assigned client IDs to prevent identity spoofing. See the [Spaces setup guide](/docs/spaces/setup#authenticate) for examples.


This is not necessary. If this is needed, the problem of which auth mechanism t use is surely solved?

umair-ably · 2026-01-08T12:42:02Z

Thanks both @mattheworiordan @paddybyers

I should've made it clear I had not yet reviewed the LLM output, so this at the very least should've been a draft only! I mostly put it up to get a gauge on the kind of content we think we were missing and the placement of it.

However, your comments have massively helped me in understanding the scope of what needs changing in our auth docs, as well as highlighting my limited understanding of exactly what we're trying to tell and recommend to our customers. I've got a session with Mark and Paddy shortly to understand exactly what our position is re: Auth with Ably, what we're trying to tell our customers, and some historical context of how auth has evolved to the point we seem to have deviations in our docs.

I'm trying to solely use LLMs for this, so again, some of these changes are likely subpar as I get a better understanding of the problem later today. For the time-being, I've gone back and forth with Claude to "resolve" (or at least have a stab at resolving) your current comments.

I would ignore this for now until I've had a chance to capture and implement the findings from our meeting later today - this is purely to move the needle and help my own understanding from what you've presented in the comments so far.

Comments on auth/quick-reference.mdx (12 comments)

Comment	Resolved
paddybyers: Why authURL instead of callback?	✅ Added "authUrl vs authCallback" section explaining both
paddybyers: Why native tokens instead of JWT?	✅ Server examples now generate JWTs directly
paddybyers: Security comparison feels like slop	✅ Section removed
paddybyers: Troubleshooting section issues	✅ Section removed
mattheworiordan: Decision matrix unclear	✅ Removed, simplified to code examples
mattheworiordan: Duplicating overview page	✅ Simplified to quick reference focus
mattheworiordan: Server using Realtime not REST	✅ Now uses Ably.Rest server-side
mattheworiordan: getUserIdFromRequest odd name	✅ Now uses req.user?.id (auth middleware pattern)
All troubleshooting/product links comments	✅ These sections removed

Comments on auth/token.mdx (8 comments)

Comment	Resolved
paddybyers: JWT should be primary, not TokenRequest	✅ "Ably JWT is recommended for most use cases"
paddybyers: Serverless in wrong section	✅ Moved to JWT section (stateless)
paddybyers: TokenRequest advantages become disadvantages	✅ Restructured with proper trade-offs
paddybyers: Too much repetition	✅ Cleaned up, table simplified
mattheworiordan: Table values questionable	✅ Table revised with clearer yes/no values

Comments on auth/jwt-integration.mdx (8 comments)

Comment	Resolved
mattheworiordan: Sending both tokens wrong	✅ File simplified, single endpoint approach
mattheworiordan: URL mismatch	✅ Consistent /api/ably-jwt throughout
mattheworiordan: Token caching broken	✅ Now uses proper authCallback pattern
mattheworiordan: No TTL specified	✅ expiresIn: '1h' now included
mattheworiordan: Random provider list	✅ Provider integrations removed
mattheworiordan: getCurrentAppToken confusing	✅ Removed
mattheworiordan: "Next Steps" not used in docs	✅ Section removed

Comments on chat/authentication.mdx (12 comments)

Comment	Resolved
paddybyers: Should recommend JWT	✅ Creates JWTs directly
mattheworiordan: authMethod/authHeaders inconsistent	✅ Examples now consistent using authCallback
mattheworiordan: Send/receive should be separate	✅ Capability table has separate rows
mattheworiordan: Missing annotations/mutations	✅ Table includes annotation-publish, etc.
mattheworiordan: Wrong namespace format	✅ Correct my-room::$chat format
mattheworiordan: "Next Steps" section	✅ Removed

Comments on Chat Room Features (6 comments)

File	Comment	Resolved
rooms/occupancy.mdx	Auth callout irrelevant	✅ Removed
rooms/presence.mdx	Should link to identified-clients	✅ Links to /docs/auth/identified-clients
rooms/reactions.mdx	Should mention identified clients	✅ Now references identified clients
rooms/typing.mdx	Unnecessary auth note	✅ Removed

Comments on chat/setup.mdx (1 comment)

Comment	Resolved
Empty code blocks	✅ All code blocks now have content

Comments on spaces/authentication.mdx & spaces/avatar.mdx (2 comments)

Comment	Resolved
"Next Steps" not used in docs	✅ Removed
Auth note unnecessary in avatar.mdx	✅ Removed

Key Changes Made

JWT is now the recommended primary auth mechanism throughout all docs
Removed unnecessary sections: Security comparison, Troubleshooting, Next Steps, Provider integrations
Server examples use REST client instead of Realtime
Consistent authCallback examples across all SDKs
Accurate capability tables with separate permissions
Proper identified client references in Chat features
jwt-integration.mdx dramatically simplified from ~430 lines to ~89 lines
Fixed empty code blocks in setup.mdx

…ll as more info on using JWTs

paddybyers

This is really hard to review because it's dominated by changes to the path for the auth docs. Please at least make all of those changes in a separate commit (but I don't see why it's not a separate PR). Then the other material changes can be reviewed.

umair-ably · 2026-01-14T10:09:01Z

This is really hard to review because it's dominated by changes to the path for the auth docs. Please at least make all of those changes in a separate commit (but I don't see why it's not a separate PR). Then the other material changes can be reviewed.

that's fair - the change was from our meeting in which we wanted auth docs under platform with shorter product auth guides in their respective sections. This then meant leaving the path as docs/auth or changing it to docs/platform/auth... I went with the latter purely because it matches the nav stack. I'll change it for the sake of this PR

umair-ably · 2026-01-14T11:03:09Z

@paddybyers I also unified the messaging we had when pointing people to the token auth docs... I'll revert this and do that as a separate PR.. just a moment

umair-ably · 2026-01-14T12:11:13Z

@mattheworiordan @paddybyers

Previous comments should be addressed.

There was a fair few more changes that I'll instead add in a subsequent PR (adding asides to current basic auth code examples which highlight using JWT token in prod, and redirects to ensure links point to the new auth docs location under platform)

umair-ably · 2026-01-14T16:25:29Z

src/pages/docs/protocols/mqtt.mdx


+### JWT Authentication <a id="jwt-auth"/>
+
+<Aside data-type='note'>


remove this... duplicate

…ll as more info on using JWTs

umair-ably · 2026-01-15T09:05:17Z

@paddybyers

Undone all nav changes for this PR... All auth docs changes are now isolated to their original location (under pubsub) and new product specific auth pages e.g. Chat and Spaces.

Upcoming PR(s) will reintroduce:

Moving auth docs from pubsub to platform (and redirects where needed)
MQTT and SSE docs changes
Unifying and adding messaging around using JWT token auth where we have basic auth code examples

cc: @m-hulbert

paddybyers

Please see the comments. I think this still needs some work.

Discussions relating to auth have lots of scope for ambiguity so please use precise language. Every word has one meaning, and every meaning has one word.

@m-hulbert I'll defer to you on whether or not the restructure makes sense wrt the nav.

Someone from the Chat team needs to review the chat parts - having the ::$chat directive in the capability expression I'm sure is wrong (@splindsay-92 )

paddybyers · 2026-01-26T07:54:03Z

src/pages/docs/auth/capabilities.mdx

-Capabilities can be set when creating a token or token request, as shown in the following example:
+#### Using JWT (recommended) <a id="jwt-capabilities"/>
+
+Set capabilities in a JWT using the `x-ably-capability` claim. No Ably SDK is required—any JWT library will work:


Suggested change

Set capabilities in a JWT using the `x-ably-capability` claim. No Ably SDK is required—any JWT library will work:

Set capabilities in a JWT using the `x-ably-capability` claim. No Ably SDK is required - any JWT library will work:

Please no em-dashes

Maybe worth just adding
This example uses jsonwebtoken
?

paddybyers · 2026-01-26T07:58:50Z

src/pages/docs/auth/capabilities.mdx

-capability := map[string][]string{
-  "*": {"*"},
-}
+If JWT is not suitable, use the Ably SDK to create a TokenRequest with capabilities:


This says nothing about why JWT might not be suitable

paddybyers · 2026-01-26T08:03:34Z

src/pages/docs/auth/capabilities.mdx

+
 ### Token capability determination <a id="capability-determination"/>

 The capabilities for tokens are determined based on those of the issuing API key and those requested by the token.


I think this needs to be more explicit. The capabilities of the resulting token are the intersection of the request capabilities, and those of the issuing API key. (This is also true for JWT.)

The requestToken() request will fail if the intersection is empty - ie the token would have no rights.

This should also mention the gotcha: this intersection behaviour means that a call to requestToken() will succeed, but can fail to provide a token with all of the requested capabilities. If the capabilities of the issuing key are not known by the client, then a successful response to requestToken() should be followed by a check that all of the requested capabilities are present.

paddybyers · 2026-01-26T08:05:35Z

src/pages/docs/auth/capabilities.mdx

 ## Custom restrictions on channels <a id="custom-restrictions"/>

+<Aside data-type='important'>
+**JWT-only feature:** Channel-scoped user claims are only available when using [Ably JWT authentication](/docs/auth/token#choosing-jwt). They are not available with TokenRequest authentication. See [JWT-only features](/docs/auth/token#jwt-only-features) for a complete list of capabilities exclusive to JWT authentication.


@m-hulbert Are we happy that "TokenRequest authentication" is the appropriate name in these docs for the native token mechanism?

I think the high-level mechanism should be 'Ably Tokens' personally.

paddybyers · 2026-01-26T08:06:46Z

src/pages/docs/auth/capabilities.mdx

+
 It is possible for JWTs to contain authenticated claims for users that can be used to allow or disallow certain interactions in your channels.

 Messages can be annotated with trusted metadata copied from the client's authentication token by Ably servers. Clients are unable to directly publish messages with user claim metadata, and claims contained within the authentication token are signed to prevent tampering. Claims can be scoped to individual channels or to namespaces of [channels](/docs/channels). The most specific user claim will be added to the message as part of the `extras` object. Note that this does not apply to presence or metadata messages.


Note that this does not apply to presence

I thought we support that now - pls check

paddybyers · 2026-01-26T08:30:52Z

src/pages/docs/auth/token.mdx

+* Ably [TokenRequest](#token-request) is created by your servers and passed to clients.
+* An [Ably Token](#ably-token) is issued by your servers and passed to clients.
+
+Note that the machine on which you are running your auth server should have an accurate clock, as tokens and `TokenRequest` contain a timestamp. You can use an [NTP daemon](https://en.wikipedia.org/wiki/Ntpd), or if you are not able to control your server's clock, you can wish to use the `queryTime` [auth option](/docs/api/rest-sdk/types#auth-options).


Suggested change

Note that the machine on which you are running your auth server should have an accurate clock, as tokens and `TokenRequest` contain a timestamp. You can use an [NTP daemon](https://en.wikipedia.org/wiki/Ntpd), or if you are not able to control your server's clock, you can wish to use the `queryTime` [auth option](/docs/api/rest-sdk/types#auth-options).

Note that the machine on which you are running your auth server should have an accurate clock, as tokens and `TokenRequest` contain a timestamp and have limited validity. You can use an [NTP daemon](https://en.wikipedia.org/wiki/Ntpd), or if you are not able to control your server's clock, you can wish to use the `queryTime` [auth option](/docs/api/rest-sdk/types#auth-options).

paddybyers · 2026-01-26T08:35:06Z

src/pages/docs/auth/token.mdx

+
+### Multi-tenant SaaS with user roles <a id="scenario-multitenant"/>
+
+**Recommendation: Ably JWT with channel claims**


Please do not use bold like this. Use a heading if appropriate, or just plain text.

I don't understand why these channel claims are relevant to this use-case - can you explain?

paddybyers · 2026-01-26T08:35:29Z

src/pages/docs/auth/token.mdx

+```
+</Code>
+
+Other clients can read these trusted claims from presence or message metadata.


Why is this relevant to a multi-tenanted system?

paddybyers · 2026-01-26T08:36:46Z

src/pages/docs/chat/authentication.mdx

+  {
+    'x-ably-capability': JSON.stringify({
+      // Only allow access to a specific room
+      'your-room::$chat': ['publish', 'subscribe', 'presence', 'history'],


I think this is incorrect. A resource specifier in a capability expression will match on the channel name without the directive part.

paddybyers · 2026-01-26T08:38:08Z

src/pages/docs/chat/setup.mdx

-
 <Aside data-type='important'>
-The examples use basic authentication to demonstrate features for convenience. In your own applications, basic authentication should never be used on the client-side as it exposes your Ably API key. Instead, use token authentication.
+**Security requirement:** Client-side applications must use [JWT token authentication](/docs/auth/token#choosing-jwt). Never expose your API key in client-side code.


Please don't use bold like this.
Please don't use the word "security" like this. There are words that mean the specific thing you're trying to say.

m-hulbert

Thanks Umair.

I can see this starting to take shape, but I think we need to make some larger changes, as we've made a long page even longer (and arguably more complicated) - with the actual code to get up and running 40% down the page.

I think we should split up the token authentication page into 3/4 separate ones;

Overview
- Covers anything that is true for all forms of token authentication.
- I think this needs to mention that authentication is handled by the Pub/Sub SDK and what that means for other products.
JWTs
- Just info on JWTs with a mention at the top that it's recommended. authCallback used in examples in all languages - authUrl can be further down with associated examples, but most people will use the callback.
- Note on when you'd use Ably native Tokens instead in the intro.
Ably Tokens
- Note at the top that JWTs are recommended and you'd only use Ably Tokens in these circumstances.
- All info on Ably Token mechanisms. (I'd also include a token embedded in a JWT on this page personally, but defer to @paddy on the popularity of that).
Token revocation
- Makes sense to nest this if we create this section.

We've also added a lot of "JWT is recommended" in places, but I feel we should just stick to the points around length of the JWT and its publicly visible claims. If we create a token authentication overview, I feel all we need to state is 'use JWT authentication unless...". And then reiterate that at the top of the JWT and Ably Token pages.

Can we also ensure we have full coverage for all languages whilst we're updating this please?

m-hulbert · 2026-01-29T09:35:40Z

src/pages/docs/auth/token.mdx

+
+## Token mechanism comparison <a id="comparison"/>
+
+| Feature | Ably JWT (Recommended) | Embedded JWT | TokenRequest |


I feel this is sort of trying to justify the use of JWTs which I'm not sure is strictly necessary if we position it as the recommended approach. Would be curious on other opinions though.

m-hulbert · 2026-01-29T09:38:36Z

src/pages/docs/auth/token.mdx

+
+| Feature | Ably JWT (Recommended) | Embedded JWT | TokenRequest |
+|---------|:----------------------:|:------------:|:------------:|
+| **Server SDK required** | No | Yes | Yes |


I'm not sure why some of these rows are bold and others aren't.

m-hulbert · 2026-01-29T09:55:00Z

src/pages/docs/chat/authentication.mdx

+meta_description: "Configure authentication for Chat applications with the required capabilities."
+---
+
+This page covers Chat-specific capabilities and room scoping. For client setup and server implementation, see [SDK setup](/docs/chat/setup).


We don't tend to write 'this page covers'. This should dive straight into what Chat authentication is, and that it's handled by the Pub/Sub SDK.

We also spoke about this replacing the SDK setup page, so I don't think we should be updating that page, and adding this one as it's just splitting the info between two pages. Especially when this page (which should be the go-to for auth) is only showing JS examples.

m-hulbert · 2026-01-29T09:56:54Z

src/pages/docs/chat/authentication.mdx

+
+Capabilities are permissions that control what operations a client can perform. When you create a token for a Chat user, you specify which capabilities they have. Each Chat feature requires specific capabilities:
+
+| Feature | Required Capabilities |


We seem to have taken the table from the existing setup page and added more rows unnecessarily.

m-hulbert · 2026-01-29T09:57:25Z

src/pages/docs/chat/authentication.mdx

+// Server-side JWT with room-scoped capabilities
+import jwt from 'jsonwebtoken';
+
+const [keyName, keySecret] = process.env.ABLY_API_KEY.split(':');


We should be using the variable for a demo key in all code examples please.

m-hulbert · 2026-01-29T10:02:21Z

src/pages/docs/chat/authentication.mdx

+
+- **Token lifecycle**: Tokens expire and the SDK automatically refreshes them via your `authCallback` - see [Token authentication](/docs/auth/token)
+- **Revoke access**: You can instantly revoke tokens for compromised or banned users - see [Token revocation](/docs/auth/revocation)
+- **Dynamic permissions**: Users can get new capabilities by re-authenticating (e.g., when a moderator grants permissions) - see [Capabilities](/docs/auth/capabilities)


Can we ensure links are included inline rather than having 'see X' or 'read more' everywhere please.

m-hulbert · 2026-01-29T10:02:59Z

src/pages/docs/spaces/authentication.mdx

@@ -0,0 +1,115 @@
+---
+title: Spaces authentication


I think most of my comments from chat are relevant here.

m-hulbert · 2026-01-29T10:03:26Z

src/pages/docs/spaces/authentication.mdx

+
+## Space-scoped capabilities
+
+You can restrict tokens to specific spaces. Spaces uses multiple channels per space:


This is the first point we're mentioning that space is equivalent to a channel. Before now you have no idea or concept of their relationship.

m-hulbert · 2026-01-29T10:05:31Z

src/pages/docs/spaces/authentication.mdx

+## Space-scoped capabilities
+
+You can restrict tokens to specific spaces. Spaces uses multiple channels per space:
+- The main space channel (`your-space`) handles presence and member locations


IIRC the channel name is your-space::$space. I'm not 100% if spaces directives are handled in capabilities automatically the same way that chat ones are though.

m-hulbert · 2026-01-29T10:06:31Z

src/pages/docs/spaces/authentication.mdx

+
+Use `authCallback` to fetch JWTs from your auth server:
+
+<Code>


Also needs React.

umair-ably requested review from AndyTWF and m-hulbert January 7, 2026 17:37

umair-ably added the review-app Create a Heroku review app label Jan 7, 2026

ably-ci temporarily deployed to ably-docs-authchanges-py2loc0j January 7, 2026 17:48 Inactive

paddybyers requested changes Jan 7, 2026

View reviewed changes

mattheworiordan requested changes Jan 7, 2026

View reviewed changes

umair-ably force-pushed the authChanges branch from 8d4649e to 4e56d1a Compare January 8, 2026 12:31

ably-ci temporarily deployed to ably-docs-authchanges-py2loc0j January 8, 2026 12:31 Inactive

Several docs changes to highlight token auth over API key auth, as we…

0d61283

…ll as more info on using JWTs

umair-ably force-pushed the authChanges branch from 4e56d1a to 0d61283 Compare January 13, 2026 08:13

ably-ci temporarily deployed to ably-docs-authchanges-py2loc0j January 13, 2026 08:13 Inactive

umair-ably marked this pull request as draft January 13, 2026 08:14

ably-ci temporarily deployed to ably-docs-authchanges-py2loc0j January 13, 2026 08:25 Inactive

umair-ably force-pushed the authChanges branch from 0906ade to 43cd265 Compare January 13, 2026 09:39

ably-ci temporarily deployed to ably-docs-authchanges-py2loc0j January 13, 2026 09:40 Inactive

umair-ably force-pushed the authChanges branch from 43cd265 to 2115ab9 Compare January 13, 2026 10:31

ably-ci temporarily deployed to ably-docs-authchanges-py2loc0j January 13, 2026 10:31 Inactive

umair-ably force-pushed the authChanges branch from 2115ab9 to 4b0b630 Compare January 14, 2026 09:23

ably-ci temporarily deployed to ably-docs-authchanges-py2loc0j January 14, 2026 09:23 Inactive

umair-ably marked this pull request as ready for review January 14, 2026 09:31

umair-ably requested a review from franrob-projects January 14, 2026 10:03

paddybyers requested changes Jan 14, 2026

View reviewed changes

umair-ably force-pushed the authChanges branch from 4b0b630 to f76e713 Compare January 14, 2026 11:01

ably-ci temporarily deployed to ably-docs-authchanges-py2loc0j January 14, 2026 11:01 Inactive

umair-ably force-pushed the authChanges branch from f76e713 to 6e4871d Compare January 14, 2026 11:44

ably-ci temporarily deployed to ably-docs-authchanges-py2loc0j January 14, 2026 11:45 Inactive

umair-ably force-pushed the authChanges branch from 6e4871d to 48f754c Compare January 14, 2026 11:58

ably-ci temporarily deployed to ably-docs-authchanges-py2loc0j January 14, 2026 11:58 Inactive

umair-ably force-pushed the authChanges branch from 48f754c to 178dc16 Compare January 14, 2026 12:06

ably-ci temporarily deployed to ably-docs-authchanges-py2loc0j January 14, 2026 12:06 Inactive

umair-ably requested review from mattheworiordan and paddybyers January 14, 2026 12:07

umair-ably commented Jan 14, 2026

View reviewed changes

umair-ably force-pushed the authChanges branch from 178dc16 to 0854b3e Compare January 15, 2026 08:56

ably-ci temporarily deployed to ably-docs-authchanges-py2loc0j January 15, 2026 08:57 Inactive

Several docs changes to highlight token auth over API key auth, as we…

3a2d796

…ll as more info on using JWTs

umair-ably force-pushed the authChanges branch from 0854b3e to 3a2d796 Compare January 15, 2026 09:01

ably-ci temporarily deployed to ably-docs-authchanges-py2loc0j January 15, 2026 09:02 Inactive

paddybyers requested changes Jan 26, 2026

View reviewed changes

m-hulbert deployed to ably-docs-authchanges-i9bbknme January 28, 2026 09:17 View deployment

m-hulbert reviewed Jan 29, 2026

View reviewed changes


		## Server auth endpoint template

		Your server needs an endpoint that creates tokens. Here's a minimal example:


		### TokenRequest <a id="choosing-tokenrequest"/>

		Best for: Standard web and mobile applications using Ably SDKs.


		Room reactions are ephemeral and not stored or aggregated by Ably. The intention being that they show the overall sentiment of a room at a point in time.

		<Aside data-type='note'>


		## Approach 1: Separate Ably JWT <a id="separate-jwt"/>

		Your existing auth flow validates the user, then you create an Ably JWT using any JWT library. No Ably SDK is required on your server.


		If your `authUrl` endpoint is slow or unreliable, tokens may expire before refresh completes. Ensure your auth endpoint responds quickly (under 5 seconds) and is highly available.

		## Next steps


		The Ably SDK automatically calls your `authCallback` before the current token expires, ensuring seamless token rotation.

		## Next steps


		### JWT Authentication <a id="jwt-auth"/>

		<Aside data-type='note'>

	Set capabilities in a JWT using the `x-ably-capability` claim. No Ably SDK is required—any JWT library will work:
	Set capabilities in a JWT using the `x-ably-capability` claim. No Ably SDK is required - any JWT library will work:


		### Token capability determination <a id="capability-determination"/>

		The capabilities for tokens are determined based on those of the issuing API key and those requested by the token.


		It is possible for JWTs to contain authenticated claims for users that can be used to allow or disallow certain interactions in your channels.

		Messages can be annotated with trusted metadata copied from the client's authentication token by Ably servers. Clients are unable to directly publish messages with user claim metadata, and claims contained within the authentication token are signed to prevent tampering. Claims can be scoped to individual channels or to namespaces of [channels](/docs/channels). The most specific user claim will be added to the message as part of the `extras` object. Note that this does not apply to presence or metadata messages.

	Note that the machine on which you are running your auth server should have an accurate clock, as tokens and `TokenRequest` contain a timestamp. You can use an [NTP daemon](https://en.wikipedia.org/wiki/Ntpd), or if you are not able to control your server's clock, you can wish to use the `queryTime` [auth option](/docs/api/rest-sdk/types#auth-options).
	Note that the machine on which you are running your auth server should have an accurate clock, as tokens and `TokenRequest` contain a timestamp and have limited validity. You can use an [NTP daemon](https://en.wikipedia.org/wiki/Ntpd), or if you are not able to control your server's clock, you can wish to use the `queryTime` [auth option](/docs/api/rest-sdk/types#auth-options).


		### Multi-tenant SaaS with user roles <a id="scenario-multitenant"/>

		Recommendation: Ably JWT with channel claims


		## Token mechanism comparison <a id="comparison"/>

		\| Feature \| Ably JWT (Recommended) \| Embedded JWT \| TokenRequest \|


		Capabilities are permissions that control what operations a client can perform. When you create a token for a Chat user, you specify which capabilities they have. Each Chat feature requires specific capabilities:

		\| Feature \| Required Capabilities \|


		## Space-scoped capabilities

		You can restrict tokens to specific spaces. Spaces uses multiple channels per space:


		Use `authCallback` to fetch JWTs from your auth server:

		<Code>

[FTF-468] Several docs changes to highlight token auth over API key auth, as well as more info on using JWTs #3085

Are you sure you want to change the base?

[FTF-468] Several docs changes to highlight token auth over API key auth, as well as more info on using JWTs #3085

Uh oh!

Conversation

umair-ably commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

coderabbitai bot commented Jan 7, 2026

Review skipped

Uh oh!

paddybyers left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Error 40103: Token expired

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mattheworiordan left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

umair-ably commented Jan 8, 2026

Uh oh!

paddybyers left a comment

Choose a reason for hiding this comment

Uh oh!

umair-ably commented Jan 14, 2026

Uh oh!

umair-ably commented Jan 14, 2026

Uh oh!

umair-ably commented Jan 14, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

umair-ably commented Jan 15, 2026

umair-ably commented Jan 7, 2026 •

edited

Loading