Authentication

PieSocket Channels are easy to use by design but this brings its own problems. Anyone with your API key (which is public by nature, unlike secret key) can exhaust your quota, or view data going in and out of the Channel rooms.

You can solve the problem stated above by using a Private Channel room, or by enabling channel protection.

Private Channel Rooms

Private Channel Rooms require authentication for subscribing to them and begin with private- prefix. Read more in our Private channels section.

Recommended: Enable Authentication For All Channel Rooms

To enable forced authentication on all rooms, log in to your PieSocket dashboard and then go to Channel Settings section.

How To Authenticate

Authentication protected channels and Private channels throw the following error when someone tries to connect without the Authorization token.

{danger.fa-close} {"error":"Authentication failed, provide valid jwt token."}

You need to add a JWT token to the request to authenticate the user for access to the PieSocket channel.

JWT Token

There are two ways to send the JWT token with the WebSocket request.

Method Key Example
Query Param jwt wss://demo.piesocket.com/v3/1?api_key=xxx&jwt=JWT_TOKEN
Header jwt Host: demo.piesocket.com; jwt: JWT_TOKEN

Generating JWT Token

You need to generate a valid JWT token on your server using the API Secret.

Use following payload to generate your JWT token with HS256 encryption algorithm and sign it using your API secret key.

{
  "sub": ROOM_ID,  
  "iat": ISSUED_TIME, 
  "exp": EXPIRY_TIME
  "user": NUMBER|STRING|JSON
}

It is possible to generate JWT token online for testing purpose with JWT.io

{danger.fa-close} This token is only valid for the Room ID specified in sub key of the token payload. You need to create a separate JWT token for a different room.

Generating JWT on your server

You can generate JWT tokens on your server using any programming language. Following are a few reference links:

# Programming Language Library
1 PHP firebase/php-jw
2 Python PyJWT
3 NodeJS jsonwebtoken
4 Go jwt-go
5 Ruby ruby-jwt

You can find a JWT library for any language by typing in "Language name JWT library" in google.

Identifying A User

There are two ways to set user identity for a Channels member.

  1. Unsecured way: This is easy to implmenet but unsecured way to set user id/name. Pass &user=id to the WebSocket endpoint to set user's id or name.

  2. The right way: This is the secure way to set user identity. You should pass the user id/name/json into JWT payload, as described above.

If you wish to send notifications to one specific user over the WebSocket, you can make use of room IDs suffixed/prefixed with the user ID on your database.

For example, let all users on your website join user-123 room where 123 is their ID.

Then, if you want to send notification to user 456, you can publish a messge on the user-456 room. Since you are using Authentication with JWT, users can not join each other's rooms without your server issusing them a JWT token.