Auth

The @talosjs/auth component ships a Clerk-backed auth client and middleware. ClerkAuth verifies bearer tokens and manages Clerk users and sessions, while ClerkAuthMiddleware resolves the authenticated user onto context.user for protected routes. The package also exposes the minimal IAuth interface and @decorator.auth() decorator used by those classes.

What it handles

The middleware extracts a bearer token, verifies it through Clerk, and resolves the current user, so you don’t wire that pipeline yourself. It reads each route’s roles and only enforces authentication where it’s required; guest routes pass straight through. Controllers read context.user and never touch Clerk directly unless they need user-management or session-management operations from ClerkAuth.

How it works

Authentication runs as middleware in the request pipeline. For each request it:

Extracts the token from the Authorization: Bearer <token> header (or a bearerToken query).
Checks the route’s roles — if the route is guest-only (no roles or ROLE_GUEST), it skips verification.
Otherwise verifies the token and resolves the user via getCurrentUser(token).
Maps the provider’s user onto the framework IUser and sets it on context.user.

Request → Bearer token
  → Auth middleware: route requires roles?
      → guest-only  → continue, no token needed
      → protected   → verify token → getCurrentUser(token) → context.user
  → Controller (context.user is available)

Downstream controllers read context.user and never import the auth provider directly.

Environment variables

Variable	Required	Purpose
`CLERK_SECRET_KEY`	Yes	Secret used by `ClerkAuth` to verify tokens and call Clerk APIs. Missing throws `AuthException` (`API_KEY_REQUIRED`).

Decorator and usage

`@decorator.auth()`

Registers an auth class with the container. It accepts an optional scope (defaults to singleton). A class only needs to implement getCurrentUser() to satisfy IAuth.

import { ClerkAuth } from "@talosjs/auth";
import { container } from "@talosjs/container";

const auth = container.get(ClerkAuth);
const user = await auth.getCurrentUser(token);

ClerkAuth also exposes Clerk-specific helpers for user and session management, including getUser, updateUser, signIn, signOut, getSession, banUser, and lockUser.

Protecting routes

Declare the roles a route requires in its Route decorator. The middleware enforces authentication only when roles are present. An empty list (or ROLE_GUEST) leaves the route open.

import { Route } from "@talosjs/routing";

@Route.get("/api/profile", {
  name: "profile",
  version: 1,
  description: "Get the current user profile",
  roles: ["ROLE_USER"], // requires a valid token
})
export class ProfileController {
  public async index(context: ContextType<ProfileRouteType>) {
    const { user } = context; // set by the auth middleware
    return context.response.json({
      id: user.id,
      email: user.email,
      roles: user.roles,
    });
  }
}

A guest route omits roles, so no token is required:

@Route.post("/api/login", {
  name: "login",
  version: 1,
  description: "Sign in with email and password",
  roles: [], // guest-only — token not required
})
export class LoginController {
  public async index(context: ContextType<LoginRouteType>) {
    // ...
  }
}

Exceptions

The component throws AuthException for authentication failures. It carries a machine-readable key, a human-readable message, and a data object, so callers can branch on the key.

Key	When
`API_KEY_REQUIRED`	`ClerkAuth` is created without `CLERK_SECRET_KEY`.
`MISSING_BEARER_TOKEN`	A protected route is requested without a token.
`INVALID_TOKEN`	Token verification fails or resolves no user.
`NO_PRIMARY_EMAIL`	Clerk resolved a user, but the user has no primary email address.
`INVALID_CREDENTIALS`	`ClerkAuth.signIn()` receives an unknown email or invalid password.

import { AuthException } from "@talosjs/auth";

try {
  const user = await auth.getCurrentUser(token);
  return context.response.json({ user });
} catch (error) {
  if (error instanceof AuthException && error.key === "INVALID_TOKEN") {
    return context.response
      .status(401)
      .json({ error: "Invalid or expired token" });
  }
  throw error;
}

Guidance

Drive access from route roles: declare roles on the route and let the middleware enforce them, rather than re-checking tokens inside controllers. Read context.user instead of the provider, which keeps controllers independent of whichever strategy is in use. When you catch an AuthException, branch on its key, returning 401 for MISSING_BEARER_TOKEN and INVALID_TOKEN; keep the keys stable and put detail in data. Load CLERK_SECRET_KEY from .env and never hard-code it. Resolve ClerkAuthMiddleware in the request pipeline and read context.user in controllers. When you need Clerk-specific operations such as signIn(), signOut(), getSession(), or user updates, inject ClerkAuth directly rather than re-implementing token verification in the controller.

Getting Started

AI

Framework

Command Line

What it handles

How it works

Environment variables

Decorator and usage

`@decorator.auth()`

Protecting routes

Exceptions

Guidance

​What it handles

​How it works

​Environment variables

​Decorator and usage

​@decorator.auth()

​Protecting routes

​Exceptions

​Guidance

What it handles

How it works

Environment variables

Decorator and usage

`@decorator.auth()`

Protecting routes

Exceptions

Guidance