Authentication

WebSocket authentication and authorization plug directly into Arkos's existing Built-in Authentication System — there's no separate auth setup for sockets. If your HTTP routes are already authenticated, you're most of the way there.

Enabling it on a Gateway

const chatGateway = ArkosGateway({
  name: "/chat",
  authentication: true,
});

With authentication: true, every connection to this namespace runs through Arkos's auth middleware before it's accepted. On success, socket.currentUser is populated and the socket is joined to a arkos::user:{id} room automatically — this is what powers socket.user(id) in the Enhanced Socket guide. On failure, the connection is rejected before your connection hook ever runs.

chatGateway.hook("connection", (socket) => {
  console.log(socket.currentUser.id); // guaranteed to exist here
});

Gotcha: you still need an auth mode configured

authentication: true on a Gateway doesn't configure authentication from scratch — it reuses whatever mode (static or dynamic) you already set under arkos.config.ts. If you set authentication: true on a Gateway without ever configuring an authentication mode for your app, Arkos throws on startup rather than silently accepting unauthenticated sockets.

Nested Gateways inherit this

A child Gateway registered via .use() inherits its parent's authentication setting unless it explicitly overrides it. See Attaching connection middleware or nesting Gateways.

Per-event authorization

Authentication answers "who is this," authorization answers "can they do this." It's set per event:

import { ArkosPolicy } from "arkos";

const chatPolicy = ArkosPolicy("chat").rule("DeleteMessage", {
  resource: "message",
  action: "delete",
  rule: ["Admin", "Moderator"],
});

export default chatPolicy;

import chatPolicy from "@/src/modules/chat/chat.policy"

chatGateway.on(
  {
    event: "delete_message",
    authorization: chatPolicy.DeleteMessage,
  },
  (socket, data) => {
    // only reached if the check passes
  }
);

authorization accepts the same object shape provided by ArkosPolicy instances.

Gotcha: authorization requires gateway-level authentication

const chatGateway = ArkosGateway({ name: "chat", authentication: false });

chatGateway.on(
  {
    event: "delete_message",
    authorization: chatPolicy.DeleteMessage,
  },
  handler
);
// throws immediately, at registration time:
// Event "delete_message" on "chat" gateway defines authorization rules
// but the gateway has authentication: false.

This fails fast and loud on startup rather than at runtime on the first request — if you see this error, either set authentication: true on the Gateway, or drop authorization from the event.

Where it sits in the request lifecycle

Authorization runs after rate limiting and before validation. See the full ordering in Full request lifecycle for one event.