JWT Authentication

Name: Euler Stream API
Author: Euler Stream

Securely connect to the Euler Stream WebSocket server from client-facing apps using JSON Web Tokens.

When building client-facing applications, you should never expose your API key in the browser. Instead, provision a short-lived JWT from your backend and pass it to the frontend for WebSocket connections.

How It Works

Your backend calls the Euler Stream API to create a JWT with scoped permissions
Your backend returns the JWT to the frontend
The frontend connects to wss://ws.eulerstream.com using the JWT

Backend: Provision a JWT

Using the TypeScript SDK:

import EulerStreamApiClient from "@eulerstream/euler-api-sdk";
 
const client = new EulerStreamApiClient({
  apiKey: process.env.EULER_API_KEY!,
});
 
async function createJwt(uniqueId: string): Promise<string> {
  const response = await client.authentication.createJWT(
    process.env.EULER_ACCOUNT_ID!,
    {
      expireAfter: 60, // seconds - keep it short
      websockets: {
        allowedCreators: [uniqueId], // restrict to specific creator
        maxWebSockets: 1,            // limit concurrent connections
      },
    }
  );
 
  return response.data.token;
}

Use short JWT lifetimes (60 seconds or less). Users should provision a new JWT for each connection.

Frontend: Connect with JWT

const jwtKey = "JWT_FROM_YOUR_BACKEND";
const uniqueId = "tv_asahi_news";
 
const ws = new WebSocket(
  `wss://ws.eulerstream.com?uniqueId=${uniqueId}&jwtKey=${jwtKey}`
);
 
ws.addEventListener("open", () => {
  console.log("Connected!");
});
 
ws.addEventListener("message", (event) => {
  console.log("Event:", event.data);
});
 
ws.addEventListener("close", (event) => {
  console.log(`Closed: ${event.code} - ${event.reason}`);
});

JWT Scoping

JWTs can be scoped to restrict what the token holder can do:

Field	Description
`expireAfter`	Token lifetime in seconds
`websockets.allowedCreators`	Array of `unique_id` values this JWT can connect to
`websockets.maxWebSockets`	Maximum concurrent WebSocket connections

Always scope JWTs to the minimum required permissions. Restrict allowedCreators so users cannot use your JWT to connect to arbitrary creators.