Identified clients

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 clientId.

There are three different ways a client can be identified with using a clientId:

• A client claims a clientId when authenticating with an API key.
• A client is authenticating with a token issued for a specific clientId.
• A client claims a clientId when authenticating with a token that is issued for a wildcard clientId.

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 clientId.

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 clientId.

The following example demonstrates how to issue an Ably TokenRequest with an explicit clientId:

RealtimeREST
JavaScriptNode.jsRubyPythonJavaC# .NETObjective-CSwift
Select...

const realtime = new Ably.Realtime({ key: '<loading API key, please wait>' });
const tokenRequest = await realtime.auth.createTokenRequest({ clientId: 'Bob'});

API Key:
Demo Only
Copy
Copied!

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.

If no 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.