Ably's changelog
Ably's changelog

Updates, deletions, and edit permissions in chat apps with Ably JWT user claims


New feature


Ably JWT user claims help developers implement chat room roles quickly and cleanly in chat applications built with Ably.

When building a chat room, you may wish to provide the ability to update and delete messages. This is an expected feature for users, and an important tool for moderators or administrators.

Users may have different permissions depending on their role in the chat room:

  • Any chat user can update or delete their own messages
  • Moderators or administrators can update or delete anyone’s messages

Ably JWT user claims* let chat room role information be added to JWT authentication tokens, which are then available to your application when checking if an edit is valid. Under the hood it can be used to support application logic for any type of message interaction, not only updates and deletion.

How does it work?

Ably provides message interactions as a flexible way to implement features such as message updates and deletions. Users supply updated content or a deletion marker as a message interaction that is tied to the original message. Applications should compare client IDs between these messages to verify whether the interaction is valid. Typically, only message interactions made by the user who produced the original message will be accepted.

Now consider the task of extending this validation to support content moderators or administrators, who are permitted to make broader changes.

By adding an Ably JWT user claim to those users’ authentication tokens, you can supply additional descriptive information - in this case, their role. Ably will then pass this information on every message sent by those users, allowing clients to directly verify that the message interaction was issued by a user with the appropriate permissions. Ably does not prescribe how this is done, you are free to validate using whatever logic is appropriate for your application.


Below is a JWT payload, showing a chat user with relatively complex permissions. The format is customisable to your application; here we use simple strings.

  "sub": "65847593",
  "name": "John Doe",

  // The user is an administrator in the 'helpdesk' channel
  "ably.channel.helpdesk": "administrator", 

  // The user is a moderator in all channels in the 'chat' channel namespace
  "ably.channel.chat:*": "moderator",

  // The user is a guest in all other channels 
  "ably.channel.*": "guest"

Here is an example of a message interaction for a deletion. The JWT user claim is provided in the message ‘extras’ for the client application to use. The content of ‘extras’ is controlled by Ably only and can’t be produced by other clients.

  "name": "chat-message",
  "data": "This message has been removed by a moderator",
  "extras": {
    "userClaim": "moderator",
    "ref": {
      "type": "com.ably.deletion",
      "timeserial": "1126583028565-1",

Getting started with Ably JWT user claims

  • Read the documentation for JWT user claims
  • Include user claims in the JWTs for your moderators, administrators, or other privileged users
  • In your client application, use the trusted information in ‘extras’ to validate message interactions appropriately

How do I give feedback?

We’d love to hear your views and questions. You can contact us at any time if you would like to send feedback.