When a client is authenticated and connected to Ably, it is considered to be an authenticated client. While an authenticated client has a means to authenticate with Ably, they do not necessarily have an identity.
When a client is assigned a trusted identity, that is, a
clientId, then they are considered to be an identified client. For all operations that client performs with the Ably service, their
clientId field will be automatically populated and can be trusted by other clients.
For example, assume you are building a chat application and want to allow clients to publish messages and be present on a channel. If each client is assigned a trusted identity by your server, such as a unique email address or UUID, then all other subscribed clients can trust any messages or presence events they receive in the channel as being from that client. No other clients are permitted to assume a
clientId that they are not assigned in their Ably-compatible token. They are unable to masquerade as another
There are three different ways a client can be identified with using a
- A client claims a
clientIdwhen authenticating with an API key.
- A client is authenticating with a token issued for a specific
- A client claims a
clientIdwhen authenticating with a token that is issued for a wildcard
When a client sets their own ID there is the possibility that they can pretend to be someone else. To prevent this, it is recommended that you embed a
clientId in the token issued to your clients from your auth server. This ensures that the
clientId is set by your auth server, and eliminates the chance of a client pretending to be someone else.
You can use basic authentication to allow a client to claim any
clientId when they authenticate with Ably. As the assignation of the
clientId is not handled by a server, it cannot be trusted to represent the genuine identity of the client.
You can use token authentication to set an explicit
clientId when creating or issuing a token. Clients using that token are restricted to operations for only that
clientId, and all operations will implicitly contain that
For example, when publishing a message, the
clientId attribute of the message will be pre-populated with that
clientId. Entering presence will also implicitly use that
The following example demonstrates how to issue an Ably TokenRequest with an explicit
You can use token authentication to set a wildcard
clientId using a value of
* when creating a token. Clients are then able to assume any identity in their operations, such as when publishing a message or entering presence.
clientId is provided when using token authentication then clients are not permitted to assume an identity and will be considered an unidentified client in all operations. Messages published will contain no
clientId and those clients will not be permitted to enter the presence set.