Room Authentication

You can authenticate your users using the onAuth method in your room. This method is called before onJoin, and it is responsible for validating the client’s request to join a room.

• If onAuth() returns a truthy value, onJoin() is going to be called with the returned value as the third argument.
• If onAuth() returns a falsy value, the client is immediatelly rejected, causing the matchmaking function call from the frontend to fail.
• You may also throw a ServerError to expose a custom error to be handled in the frontend.

With the colyseus bundle (which includes @colyseus/auth), the default static onAuth verifies the client’s JWT. A malformed or expired token is rejected with AUTH_FAILED. A client that sends no token passes through with no auth data.

import { Room } from "colyseus";
import { JWT } from "@colyseus/auth";
 
class MyRoom extends Room {
    static async onAuth (token, options, context) {
        // validate the token
        const userdata = await JWT.verify(token);
 
        // return userdata
        return userdata;
    }
}

import { Room, ServerError } from "colyseus";
 
class MyRoom extends Room {
    async onAuth (client, options, context) {
        // room-specific gate, e.g. reject spectators once the match started
        if (this.state.phase !== "lobby" && !options.spectator) {
            throw new ServerError(400, "match already in progress");
        }
        return true;
    }
}

import { Room } from "colyseus";
// ...
class MyRoom extends Room {
    // ...
    async onJoin (client, options, auth) {
        console.log(auth); // contains the "userdata" returned by onAuth
        console.log(client.auth); // shorthand/equivalent to `auth`
    }
}

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

client.joinOrCreate("my_room").then((room) => {
    console.log(room);
});

With @colyseus/database

When the @colyseus/database integration is active, the default onAuth verifies the JWT and enforces tokenVersion-based revocation. Bans and explicit bumpTokenVersion() calls both reject stale tokens automatically. Override the static onAuth only for room-specific logic (for example, surfacing the ban reason in the close frame instead of a generic AUTH_FAILED). Note that overriding it replaces the default, so you re-do the token verification yourself:

import { Room, ServerError } from "colyseus";
import { JWT } from "@colyseus/auth";
import { db } from "../app.config";
 
class MyRoom extends Room {
    static async onAuth(token, options, context) {
        const payload = await JWT.verify(token); // throws on invalid/expired
        const { banned, reason } = await db.auth.isBanned(payload.id);
        if (banned) {
            throw new ServerError(403, reason ?? "You are banned.");
        }
        return payload; // becomes client.auth
    }
}

onAuth Context

The third argument of the onAuth method is the context object. Both static onAuth and onAuth methods receive the same context object as the third argument.

The context object has the following properties:

• context.token - the authentication token sent by the client.
• context.headers - the headers sent by the client.
• context.ip - the IP address of the client.
• context.req - the matchmaking HTTP request, on static onAuth only.

Accessing the Auth Token

The authentication token is available in the context.token property.

// ...
async onAuth(client, options, context) {
    console.log(context.token);
}
// ...

Accessing the request headers

The request headers are available in the context.headers property.

// ...
async onAuth(client, options, context) {
    console.log(context.headers);
}
// ...

Accessing the client IP address

The client IP address is available in the context.ip property, as a single address. Colyseus reads it from x-real-ip, then the first entry of x-forwarded-for, then x-client-ip, and falls back to the address of the connection itself. The property is undefined when no source provides one.

// ...
async onAuth(client, options, context) {
    console.log(context.ip);
}
// ...

It contains the value of the X-Real-IP header, if available. If not, it falls back to the X-Forwarded-For header, and finally to the request object’s remoteAddress property.