HTTP Middleware

If you are using the HTTP API, you can authenticate your requests using the Authorization header.

Client SDK: Set the auth token

client.js

// set the auth token
client.auth.token = "YOUR AUTH TOKEN";

If you are using the @colyseus/auth module, this token is managed automatically. See Authentication → Module.

Client SDK: Make HTTP requests

The HTTP requests contain the auth token in the Authorization header.

client.js

client.http.get("/profile").then((response) => {
    console.log(response.data);
});

Server: Validate the auth token

If you are using the @colyseus/auth module, auth.middleware() works in both the HTTP Routes system (createEndpoint / createMiddleware) and as an Express middleware. The decoded JWT payload is exposed on ctx.context.auth (HTTP routes) or req.auth (Express).

src/endpoints/profile.ts

import { createEndpoint } from "colyseus";
import { auth } from "@colyseus/auth";
 
export const profile = createEndpoint("/profile", {
    method: "GET",
    use: [auth.middleware()],
}, async (ctx) => {
    console.log("authenticated user:", ctx.context.auth);
    return ctx.context.auth;
});

See HTTP Routes for how endpoints are mounted via createRouter.

src/app.config.ts

import { defineServer } from "colyseus";
import { auth } from "@colyseus/auth";
 
const server = defineServer({
    // ...
    express: (app) => {
        app.use("/profile", auth.middleware(), (req, res) => {
            console.log("authenticated user:", req.auth);
            res.json(req.auth);
        });
    }
    // ...
});

src/app.config.ts

function yourAuthMiddleware (req, res, next) {
    const authorization = req.headers.authorization;
    // TODO: validate the "authorization" token here
    next();
}
 
app.use("/profile", yourAuthMiddleware, (req, res) => {
    // handle the request
});

⚠️

tokenVersion-based revocation (db.auth.ban(), db.auth.bumpTokenVersion()) is enforced on room joins. auth.middleware() only verifies the JWT’s signature and expiry. A revoked-but-unexpired token still passes HTTP routes; if a route must observe revocation immediately, check db.auth.isBanned() / the tokenVersion claim yourself inside the handler. See Database → Authentication.

Room Authentication Auth Module