Realtime · Socket.IO

Connection & security

Socket.IO on the API origin, path /socket.io/. Authenticate with an access JWT.

Getting a token for your own end-users

The <ACCESS_JWT> below is not a Mudbase-console token — it's the same access token your project's own auth already issues to your app's end-users. Sign a user in through any of your project's auth methods (email/password, OTP, magic link, or anonymous), and the response includes a token field. Pass that value straight into the socket handshake — no separate "realtime token" endpoint exists.

// 1. Sign your end-user in (any project auth method — shown here: email/password)
const { token } = await fetch("https://cloud.mudbase.dev/api/auth/local/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email, password, projectId: "<YOUR_PROJECT_ID>" }),
}).then((r) => r.json())

// 2. Use that token to open the socket
const socket = io("https://cloud.mudbase.dev", {
  path: "/socket.io/",
  auth: { token },
})

// 1. Sign your end-user in (any project auth method — shown here: email/password)
const { token } = await fetch("https://cloud.mudbase.dev/api/auth/local/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email, password, projectId: "<YOUR_PROJECT_ID>" }),
}).then((r) => r.json())

// 2. Use that token to open the socket
const socket = io("https://cloud.mudbase.dev", {
  path: "/socket.io/",
  auth: { token },
})

URL & client (browser)

import { io } from "socket.io-client"

const socket = io("https://cloud.mudbase.dev", {
  path: "/socket.io/",
  transports: ["websocket", "polling"],
  auth: { token: "<ACCESS_JWT>" },
})

import { io } from "socket.io-client"

const socket = io("https://cloud.mudbase.dev", {
  path: "/socket.io/",
  transports: ["websocket", "polling"],
  auth: { token: "<ACCESS_JWT>" },
})

Node / tests (Bearer header)

const socket = io(baseUrl, {
  path: "/socket.io/",
  extraHeaders: { Authorization: `Bearer ${token}` },
})

const socket = io(baseUrl, {
  path: "/socket.io/",
  extraHeaders: { Authorization: `Bearer ${token}` },
})

JWT rules

Failure → connect_error, message Authentication error.

On successful connect

Plan limit

If your plan’s realtime connection limit is exceeded:

1. Server emits error: { "message": "Realtime connection limit reached for your plan.", "limit": <n> }
2. Socket disconnects.