Clerk

ClerkAuth is the Auth component’s Clerk-backed strategy. It wraps the official @clerk/backend SDK to verify session tokens, resolve the current user, and manage accounts (banning, locking, metadata, sessions, and password sign-in) behind the framework’s IAuth interface. A companion ClerkAuthMiddleware plugs Clerk into the request pipeline and maps a Clerk user onto the framework IUser, so your controllers read context.user and never depend on Clerk directly.

What ClerkAuth covers

A single getCurrentUser(token) call verifies the Clerk session token with your secret key and resolves the user. ClerkAuthMiddleware does the request-side work: it extracts the bearer token, enforces route roles, and maps the Clerk user onto IUser. Beyond authentication, the strategy reaches the Clerk Backend API to ban or lock accounts, update profiles, manage metadata, and revoke sessions. Password sign-in is covered too, where signIn() verifies credentials and mints a Clerk sign-in token. Registration runs through @decorator.auth(), so there’s no manual wiring.

Installation

ClerkAuth ships with @talosjs/auth and depends on the Clerk Backend SDK.

bun add @talosjs/auth @clerk/backend

Environment variables

Variable	Required	Purpose
`CLERK_SECRET_KEY`	Yes	Clerk Backend API secret key. Missing throws `AuthException` (`API_KEY_REQUIRED`).

CLERK_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxxxxx

The secret key is validated when ClerkAuth is constructed, so a missing key fails fast at startup rather than on the first request.

How it works

ClerkAuthMiddleware runs in the request pipeline. For each request it:

Reads 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 lets the request through without a token.
Otherwise calls ClerkAuth.getCurrentUser(token), which verifies the token and loads the Clerk user.
Maps the Clerk user onto the framework IUser and sets it on context.user.

Request → Bearer token
  → ClerkAuthMiddleware: route requires roles?
      → guest-only  → continue, no token needed
      → protected   → verifyToken → getUser → context.user
  → Controller (context.user is available)

When mapping, the middleware pulls the user’s primary email, derives roles and the internal id from Clerk’s privateMetadata (falling back to ROLE_USER), and copies across name, phone, avatar, activity timestamps, and ban/lock flags.

Usage

Register the middleware (and ClerkAuth) with the container, then declare route roles. The middleware enforces them automatically.

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

const auth = container.get(ClerkAuth);

// Resolve the current user from a session token
const user = await auth.getCurrentUser(token); // User | null

Protect a route by declaring the roles it requires. The middleware verifies the Clerk token only when roles are present:

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 Clerk token
})
export class ProfileController {
  public async index(context: ContextType<ProfileRouteType>) {
    const { user } = context; // mapped from Clerk by the middleware
    return context.response.json({
      id: user.id,
      email: user.email,
      roles: user.roles,
    });
  }
}

signIn() looks up the user by email, verifies the password through Clerk, and returns the user plus a sign-in token (default TTL 30 days):

const { user, token } = await auth.signIn({
  email: "ada@example.com",
  password: "s3cret",
  ttl: 2_592_000, // optional, seconds
});

await auth.signOut(sessionId); // revokes the Clerk session

Account management

ClerkAuth exposes the Clerk user and session APIs directly:

Method	Purpose
`getCurrentUser(token)`	Verify a token and resolve the user, or `null`.
`getUser(userId)`	Fetch a user by id.
`banUser(userId)` / `unbanUser(userId)`	Ban or unban a user.
`isBanned(userId)`	Whether the user is banned.
`lockUser(userId)` / `unlockUser(userId)`	Lock or unlock a user.
`isLocked(userId)`	Whether the user is locked.
`updateUser(userId, params)`	Update user attributes.
`updateUserProfileImage(userId, { file })`	Replace the profile image.
`updateUserMetadata(userId, params)`	Update public/private/unsafe metadata.
`getUserMetadata(userId)`	Read public/private/unsafe metadata.
`deleteUser(userId)`	Delete a user.
`deleteUserProfileImage(userId)`	Remove the profile image.
`getSession(sessionId)`	Fetch a session.
`getCurrentUserSession(token)`	Resolve the session for a token, or `null`.
`signIn({ email, password, ttl? })`	Verify credentials and mint a sign-in token.
`signOut(sessionId)`	Revoke a session.

Use in the app

In an @talosjs/app application, Clerk plugs in as a request middleware. Add ClerkAuthMiddleware to the middlewares slot of your App config. Importing it registers both ClerkAuthMiddleware and ClerkAuth with the container through @decorator.auth(), so there is nothing else to wire.

bun add @talosjs/app @talosjs/auth @clerk/backend

import { App } from "@talosjs/app";
import { ClerkAuthMiddleware } from "@talosjs/auth";
import { TerminalLogger } from "@talosjs/logger";

const app = new App({
  routing: { prefix: "/api" },
  loggers: [TerminalLogger],
  middlewares: [ClerkAuthMiddleware], // runs on every matched route
});

await app.run();

Once registered, the middleware runs on each matched route: it reads the bearer token, enforces the route’s roles, and maps the Clerk user onto context.user. Controllers then read context.user and declare the roles they require (see Protecting routes above). Set CLERK_SECRET_KEY in your .env.yml (or environment) so the strategy can verify tokens.

Exceptions

ClerkAuth and ClerkAuthMiddleware throw AuthException with a machine-readable key, so callers can branch on it.

Key	When
`API_KEY_REQUIRED`	`ClerkAuth` is constructed without `CLERK_SECRET_KEY`.
`INVALID_CREDENTIALS`	`signIn()` is given an unknown email or a wrong password.
`MISSING_BEARER_TOKEN`	A protected route is requested without a token.
`INVALID_TOKEN`	The token verifies to no user.
`NO_PRIMARY_EMAIL`	The Clerk user has no primary email address.

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

try {
  const { user, token } = await auth.signIn({ email, password });
  return context.response.json({ user, token });
} catch (error) {
  if (error instanceof AuthException && error.key === "INVALID_CREDENTIALS") {
    return context.response
      .status(401)
      .json({ error: "Invalid email or password" });
  }
  throw error;
}

Things worth doing

Load CLERK_SECRET_KEY from .env so it stays out of source control, never hard-coded. The middleware reads privateMetadata.roles and privateMetadata.externalId from Clerk, so set those for each user or the mapping onto IUser won’t be complete. In your handlers, read context.user rather than reaching for Clerk directly; that keeps controllers provider-agnostic and lets the auth strategy change underneath them. Declare roles on routes and let ClerkAuthMiddleware enforce them instead of re-checking tokens by hand. When something goes wrong, branch on AuthException.key and return 401 for INVALID_CREDENTIALS, MISSING_BEARER_TOKEN, and INVALID_TOKEN. See the Auth component for the strategy interface and route-protection model.

Getting Started

AI

Framework

Command Line

What ClerkAuth covers

Installation

Environment variables

How it works

Usage

Account management

Use in the app

Exceptions

Things worth doing

​What ClerkAuth covers

​Installation

​Environment variables

​How it works

​Usage

​Password sign-in

​Account management

​Use in the app

​Exceptions

​Things worth doing

What ClerkAuth covers

Installation

Environment variables

How it works

Usage

Password sign-in

Account management

Use in the app

Exceptions

Things worth doing