User Authentication

User authentication signs in a WebSocket connection as an application user. It is separate from private or presence channel authorization.

Call pusher.signin() after connecting. A successful sign-in enables:

  • Server-to-user events.
  • Watchlist online/offline events.
  • Terminating all active connections for a user_id.

#Client setup

const pusher = new Pusher('app_key', {
    wsHost: 'wss.vask.dev',
    wsPort: 443,
    forceTLS: true,
    enabledTransports: ['ws', 'wss'],
    userAuthentication: {
        endpoint: '/pusher/user-auth',
    },
});

pusher.signin();

On sign-in, the SDK calls your userAuthentication.endpoint with the connection socket_id.

#Server response

Your endpoint returns auth and user_data. The user_data value must be a JSON-encoded string and must include a non-empty id.

{
    "auth": "app_key:hmac_signature",
    "user_data": "{\"id\":\"user-123\",\"name\":\"Ada\"}"
}

The signature covers:

{socket_id}::user::{user_data}

#WebSocket frame

The SDK sends this frame after it receives your auth response:

{
    "event": "pusher:signin",
    "data": {
        "auth": "app_key:hmac_signature",
        "user_data": "{\"id\":\"user-123\",\"name\":\"Ada\"}"
    }
}

Vask replies with:

{
    "event": "pusher:signin_success",
    "data": {
        "user_data": "{\"id\":\"user-123\",\"name\":\"Ada\"}"
    }
}

If the signature is invalid, the client receives pusher:error.

#Adding a watchlist

Add watchlist to user_data when the signed-in user should receive online/offline events for a set of other users.

{
    "id": "user-123",
    "name": "Ada",
    "watchlist": ["user-456", "user-789"]
}

Bind watchlist events after sign-in.

pusher.signin();

pusher.user.watchlist.bind('online', (event) => {
    console.log(event.user_ids);
});

pusher.user.watchlist.bind('offline', (event) => {
    console.log(event.user_ids);
});

#Presence is not user sign-in

Presence channel user_id identifies a member inside that channel. User authentication identifies the whole connection.

Use pusher:signin if you need server-to-user events or user termination. A client that only joins a presence channel is not enough for those features.

Prefer raw markdown? View this page as markdown.