DEV Community: MongoDB Guests

Streaming MongoDB Change Events to Amazon Redshift via Atlas Stream Processing and Kinesis

MongoDB Guests — Wed, 05 Aug 2026 13:13:42 +0000

This tutorial was written by Igor Alekseev.

Real-time data pipelines that move operational data into analytical systems are a cornerstone of modern architectures. In this post, I’ll walk through how to stream MongoDB change events into Amazon Redshift using MongoDB Atlas Stream Processing and AWS Kinesis Data Streams — with no S3 staging or Firehose in between.

Architecture Overview

The flow is straightforward:

MongoDB Atlas — Changes (inserts, updates, replaces) occur in a collection.
Atlas Stream Processing — A stream processor captures these changes via a change stream, filters and reshapes them into flat JSON, and emits records to Kinesis.
AWS Kinesis Data Stream — Acts as the durable, ordered buffer between the source and the analytical store.
Amazon Redshift — A streaming materialized view reads directly from Kinesis and exposes the data as queryable columns.

The key advantage here is simplicity: there’s no intermediate S3 bucket, no Firehose delivery stream, and no ETL job to manage. Data flows from operational writes to analytical queries in near real-time.

Why This Combination?

Atlas Stream Processing handles the hardest part of change data capture — it connects natively to MongoDB change streams, handles resume tokens, and provides a pipeline language (aggregation framework) for reshaping documents on the fly. Instead of writing and hosting a custom consumer, you declare a pipeline, and Atlas manages the execution.

Kinesis provides a durable, ordered stream that decouples the producer (Atlas) from the consumer (Redshift). If Redshift has a maintenance window or you need to replay data, Kinesis retains records for up to 365 days.

Redshift Streaming Ingestion eliminates the traditional pattern of landing data in S3 first. A materialized view reads directly from the Kinesis stream, making new records queryable within seconds of arrival.

Implementation

Step 1: Create the Kinesis Data Stream

aws kinesis create-stream \
  --stream-name atlas-change-events \
  --shard-count 1 \
  --region us-east-1

A single shard handles up to 1 MB/s or 1,000 records/s ingest. Scale shards based on your change event volume.

Step 2: Set Up IAM for Atlas

Atlas Stream Processing authenticates to Kinesis via IAM AssumeRole. Create a role with a trust policy that allows the Atlas AWS account to assume it, and attach minimal Kinesis write permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kinesis:PutRecords",
        "kinesis:DescribeStreamSummary"
      ],
      "Resource": "arn:aws:kinesis:us-east-1:<YOUR_ACCOUNT>:stream/atlas-change-events"
    }
  ]
}

That’s it — just two permissions. Atlas uses the batch API (PutRecords) exclusively, so you don’t need the single-record API (PutRecord) or the full DescribeStream.

Step 3: Register the Kinesis Connection in Atlas

In the Atlas UI, navigate to Stream Processing → Connection Registry → Add Connection → Kinesis, and provide:

The stream name
The AWS region
The IAM role ARN

Step 4: Create the Stream Processor

The stream processor is an aggregation pipeline that runs continuously. Here’s the pattern:

sp.createStreamProcessor("atlasToKinesisProcessor", [
  // 1. Filter for relevant operation types
  { $match: { operationType: { $in: ["insert", "update", "replace"] } } },

  // 2. Flatten the change event — promote fullDocument fields to top level
  { $replaceRoot: {
      newRoot: { $mergeObjects: ["$fullDocument", { _operationType: "$operationType" }] }
  }},

  // 3. Project into a flat structure for Kinesis/Redshift
  { $project: {
      device_id: "$device_id",
      timestamp: "$timestamp",
      watts: "$obs.watts",
      temp: "$obs.temp",
      _operationType: 1
  }},

  // 4. Emit to Kinesis
  { $emit: {
      connectionName: "myKinesisConnection",
      stream: "atlas-change-events",
      region: "us-east-1",
      partitionKey: "$device_id"
  }}
]);

The $emit stage is Kinesis-specific. Note that stream, region, and partitionKey are all top-level fields — not nested inside a config object.

After creating the processor, start it in mongosh connected to your Stream Processing Instance (SPI):

sp.atlasToKinesisProcessor.start();

Step 5: Set Up Redshift Streaming Ingestion

On the Redshift side, create an external schema pointing to Kinesis:

CREATE EXTERNAL SCHEMA IF NOT EXISTS kinesis_schema
FROM KINESIS
IAM_ROLE 'arn:aws:iam::<YOUR_ACCOUNT>:role/<REDSHIFT_ROLE>';

Then create a streaming materialized view that parses the JSON records:

CREATE MATERIALIZED VIEW mdb_change_events AUTO REFRESH YES AS
SELECT
  approximate_arrival_timestamp,
  JSON_EXTRACT_PATH_TEXT(from_varbyte(kinesis_data, 'utf-8'), 'device_id') AS device_id,
  JSON_EXTRACT_PATH_TEXT(from_varbyte(kinesis_data, 'utf-8'), 'timestamp') AS event_timestamp,
  CAST(JSON_EXTRACT_PATH_TEXT(from_varbyte(kinesis_data, 'utf-8'), 'watts') AS DOUBLE PRECISION) AS watts,
  CAST(JSON_EXTRACT_PATH_TEXT(from_varbyte(kinesis_data, 'utf-8'), 'temp') AS DOUBLE PRECISION) AS temp,
  JSON_EXTRACT_PATH_TEXT(from_varbyte(kinesis_data, 'utf-8'), '_operationType') AS operation_type
FROM kinesis_schema."atlas-change-events";

With AUTO REFRESH YES, Redshift continuously ingests new records. You can also trigger a manual REFRESH MATERIALIZED VIEW mdb_change_events; if needed.

Step 6: Query Your Data

SELECT * FROM mdb_change_events
ORDER BY approximate_arrival_timestamp DESC
LIMIT 10;

That’s it. Operational writes in MongoDB are now queryable in Redshift within seconds.

Lessons Learned

Flatten before emitting. Redshift’s JSON_EXTRACT_PATH_TEXT is limited to 5 levels of nesting, has a 16MB record cap, and AWS recommends migrating to JSON_PARSE with SUPER type instead. By flattening in Atlas Stream Processing ($replaceRoot + $project), Kinesis receives simple flat JSON, and the Redshift materialized view stays clean.
The materialized view only captures new records. Records already in the stream when the view is created may not appear. Create the view before starting the processor, or insert fresh test data after creation.
External schema creation requires a superuser. The CREATE EXTERNAL SCHEMA statement must be run by the database owner or a user with the CREATE SCHEMA privilege. If your IAM-federated session doesn’t have these privileges, connect with the admin user and password instead.

When to Use This Pattern

This architecture works well when:

You need near-real-time analytics on operational MongoDB data
You want to avoid managing CDC infrastructure (Debezium, Kafka Connect, custom consumers)i
Your analytical queries run in Redshift, and you want columnar performance
You prefer a serverless, managed approach with minimal operational overhead

For higher throughput or more complex transformations, you might add more Kinesis shards and scale the Atlas Stream Processing instance accordingly. The architecture stays the same — just the capacity changes.

References

An agent is a graph

MongoDB Guests — Tue, 04 Aug 2026 16:04:18 +0000

This tutorial was written by Néstor Daza.

This is the fourth article in a series about building Claudius, my own Claude-based chatbot (Github). In the previous article, we scaffolded the core components of the app.

We already built the foundation: the data model, an identity the client cannot tamper with, and a health check that proves the application can reach both Atlas and Bedrock. We can now move to the streaming chat backbone, the phase where the conversation finally becomes real and Claudius turns into something you can use every day as your favorite AI tool.

We are going to build the live path, everything that happens between hitting send and tokens arriving on screen. The model runs as a small agent that can pause to search the web, stream its answer back word by word, and let you switch from a cheap model to a strong one in the middle of a thread without losing your place. The next article will be about where the conversation lives once the tokens stop, the persistence, the metering, and the guarded writing operations that keep the whole thing grounded. Here, the question is narrower and more immediate: what actually happens when you hit send?

The agent is not a prompt

The chat engine is not a single call to a model wrapped in a clever prompt; it’s a small state machine built with LangGraph, a design choice that lets the model do more than answer in one shot.

The graph has three nodes. load_context runs but does nothing yet, as a deliberate placeholder where memory retrieval will land in a later phase. agent is the model itself, bound to the tools it is allowed to call. tools is the executor that runs whatever the model asks for. A conditional edge sits after the agent; if the model requests a tool call, control passes to the tools node. If it returns a plain answer, the run ends. The tools node always loops back to the agent.

const builder = new StateGraph(MessagesAnnotation)
  .addNode("load_context", loadContext)
  .addNode("agent", agent)
  .addNode("tools", new ToolNode(tools))
  .addEdge(START, "load_context")
  .addEdge("load_context", "agent")
  .addConditionalEdges("agent", toolsCondition, ["tools", END])
  .addEdge("tools", "agent");

That loop keeps running until the model has what it needs, then returns a natural language answer instead of another tool call. A prompt answers once and stops, a graph keeps working until the task is finished.

Choose the model per run, not per graph

Here is the design decision that took the most thought, and it is invisible in the diagram above. The model is not compiled into the graph.

You might expect the agent node to close over a fixed model instance when the graph is constructed. Instead, the model is chosen per run and passed through LangGraph's configurable channel, the per-invocation configuration that travels alongside the graph state. The agent node reads the inference profile from that channel and builds its model client fresh on every turn.

async function agent(
  state: typeof MessagesAnnotation.State,
  config: RunnableConfig,
): Promise<typeof MessagesAnnotation.Update> {
  const { inferenceProfileId, maxTokens } = readConfigurable(config);
  const model = buildChatModel(
    inferenceProfileId,
    maxTokens !== undefined ? { maxTokens } : {},
  ).bindTools(tools);

  const response = await model.invoke(
    [new SystemMessage(SYSTEM_PROMPT), ...state.messages],
    config,
  );

  return { messages: [response] };
}

readConfigurable pulls the inference profile and token ceiling from the per-run config. buildChatModel constructs the ChatBedrockConverse client for that profile, and bindTools attaches the tool schema so the model knows what it is allowed to call (i.e, web_search). The node then invokes the model with the system prompt followed by the full message history, and returns the model's reply as the one update to the graph state.

Why go to this trouble? Because it is what makes switching models mid-conversation almost free. When you move from Haiku to Sonnet halfway through a thread, nothing about the stored conversation changes. The message history is untouched; on the next turn, we read a different inference profile from the config and build a different client using the same history. There is no graph to rebuild and no checkpoint to migrate. The model is a parameter of the turn, not a property of the conversation.

Model-switching appears in the request the client sends, not in the thread you see on screen. The rendered conversation carries no per-message model label, and the conversation row stores only the current model as a single field, so neither one records which model produced which turn. The request payload does, with each send carrying the conversation identifier, the chosen model, and the new text. Two consecutive sends in one conversation, sharing a conversationId and differing only in modelId, show up like this:

// Turn 3, sent while the selector was on Haiku
{
  "conversationId": "6770f1a2b3c4d5e6f7a8b9c0",
  "modelId": "claude-haiku",
  "text": "Summarize the tradeoffs we just covered."
}
// Turn 4, same conversation, selector now on Sonnet
{
  "conversationId": "6770f1a2b3c4d5e6f7a8b9c0",
  "modelId": "claude-sonnet",
  "text": "Now make the strongest case against that position."
}

The second turn still reads the full prior history that the server holds, so Sonnet answers turn four with turn three already in context, even though turn three ran on Haiku. The modelId is the public catalog identifier that the selector handed the client, paired with the display name on screen; the cross-region inference profile it resolves to remains on the server.

One tool, one predictable shape

The agent has just one tool in this phase, web_search, and it is a thin wrapper over Tavily. It returns exactly three fields per result: title, url, and snippet. Nothing else comes through.

The wrapper is hand-rolled rather than pulled from a library, to have a bit more control over the output shape. The model reads a compact JSON block, and the user interface renders it as a list of sources. Both sides depend on the shape staying fixed. Tavily returns its result text in a field called content, and the wrapper renames it to snippet at that boundary. Replace Tavily with another search service later, and the only code that changes is what's inside that wrapper.

This is a habit worth keeping past this one tool. A predictable shape at a boundary is cheap to build and prevents the rest of the system from developing a quiet dependency on a particular vendor's response format.

Bridging the event gap

The graph produces one kind of stream, the browser expects another; the route between them is a translation layer, the most intricate piece of this phase.

LangGraph emits a flat event log through its streamEvents interface. Model token chunks, tool starts, tool ends, and run boundaries all arrive as a sequence of typed events that you consume in order. The frontend uses the Vercel AI SDK, which expects something different, a typed stream of user-interface message parts. Natural text arrives as a text-start, then a run of text-delta events, then a text-end. Tool activity arrives as tool-input and tool-output parts. The two formats describe the same conversation, but they are not the same format. We need to close the gap between them.

A small state machine takes care of it. It walks the LangGraph event log and emits AI SDK parts as it goes.

for await (const ev of events) {
  switch (ev.event) {
    case "on_chat_model_stream": {
      const chunk = ev.data?.chunk as BaseMessage | undefined;
      const delta = chunk?.text ?? "";
      if (delta.length > 0) {
        if (textId === null) {
          textId = `text-${textSegment++}`;
          writer.write({ type: "text-start", id: textId });
        }
        writer.write({ type: "text-delta", id: textId, delta });
        assistantText += delta;
      }
      break;
    }
    case "on_chat_model_end": {
      endText();
      const output = ev.data?.output as
        | { usage_metadata?: UsageMetadata }
        | undefined;
      addUsage(totals, output?.usage_metadata);
      break;
    }
    case "on_tool_start": {
      writer.write({ type: "tool-input-start", toolCallId: ev.run_id, toolName: ev.name, dynamic: true });
      writer.write({ type: "tool-input-available", toolCallId: ev.run_id, toolName: ev.name, input: ev.data?.input ?? {}, dynamic: true });
      break;
    }
    case "on_tool_end": {
      writer.write({ type: "tool-output-available", toolCallId: ev.run_id, output: parseToolOutput(ev.data?.output), dynamic: true });
      break;
    }
  }
}

Read it event by event. On a model token chunk (on_chat_model_stream), if no text part is open yet, the machine opens one with a fresh identifier and a text-start, then writes the token as a text-delta and appends it to the running answer it keeps in assistantText. On the model turn ending (on_chat_model_end), endText closes the open part, emitting the text-end and resetting the identifier to null so the next token will open a new segment; the same handler pulls the token usage out of the event and adds it to the running totals, which the companion article picks up. On a tool starting (on_tool_start), the machine emits the tool-input parts. On a tool ending (on_tool_end), it parses the tool's JSON output back into a structured part that the renderer can show as sources.

Because the model finishes its turn before the tools it requires run, on_chat_model_end always fires ahead of on_tool_start. So each tool call sits cleanly between closed text segments, never inside an open one. The textSegment counter increments each time, so the answer the model writes after reading its search results opens as a fresh segment rather than reopening the one that came before the search. The renderer sees a clean sequence: natural text, then a tool call with its sources, then more text.

The tool parts are flagged dynamic. The web_search tool is not registered on the client with a schema, so as far as the AI SDK is concerned, its part is a dynamic tool, one whose shape is not known in advance. Marking it dynamic on the server lets the client assemble it into a cleanly typed part that the renderer can switch on, even though the client was never handed the tool's signature.

The conversation identifier rides back on a transient data part. When you send the first message in a brand-new conversation, the server creates the conversation row and needs to tell the client its identifier, without forcing a second request to get it. So it writes a one-off data-conversation part at the very top of the stream.

writer.write({ type: "start" });
writer.write({
  type: "data-conversation",
  data: { id: threadId, title: conversationTitle },
  transient: true,
});
writer.write({ type: "start-step" });

The client reads that part, adopts the identifier, updates the URL, and shows the new conversation in the sidebar, the part itself never becoming a message in the thread. transient marks it as out-of-band, a signal rather than content. No extra round trip, and the conversation is addressable from the first token onward.

The user sees what the agent did

The payoff of all that plumbing is visible on screen. Tokens animate in as they arrive, so the answer builds in front of you instead of appearing in one block after a wait. When the agent decides to search, a live line appears reading "Searching the web," and once results return, it collapses into an expandable list of the sources the tool found, each with its title and link.

That last behavior is a principle that runs through the whole product. Every tool call is visible and inspectable. The user should always be able to see what the agent did on their behalf, not only the polished answer that came out the other end. The event bridge is what makes this possible, because it carries tool activity through as first-class parts rather than burying it inside the model's turn.

There is one more thing to notice about the round trip, and it sets up the second half of the backbone. When you send a message, the client sends only the new text. It does not send back the transcript of everything said before. It cannot, really, because it does not hold the authoritative history. It holds only what it has rendered on screen. The full conversation lives elsewhere, and the model reads it from there on every turn.

Where it lives, and why one small identity decision makes reopening a week-old conversation as cheap as opening a fresh one, is the theme of the next article. The agent is a graph. The conversation, it turns out, is a database.

Building the foundation Claudius runs on

MongoDB Guests — Tue, 04 Aug 2026 15:21:07 +0000

This tutorial was written by Néstor Daza.

This is the third article in a series about building Claudius, my own Claude-based chatbot (Github). The previous article discussed the MongoDB data model to use for the app.

The previous article decided the shape of the data. None of it matters until the app around it is working, and getting it there is the unglamorous half of this phase. It comes down to three things: an identity system the client cannot tamper with, proof that Claudius can reach the two services it depends on, and the deployment realities that decide whether any of it runs at all. This is the boring work that quietly decides whether a project survives contact with production.

Identity: the client never gets a vote

Any Google account on Earth can sign into Claudius safely because a user's role is never something the client sends. It is decided on the server every time.

One piece of this lives outside the code. The Google provider needs an OAuth (Open Authorization) client that you register once in the Google Cloud Console, and the client identifier and secret from that registration are set in corresponding env variables. These setup steps live in the Auth.js and Google documentation, so I am not repeating them here.

Sign-in runs on Auth.js v5 with the Google provider and the MongoDB adapter. There are three roles, admin, member, and guest, and they resolve in exactly one place on the server, with a clear precedence:

export async function resolveRole(email: string | null | undefined): Promise<Role> {
  if (!email) return "guest";

  const normalized = email.toLowerCase();
  if (normalized === env.ADMIN_EMAIL.toLowerCase()) return "admin";

  const settings = await settingsCol();
  const allowlist = await settings.findOne({ _id: "allowlist" });
  if (allowlist && "emails" in allowlist) {
    const allowed = allowlist.emails.some((e) => e.toLowerCase() === normalized);
    if (allowed) return "member";
  }

  return "guest";
}

The bootstrap admin email wins outright, an allowlist of member emails in the settings collection comes next, and everyone else falls through to guest, the least-privileged default. The client supplies a Google identity and nothing more. It never names its own role, so there is no request a user can forge to promote themselves.

The session uses a JWT (JSON Web Token) rather than a database-backed session, so the resolved role is stored in the token and is available without a database read on every request. That choice has one small downside: the token caches the role until it refreshes, so adding someone to the member allowlist takes effect on their next sign-in, not the moment you edit the list. For a personal project, that is a fine trade.

The wiring is small: on first sign-in, the jwt callback calls provisionUser and stores the returned role on the token, and the session callback then copies it onto session.user for the app to read.

Provisioning is the other half of sign-in. The adapter has already written a bare user document, just the name, email, and image Google returns. It fills in the Claudius-specific fields with a single aggregation-pipeline update built around $ifNull, so each field defaults only when it is absent, and an admin's later change is never overwritten. The role is the exception, recomputed every time, since that is the field on which the whole security model rests:

export async function provisionUser(
  userId: string,
  email: string | null | undefined,
): Promise<Role> {
  const role = await resolveRole(email);
  const users = await usersCol();

  const resetsAt = new Date(Date.now() + 24 * 60 * 60 * 1000);

  await users.updateOne({ _id: new ObjectId(userId) }, [
    {
      $set: {
        role,
        allowedModels: { $ifNull: ["$allowedModels", null] },
        monthlyTokenBudget: { $ifNull: ["$monthlyTokenBudget", null] },
        status: { $ifNull: ["$status", "active"] },
        dailyMessageCount: {
          $ifNull: ["$dailyMessageCount", { count: 0, resetsAt }],
        },
      },
    },
  ]);

  return role;
}

One TypeScript detail in this layer was a bit of a pain. Augmenting the session type works through the next-auth module as you would expect, but the JWT type does not! It is only re-exported from next-auth/jwt and lives in @auth/core/jwt, so a declaration written against next-auth/jwt silently fails to merge, and the token field you were trying to type lands as unknown instead. You have to target the real module:

declare module "next-auth" {
  interface Session {
    user: {
      id: string;
      role: Role;
    } & DefaultSession["user"];
  }
}

// JWT lives in @auth/core/jwt; next-auth/jwt only re-exports it, so the
// augmentation must target the real module to merge rather than shadow.
declare module "@auth/core/jwt" {
  interface JWT {
    uid?: string;
    role?: Role;
  }
}

That silent failure is the worst kind: when there are no errors, the type just quietly goes wrong.

Connectivity: prove it reaches Atlas and Bedrock

The last piece of the skeleton is a single protected route that proves the app can talk to the things it depends on. Any signed-in role can call /api/health. It always pings Atlas, and given ?probe=bedrock it goes one step further and makes a one-token Converse call against Claude Haiku 4.5, to prove the credentials can invoke a real model. The probe is the interesting part: capped at a single output token, wrapped so no AWS internals leak back to the caller, and returning the counts read from the Converse usage metadata.

export async function bedrockHealthProbe(): Promise<BedrockHealth> {
  try {
    const llm = new ChatBedrockConverse({
      model: HAIKU_INFERENCE_PROFILE,
      region: env.AWS_REGION,
      credentials: {
        accessKeyId: env.AWS_ACCESS_KEY_ID,
        secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
      },
      maxTokens: 1,
      temperature: 0,
    });

    const response = await llm.invoke([["human", "ping"]]);

    const usage = response.usage_metadata as TokenUsage | undefined;

    return {
      ok: true,
      inputTokens: usage?.input_tokens ?? null,
      outputTokens: usage?.output_tokens ?? null,
    };
  } catch {
    // Do not surface the underlying AWS/SDK error to callers.
    return { ok: false, error: "Bedrock probe failed" };
  }
}

On a live run, it comes back with the result you want:

{"ok":true,"inputTokens":8,"outputTokens":1}

Eight tokens in, one token out. That is the signal you want from a health check on an AI app, not only that the network is up, but that the credentials work and the meter is running.

The models, the probe, and the rest of the app are seeded into settings as a catalog. Each entry carries a real Bedrock cross-region inference profile ID rather than a bare model ID, which is the correct choice for cross-region routing:

[
{"id":"haiku","inferenceProfileId":"us.anthropic.claude-haiku-4-5-20251001-v1:0"},
  {"id":"sonnet","inferenceProfileId":"us.anthropic.claude-sonnet-4-6"},
  {"id":"opus","inferenceProfileId":"us.anthropic.claude-opus-4-8"}
]

Each entry also carries per-million-token input and output pricing, which a later phase uses to enforce tier costs. For now, those fields are a deliberate placeholder, to be confirmed against current Bedrock pricing before any billing math depends on them, so I am not quoting numbers here that would only mislead.

Env: validate only what this phase uses

As we work through this series, each development phase validates only the environment variables it uses, rather than declaring the project's entire surface up front. So far, we need just eight, for the database, Google auth, Bedrock, and the admin bootstrap, so the env schema gates exactly those. A missing or malformed value throws at startup, naming the offending variable and never printing its value:

const EnvSchema = z.object({
  MONGODB_URI: z.string().url(),
  AUTH_SECRET: z.string().min(1),
  AUTH_GOOGLE_ID: z.string().min(1),
  AUTH_GOOGLE_SECRET: z.string().min(1),
  AWS_ACCESS_KEY_ID: z.string().min(1),
  AWS_SECRET_ACCESS_KEY: z.string().min(1),
  AWS_REGION: z.string().min(1),
  ADMIN_EMAIL: z.string().email(),
});

const parsed = EnvSchema.safeParse(process.env);
if (!parsed.success) {
  // List the offending variable names only, never their values.
  const offenders = parsed.error.issues
    .map((issue) => issue.path.join("."))
    .join(", ");
  throw new Error(
    `Invalid environment configuration. Check these variables: ${offenders}`,
  );
}
export const env = parsed.data;

Other variables that will be introduced later, like Tavily for web search, Voyage for embeddings, Blob for file storage, and LangSmith for tracing, are not here yet.

The gotchas that cost real time

The skeleton works, but it did not the first time, and the failures are perhaps the most useful part of this build report.

The first was the most painful: the connection string has no database path, so anything that does not explicitly name the database falls back to test, which the Atlas credentials cannot touch. It bit twice, first in the index script:

MongoServerError: not authorized on test to execute command { listCollections: 1, ... $db: "test" }

Then again, after deployment, in production sign-in, because the Auth.js adapter does not go through the app's database helper and quietly defaults to test until it is told otherwise:

[auth][error] AdapterError
[auth][cause]: MongoServerError: not authorized on test to execute command
{ find: "accounts", ... $db: "test" }

The fix is to name the database explicitly in both places. The adapter gets its own databaseName:

// databaseName is set explicitly because the connection string has no default
// database; without it the adapter would target "test" (which the Atlas
// credentials cannot access).
export const { handlers, auth, signIn, signOut } = NextAuth({
  adapter: MongoDBAdapter(clientPromise, { databaseName: DB_NAME }),
  ...authConfig,
});

And the app reaches the database through one helper that names it the same way. That helper is also where the second gotcha lives. A naive new MongoClient() per request would leak a connection pool on every serverless invocation and every dev hot reload, so the client is cached on globalThis as a single instance, and DB_NAME is a constant rather than an env var because the database name is neither secret nor environment-specific:

const globalForMongo = globalThis as unknown as {
  _claudiusMongoClientPromise?: Promise<MongoClient>;
};

const client = new MongoClient(env.MONGODB_URI);

export const clientPromise: Promise<MongoClient> =
  globalForMongo._claudiusMongoClientPromise ??
  (globalForMongo._claudiusMongoClientPromise = client.connect());

export const DB_NAME = "claudius";

export async function getDb(): Promise<Db> {
  const connected = await clientPromise;
  return connected.db(DB_NAME);
}

The adapter is handed the same clientPromise, so auth, and the app shares one client and one pool rather than opening two. Making them agree on a single driver version took one line at the repo root, since the adapter and the app can otherwise resolve different ones:

"overrides": { "mongodb": "7.3.0" }

The third is a monorepo trap. The shared package is consumed as raw TypeScript and transpiled by the app's build through transpilePackages: ["@claudius/shared"], with no separate build step. That is convenient, but it means every runtime dependency the shared code imports has to resolve from the app workspace, because Vercel scopes its install to the app's root directory. The rule that keeps the build green is to declare a runtime dependency in every workspace that imports it, even when that looks like duplication.

The last is the kind of thing that only shows up on deploy. A lockfile generated on macOS omitted the Linux binaries that Tailwind's build needs, and Vercel's Linux install could not find them:

Error: Cannot find module '../lightningcss.linux-x64-gnu.node'

Declaring those binaries as optionalDependencies puts them in the lockfile for every platform, and the deploy goes green:

"optionalDependencies": {
  "@tailwindcss/oxide-linux-x64-gnu": "4.3.1",
  "lightningcss-linux-x64-gnu": "1.32.0"
}

What stands, and what a headless build cannot prove

No chat yet, but the foundation is real. Identity resolves on the server and rides safely in the token. The health route confirms Claudius can reach both Atlas and Bedrock, and the configuration fails loud and early when something is missing. The data model from the last article now has something solid underneath it.

The role-resolution logic is unit-tested, but the actual sign-in is an OAuth round trip, and that needs a real browser, not just this headless build. Confirming that an admin email lands as admin on the page and on the persisted user document is the one step I finish by hand.

Next is the streaming chat backbone, where the conversation finally gets a place to live, and I open the real checkpoint document I have been promising since the start.

Finally! MongoDB Atlas supports partial restore

MongoDB Guests — Mon, 03 Aug 2026 09:00:00 +0000

This article was written by Darshan Jayarama.

Reflecting on my tenure as a MongoDB TSE, I recall a specific incident where a DBA mistakenly dropped a production collection instead of a UAT one. At the time, we were compelled to restore the total cluster to a secondary instance, isolate the required data, and then re-import it into the live environment. The process was inefficient and expensive. We had to recover an entire 760GB cluster just to retrieve a single 50MB collection. You can imagine the massive resource drain involved.

One might wonder why we couldn't restore a single collection or select databases. That’s the new feature I am going to share with you today.

What is partial restore?

As explained in the MongoDB documentation, you can now simply restore any database or collection from the cloud backup; there is no need to restore the full cluster.

It means that if one collection is all you want, you can recover it without touching the entire dataset from the cloud backup.

Real-World Example

A production cluster will have a combination of multiple databases:

Live Production Environment

├── Customer_Profiles
├── Transaction_History
├── Stock_Management
├── Billing_Records
└── Data_Insights

If someone accidentally drops Billing_Records.invoices collection. To resolve this:

Before the Partial Restore feature:

Restore the entire cluster to a temporary Atlas cluster.
Wait for the restore to complete.
Export the required collection.
Import it back into production.
Delete the temporary cluster.

With the Partial Restore feature,simply choose:

Backup Snapshot
Database
Collection
Restore

Here is the workflow:
Click on the Backup tab, select the cluster, and select the backup snapshot as shown below.

Click the 3 dots per the selected snapshot, then click Restore.

In the next window, select the Restore Databases/Collection tab:

You will now have 2 options:

Create as new: With this option, you can choose not to remove the existing collection. If the restoring collection/DB name already exists, Atlas automatically renames the restoring collection to avoid a conflict.
Overwrite existing: Atlas replaces the existing collection with the restored version.

If you want to compare the existing and restored collection, then choose the "Create as new" option. If you want to replace the existing collection, then choose the "Overwrite existing" option. But please be aware that all the data written after the snapshot time will no longer exist.

After choosing your option, you can go ahead and select exactly the data you need. You have two ways to do this:

Using the UI: Just tick the checkboxes for the database or collection you want. Or, if you prefer, you can use the search bar to find what you need using a regex pattern.
Using List Entry: Type the database name or the database. collection name, one per line. For example, if you want everything from the Billing_records database, but only the NRI and HNI collections from the Customer_profile database, you just enter it like this: Billing_records Customer_profile.NRI Customer_profile.HNI

Keep one thing in mind —you cannot use a dot in your database name. If you use a dot, the system will treat it as a combined DB and collection name.

Once you are done with this part, just click Next. On the next screen, you will need to select the Destination details.

What Is MongoDB Atlas Vector Search

MongoDB Guests — Tue, 28 Jul 2026 10:01:53 +0000

This article was written by Moses Anumadu.

Traditional search relies on keywords and tags to recommend search results. This system works and is in use across multiple platforms. However, it has a major limitation that has become more apparent in recent years due to increased AI adoption. The major limitation of traditional search is that it returns search results based solely on keyword matches. Traditional searches, as we have them today, do not consider semantic meaning. For example:

Imagine that we built a movie website using traditional search. Now, if a user wants to find The Matrix, but they can't remember the name. They type in "dystopian AI reality simulation." A traditional keyword database will return zero results because those exact words are not in the movie title or description. This is the major challenge for traditional search. It returns results strictly from keywords, in this case, either in the movie name or description. So, if a user does not type the exact keywords stored in your database, the correct or intended movie does not show up, even though it is in the database. The platform simply does not know that it was the intended movie. This can be limiting and produce search results that do not accurately match the users' intent.

A better approach for this use case is to have the search not rely on keywords to recommend movies. It should recommend movies based on semantic similarities. This is a very good example of when vector search should be used over traditional search.

In this tutorial, we will explore what vector search is, its importance, what MongoDB Vector Search is, and why you should consider it for your next vector search implementation. With that said, let's get started.

Prerequisites

To follow along with this article, you should have a basic understanding of the following concepts:

MongoDB Atlas
Database and collection
Can perform CRUD operations
Basic understanding of web development technologies

What Is Vector Search?

Vector search is a search technology that uses vectors to identify semantic similarity and recommend results that are accurate in terms of meaning and not keywords.

With vector search, text, images, and other media file types are stored as embeddings. Embeddings are numerical values generated by machine learning models that capture the context, intent, and semantic similarity of the stored data. Items with similar meanings have embeddings (numeric values) that are closer.

When a search is done, the vector search identifies similar values by comparing the closeness of the content embeddings. The closer the embeddings, the more similar the contents. This returns a more accurate search result that relies on meaning over a keyword search that relies on keywords.

The major difference to note here is that keyword searches rely on keyword matches to recommend results, while vector searches rely on meaning by comparing embeddings to recommend results.

Keyword Search vs. Vector Search

Keyword Search	Vector Search
Search relies on exact keyword matching to return results.	Search relies on a semantic understanding of search terms.
Results are not generated based on users' intentions. They rely on keyword accuracy.	Generates results with users' intent in consideration.
The use of synonyms in keyword searches does not often return the best search results. Eg, car and vehicle won't return the same result.	Synonyms in vector search generate far more accurate results. It factors in the actual meaning of the words to generate results.
Keyword search queries are not flexible to things like typos and long search queries.	Search keywords or phrases can be sentences. It can be flexible with misspelled words and still return accurate results.

How Embeddings Enable Vector Search

What Is an Embedding?

Think of embeddings as the foundation of vector searches. Embeddings are numerical values generated by artificial intelligence. These numeric values represent the meaning of text and media files, so vector search can compare them and return more accurate, similar results.

In a keyword search query, a traditional database does not treat words as symbols with meaning; it sees them as independent flat characters that don't have links to the sentence's meaning. So it only returns results that match exactly. An example can be a search keyword of "CAT" would return a CAT. Not because it understands it, but because the keywords match. But a search keyword of VEHICLE would not return a result of CAR.

How AI generates these similarities

Let's take a moment to examine how an AI embedding model generates the numbers in an embedding. Imagine you need to describe an apple using a scale of 1-10. Is an apple sweet? Yes. On a scale of 1 - 10, how sweet is an apple? Say 8. Is an apple crunchy? Yes. On a scale of 1 - 10, how crunchy is an apple? Say 6. Is an apple red in color? Yes. On a scale of 1 to 10, how red is an apple? Say 9. This would give us an embedding of [8, 6, 9]. A fruit like a banana can be [9, 1, 0].

The AI embedding model does something very similar to the example above; when it processes a sentence, it outputs a long list of numbers (called a vector). This list serves as a precise map coordinate for that specific piece of text in a giant, digital "map of meaning."
This results in words with similar meaning having vectors that are closely related or similar.

Why Embeddings Matter

Embeddings are like the building blocks of vectors. With them, vectors are generated, and similarity in terms of meaning can be measured in a search query.

How MongoDB Vector Search Works

The Vector Search Workflow

In a MongoDB vector search implementation, data is stored together with its generated vector in the same collection. This simplifies the implementation when compared to the steps required to implement this using different technologies. Let's examine the workflow for both storing a document and retrieving it during a search query.

Storing document

Storing record

This process starts with storing our normal documents in a MongoDB collection. A document can be in text or media format.

Embeddings are generated

After storing this document, embeddings are generated using any of the AI models that have this compatibility. Some popular examples are VoyageAI, OpenAI, Cohere, and Hugging Face.

Documents are updated to contain vectors.

The data collection in Atlas is updated to contain the generated vectors. This saves the vector as a field in the collection. Keeping both the data and its embeddings in one collection.

A vector search index is created

The final step in this flow is creating the vector search index. This boosts performance during searches.

The image below provides a visual explanation of the flow;

Search workflow

The MongoDB vector search workflow consists of a few steps; it starts with a user query. The query is converted into embeddings using an AI embedding model (for best results, use the same embedding model as the one used to embed the documents in the database is advised).

After the vectors are generated, MongoDB vector search calculates the semantic proximity between the search query vector and the vector of the documents stored in the collection. It then returns the results, which are semantically matching items to the user search query. The image below provides a more visual explanation of the process.

Common Use Cases

There is no doubt about the importance of vector searches. However, this does not make it the right tool for every search implementation. Vector search implementations require AI models to generate vectors. This can make the search implementation a bit more complex and costly. With that in mind, it is important to explore some real-world use cases where it can be a good fit and also where it is not. But in general, vector searches are a great solution for search results that want semantic similarity. Some examples include:

Semantic document search
AI knowledge bases
Product recommendation systems
Similar content discovery
FAQ search
AI assistants using business data

Benefits and Considerations

Benefits

Some of the key benefits include:

More relevant search results

Using vectors to measure similarity enables vector searches to return more relevant results. Unlike keyword searches, vector search can provide relevant results even if the search query contains misspelled or slang words.

Better user experience

Vector search implementation can improve the user experience. Vector search is less rigid; it provides some flexibility for users when typing their search. This improves the users' experience of the application.

Natural language querying

Vector search implementation allows users to type search queries in natural language, rather than having to target keywords, often explaining the expected result rather than targeting the keywords.

Native integration within MongoDB

Vector Search is part of the core features of MongoDB. This means that it is already integrated with your database and collections. If you have an already existing collection in MongoDB, you can easily use your existing data to implement vector searching.

Reduced need for a dedicated vector database

With MongoDB, you do not need a separate vector database. Data can be stored alongside its vector embeddings in the MongoDB collection.

Considerations

While vector search can provide more accurate results, it is worth noting that it is not a complete replacement for traditional searches. The following key points are worth noting before deciding to implement a vector search in an application:

The need for embedding models:

Vector search implementation requires the use of AI models to generate embeddings. These models can be expensive and provide an additional configuration layer.

Additional storage requirements for vectors

Vectors can be large in size. The vector for a sentence can have up to 8,192 dimensions. Imagine when you have a hundred blog posts. This can take up a huge amount of space and can lead to higher cloud bills.

Choosing an appropriate embedding model

There are several embedding models that are great for different industries. Choosing the right model for your particular use case is a factor that should be considered. For example, a model that was designed for the fashion industry might not give the best result for a model optimized for medical research.

When keyword search may still be the better choice

Vector search is not a complete replacement for keyword search. Keyword search can still be more effective for exact match searches. An example can be searching for an exact serial number, username, or any other situation that returns an exact keyword result.

When Should You Use MongoDB Vector Search?

A vector search implementation that does not use MongoDB requires data, which can be in the form of text, images, or audio, to be stored in a traditional database; the generated vector for the items will be stored in a different dedicated vector database. This results in repetition because two databases are used, increasing the complexity of keeping the two databases in sync and fragmenting data (text and vectors).

MongoDB vector search bridges that gap. It lets data and their generated vectors be stored in the same collection.

Another major advantage that MongoDB vector search brings is that it keeps data in sync. A very common issue with vector search integrations where one database is used for data and another for storing vectors is that the data is often not in sync. If a record is deleted from the regular database and the vector is not, search results can be recommended that are no longer available in the database. MongoDB vector search stores the record and keeps it in sync. If a record is deleted from its collection, its vector is deleted as well, keeping both the record and its vector in sync.

MongoDB vector search eliminates the need for new infrastructure by storing both records and vectors in the same collection.

Conclusion

In this article, we explored what vector search is, how it works, how AI comes into the picture, and what differentiates it from traditional keyword search. We also took it a step further and explored how MongoDB vector search works and what advantages it has over other vector databases.

By the end of this article, you should have a basic understanding of how:

Vector search retrieves information based on meaning rather than exact keywords.
Embeddings make semantic search possible.
MongoDB provides native vector search capabilities that integrate with your existing data.
Understanding these fundamentals is the first step toward building intelligent search experiences.

For a deeper dive on how to implement vector search with MongoDB, you can check out the MongoDB documentation here. If you prefer a step-by-step tutorial, check out this tutorial here.

Now you have the basics; go build something great. Cheers.

A Proven Application Layer for MongoDB

MongoDB Guests — Mon, 27 Jul 2026 11:48:12 +0000

The successful alternative I used before Atlas Device SDKs. This Article was written by Raschid Jimenez.

Atlas Device SDKs reached end-of-life in September 2025, and it’s easy to understand why so many MongoDB developers liked them: direct client access, authentication, sync, and security, all tied closely to MongoDB Atlas.

Long before Atlas Device SDKs, I had already found a different way to get many of those same benefits. Using Parse Server and Back4app, I built production apps for years without the burden of maintaining custom API layers across every client and language. This article is the recipe I wish more MongoDB developers knew: why this stack works, what it gives you, and why it’s such a strong fit on top of MongoDB.

I will walk you through three things that sold me on Parse Server and Back4app: native client SDKs across every platform, row-level security for multi-tenant apps, and managed schema with index control. Along the way, I'll cover what else comes in the package: authentication, real-time updates via LiveQuery, file storage, auto-generated GraphQL APIs, and offline support. Data never leaves MongoDB Atlas. Back4app is a gateway that translates client requests into operations against your cluster.

            ┌──────────────────────────────────────┐
            │  Client (SDKs / REST / GraphQL)      │
            └────────────────────┬─────────────────┘
                                 │
            ┌────────────────────▼─────────────────┐
            │     Application Layer                │
            │       (Back4app - Stateless Gateway) │ 
            └────────────────────┬─────────────────┘
                                 │
            ┌────────────────────▼─────────────────┐
            │     MongoDB Atlas (your cluster)     │
            └──────────────────────────────────────┘

Back4app Uses MongoDB Atlas as the Datastore

Back4app is a managed backend-as-a-service (BaaS) platform. Sign up, paste in your MongoDB connection string, and you get an application backend running in front of your cluster: APIs, SDKs, authentication, real-time sync, file storage, access control, and a dashboard. No provisioning servers, no configuring authorization, no maintaining the layer yourself.

The connection model is what should land for an Atlas audience: bring your own cluster. Back4app connects to an existing Atlas deployment via a standard MongoDB connection string. No migration, no copy of your data, no proprietary storage format, no lock-in at the storage tier. If you walked away from Back4app tomorrow, your Atlas cluster would still be there, untouched, with every native MongoDB primitive intact.

What Back4app adds is the application backend layer most teams end up building anyway: auto-generated REST and GraphQL APIs, authentication, real-time sync, file storage, ACLs and CLPs, and a visual data browser.

Back4app is a layer in front of Atlas, not a replacement for it.

Parse Server Under the Hood

Under the hood, Back4app runs Parse Server, an open-source backend framework with a mature SDK ecosystem across every major platform. That's where the Parse.Object, Parse.Query, Parse.ACL, and Parse.Schema APIs in the code samples throughout this article come from. They're Parse Server primitives. Back4app is the managed platform that runs Parse Server in production (like Atlas does for MongoDB), plus the pieces around it: hosted infrastructure, the connection-string flow into Atlas, the dashboard, the spreadsheet-like data browser, role-aware visual schema editing, monitoring, scaling, and backups.

The short version: code I write with a Parse.* prefix is Parse Server. The surfaces I interact with through the Back4app dashboard are Back4app.

Client SDKs Across Every Platform

With Atlas Device SDKs gone, the question for most teams is concrete: how do clients perform operations against MongoDB Atlas (CRUD, authentication, file uploads, real-time subscriptions, and access-controlled queries with relations) without building and maintaining a custom REST layer for each?

Back4app offers a set of native SDKs that talk to the gateway, which in turn talks to your Atlas cluster. Supported platforms:

iOS (Swift, Objective-C)
Android (Java, Kotlin)
Web (JavaScript, TypeScript)
React Native, Node.js
Flutter, Dart
PHP, .NET, C#
Edge runtimes

For anything not on that list, Back4app auto-generates REST and GraphQL endpoints from the same schema.

The interesting part isn't the language list. It's that the API shape is the same across all of them. Here are the four CRUD operations in JavaScript:

// CREATE - no REST endpoint, no schema migration, just save.
const order = new Parse.Object("Order");
order.set("total", 149.99);
await order.save();

// READ - ACLs are enforced server side; this user only sees their tenant's orders.
const query = new Parse.Query("Order");
query.greaterThan("total", 100);
query.include("customer"); // hydrate the pointer in one round trip
const orders = await query.find();

// UPDATE - same object, just mutate and save.
order.set("status", "shipped");
await order.save();

// DELETE - single call, ACL-checked at the data layer.
await order.destroy();

That include("customer") line is worth looking at. On raw MongoDB, resolving a reference to fetch the related document means writing an aggregation pipeline:

// Without Parse - manual aggregation pipeline:
db.orders.aggregate([
  { $match: { total: { $gt: 100 } } },
  { $lookup: {
      from: "users",
      localField: "customer",
      foreignField: "_id",
      as: "customer"
  }},
  { $unwind: "$customer" }
]);

// With Parse - one line:
await new Parse.Query("Order")
  .greaterThan("total", 100)
  .include("customer")
  .find();

Same result, one round trip, no pipeline to maintain. The include works identically across REST, GraphQL, and every SDK.

The same read in Swift, using the modern Parse-Swift SDK:

let query = Order.query("total" > 100)
  .include("customer")
let orders = try await query.find()

A note on API symmetry: query.include("customer") reads the same in JavaScript and Swift. The naming follows each language's conventions, but the mental model is identical across platforms. Same query model, same ACL enforcement, same relational include semantics. A team shipping iOS, Android, and web doesn't re-architect the data layer per client. They translate one mental model into three idioms.

If GraphQL is the API you want, the same schema produces a typed GraphQL endpoint automatically. No resolvers to write, and the same ACLs and CLPs that govern the SDKs govern those queries too.

For reactive UIs, LiveQuery lets you subscribe to any query and receive push updates on create, update, and delete over WebSockets. No polling loops, no reconnection logic, no homegrown change-stream plumbing. Subscribe to a dashboard to live order updates, and the dashboard updates itself when an order changes upstream.

Row-Level Security and Multi-Tenancy

Multi-tenant access control is application-layer work by design: the database holds the data, the application decides who sees what. In practice, that means every team building multi-tenant SaaS on Atlas writes the same middleware: tenant filters injected into every query, role checks scattered across controllers, field redaction in serializers. That creates a lot of security-critical logic to maintain.

Back4app moves that enforcement down to the data layer. Four layers of access control work together:

Layer	Granularity	When to use
Application Keys	Per client type	Separate public, client, and master contexts
Class-Level Permissions	Per class (collection)	"Who can create or read Orders at all"
Access Control Lists	Per document	"Who can read this Order"
Protected / Field-level	Per field	isAdmin: only the server can write

Here's what each layer replaces in a hand-rolled implementation:

// Without Parse — middleware you write and never get to delete:
app.get("/api/invoices", auth, async (req, res) => {
  const invoices = await db.collection("invoices").find({
    tenantId: req.user.tenantId,        // remember this on every endpoint
    $or: [
      { ownerId: req.user._id },
      { sharedWith: req.user._id }
    ]
  }).toArray();
  // ...strip fields the role shouldn't see...
  res.json(invoices);
});

// With Parse — write zero filter middleware:
const invoices = await new Parse.Query("Invoice").find();
// ACLs and CLPs enforce the same rules across REST, GraphQL, and every SDK.

Here's how you set those ACLs up for a multi-tenant invoice scoped to a tenant role:

const invoice = new Parse.Object("Invoice");
invoice.set("amount", 1200);

const acl = new Parse.ACL();
acl.setRoleReadAccess("tenant_acme", true);          // every user in this tenant
acl.setRoleWriteAccess("tenant_acme_admins", true);  // only admins can modify
invoice.setACL(acl);

await invoice.save();

Any query from a user outside tenant_acme will not see this document. Enforcement happens server-side at the gateway, not in hopeful client code. The same filter applies whether the request comes from the iOS SDK, the GraphQL endpoint, or an inbound webhook. There is no client-side path that can bypass it.

When per-object rules aren't expressive enough ("users can update their own row, but only during business hours, and only if the invoice isn't locked"), Cloud Code provides server-side functions for custom validation:

// Cloud Code — server side function, runs in Parse Server, ACL-aware.
Parse.Cloud.beforeSave("Invoice", async (req) => {
  if (req.object.get("locked") && !req.master) {
    throw "Locked invoices cannot be modified";
  }
});

Schema and Index Management

With Parse, the schema lives in the database itself. Every client SDK, REST endpoint, and GraphQL type derives from there automatically. One source of truth, propagated to every surface your app talks to.

Parse's ODM defines classes (collections) with typed fields: strings, numbers, dates, files, GeoPoints, pointers, and relations. Parse enforces types at the gateway across REST, GraphQL, and every SDK, so a malformed payload is rejected before it reaches Atlas. The underlying MongoDB collection and the indexes Parse needs are auto-created. Schema changes are tracked through the Parse schema API or the Back4app dashboard, and they propagate to every client without anyone regenerating models by hand.

Document stores don't usually feel relational, but Back4app adds pointers for one-to-one references and relations for many-to-many associations, with include queries that hydrate them in a single round trip:

const query = new Parse.Query("Order");
query.include("customer");   // hydrates the pointer
query.include("products");   // hydrates the relation
const orders = await query.find();
// One round trip. No manual $lookup pipeline.

When you want schemas in version control rather than clicked into a dashboard, schemas can be declared programmatically, and migrations become regular code:

const schema = new Parse.Schema("Invoice");
schema
  .addString("customerEmail")
  .addNumber("amount")
  .addPointer("tenant", "Tenant")
  .addIndex("by_email", { customerEmail: 1 }); // explicit MongoDB index
await schema.save();

Parse exposes MongoDB indexes directly. It creates defaults for ACL fields and pointers, but your hand-tuned indexes stay untouched. Parse only adds the ones it needs for ACL filtering and pointer fields. Your existing indexes for aggregation pipelines, Atlas Search, or hand-tuned queries stay exactly as you set them. The addIndex() call above creates a real MongoDB index. Parse doesn't abstract that away.

If you picked MongoDB for schemaless flexibility: Parse classes can stay flexible (allowAddField: true) during prototyping and tighten as the data model stabilizes. You pick per class. Strict where it matters, flexible where it helps.

Conclusion & Next Steps

Back4app is a stateless gateway in front of your existing MongoDB Atlas cluster. Connect it with a standard MongoDB connection string, and you get the dashboard, the spreadsheet-like data browser, SDKs across every major platform, auto-generated REST and GraphQL endpoints, LiveQuery for real-time UIs, and row-level security via CLPs and ACLs. Native MongoDB primitives (aggregations, transactions, indexes, Atlas Search) remain entirely available to you.

So my advice to you is: go to Back4App and sign up for free, create an app in your preferred language, and run your first operation on your data in under 10 minutes. Back4App offers a free tier (25,000 API requests per month), which is enough to try on a real app rather than a toy. My customers loved having their app backends hosted for free and paying only when they scaled.

Build Your AI-Powered Reading List Using DigitalOcean Functions, Mistral AI, and MongoDB

MongoDB Guests — Wed, 22 Jul 2026 10:24:29 +0000

This Tutorial was written by Diego Freniche.

Since I started browsing the Internet, I've used many different services, applications, and browser plugins (even the good old bookmarks) to mark articles and posts that seemed interesting and that I wanted to read. Only not now. I'll read them later, I promise. And then you hoard a bunch of links in one place. But when you go back to actually read them, you find yourself clicking again on them just to remember what those links where about and why did you store them in the first place...

Fast forward today, and I haven't changed much in how I interact with articles I want to read later. But nowadays we can use LLMs almost for free... and they are really good at writing text summaries. So, why not create a system that, given a link, generates a summary and then stores both the link and the summary in a fast database I can use to build my own UI later?

And this is now yet another read-it-later (maybe) system was born...

Prerequisites

Before you begin this guide, you'll need the following:

a DigitalOcean account, that we'll use to write a DigitalOcean Function. This function will receive our links and run the code that will generate the LLM-powered summary and store the results in a database.
a MongoDB database, also running in DigitalOcean. We will use it to store the links and summaries of the web pages. You can learn more about deploying a managed MongoDB instance in DigitalOcean here.
access to any LLM that can write a good summary. For this example, I'll use Mistral AI, so you'll need to register a free account there and get an API token. Take a note of that API key, we'll need it later!

Step 1 - Creating an Empty DigitalOcean Function

Let's start by creating the backbone of our system. We can write a backend app using Node, Spring Boot or any other web framework. But then we need to host it in a server, write the code, correctly size the server, update the operating system and dependencies, etc. Using a serverless function we focus on the task at hand. In this case, getting a URL via a parameter, producing a summary of the page, and storing the data in the database.

So head over to Functions and click on create > Functions. First, we need to choose where our serverless function will be hosted. Although it's a serverless function, our code will need a real server to run. Only we don't have to provide it. Choose a data center close to your location (or close to where the users of your function will be). Then give it a name, choosing a label. In my case, it will be read-it-later-i-pinly-promise.

After creating the namespace, you'll be in the Overview tab. Let's add some basic code to test our function! Just click on the Create Function button.

We need to select one of the supported runtimes (in our case, Nodejs 18), and we'll give the function a name: read_later. It's important to leave the Web Function box checked, as we want to call this function directly using HTTP.

Done! Now you should see the default source code of the newly created function. This just gets an argument name from the URL and returns it. As we're not configuring a web page or a JSON response, this will be printed out as plain text by our web browser.

function main(args) {
let name = args.name || 'stranger' let greeting = 'Hello ' + name + '!' console.log(greeting)
return {"body": greeting}
}

In the main function, we receive a JSON object with all the arguments passed in the function call, we search for name, and use it. If not found, we use stranger as name. Then we compose and print out a greeting which we also return from our function.

Step 2 - testing our function

As this is accessible via HTTP calls, we have several different options to test our function.

Using cURL

If your system includes curl (Microsoft Windows 10/11 and most UNIX systems, like Linux and macOS come with cURL preinstalled), you can copy the URL of your function and add the name parameter at the end. Then call curl with:

curl https://<redacted>.doserverless.co/api/v1/web/<redacted>/default/read_later? name=Diego

In your case, instead of <redacted>, you'll see the ids of your functions. If you call the function from a Terminal, you'll see the response from our function:

curl https://<redacted>.doserverless.co/api/v1/web/<redacted>/default/read_later? name=Diego
Hello Diego!%

Try it changing the name and the code in your function and experiment with it! It's super fun!

Testing directly in DigitalOcean

We can click on Test Parameters and add a JSON with our test data, in this case:

{ "name": "Diego" }

Then, we can hit the Run button and see the results in the Output and Logs windows.

Step 3 - Adding the LLM Code

First, we will change our variable names to reflect what we're doing: producing summaries from links. Instead of name we'll use a link variable. Also, we'll return a proper HTTP response, with
statusCode 200 in case we got a link.

export async function main(args) { const link = args.link;
if (!link) { return {
statusCode: 400,
headers: { "Content-Type": "application/json" }, body: { error: "Please send a link" }
};
}
const body = { URL: link }; return {
statusCode: 200,
headers: { "Content-Type": "application/json" }, body: body
};
}

After changing the code, hit the "Save" button to avoid losing your changes. You can now re-run your function and check the results.

While we're at it, let's also change the Test Parameters (if you're testing directly from the browser) to:

(
"link": "https://en.wikipedia.org/wiki/Seville"
)

Seems like we're about to travel to Seville!

After that, we'll add the code to interact with Mistral. We need to send a POST with the prompt to their endpoint. For this, we'll need an API key from Mistral AI (see prerequisites). Save the code, but don't run the function (yet) as we need to add the secret.

const API_KEY = process.env.MISTRAL_API_KEY; // secrets are stored in the function's Settings
const API_URL = 'https://api.mistral.ai/v1/chat/completions';

async function chatWithLeChat(prompt) { try {
// call the Mistral endpoint with POST const res = await fetch(API_URL, {
method: 'POST', headers: {
'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json',
},
body: JSON.stringify({ model: 'mistral-tiny',
messages: [{ role: 'user', content: prompt }],
}),
});

const data = await res.json(); console.log(res.status, data);
return data?.choices?.[0]?.message?.content || null;
} catch (error) {
console.error('Error:', error?.message || error); return null;
}

Step 4 - Adding Secrets

As you can see, in our code, we don't embed the secrets (like API keys). Instead, we use the Functions environment to provide these:

const API_KEY = process.env.MISTRAL_API_KEY;

To add this secret MISTRAL_API_KEY we click on Settings. Then, we scroll down to Environment Variables. There, we can click on Edit

Now, click on Add and then Save. You should see your new environment variable now!

Step 5 - getting the LLM summary

It's time to call our chatWithLeChat function from main! To do that, we 1st create a system prompt that includes the link we received and instructs the LLM on what to do. Then, we'll call Mistral:

const prompt = 'I need a summary of this page: ' + link;

const summary = await chatWithLeChat(prompt);

We will extend our body to include the summary:

const body = { URL: link , summary: summary
};

This is all our code right now:

export async function main(args) { const link = args.link;
if (!link) { return {
statusCode: 400,
headers: { "Content-Type": "application/json" }, body: { error: "Please send a link" }
};
}

const prompt = 'I need a summary of this page: ' + link; const summary = await chatWithLeChat(prompt);
const body = { URL: link , summary: summary
};

return { statusCode: 200,
headers: { "Content-Type": "application/json" }, body: body
};
}

const API_KEY = process.env.MISTRAL_API_KEY; // secrets are stored in the function's Settings
const API_URL = 'https://api.mistral.ai/v1/chat/completions';

async function chatWithLeChat(prompt) { try {
// call the Mistral endpoint with POST const res = await fetch(API_URL, {
method: 'POST', headers: {
'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json',
},
body: JSON.stringify({ model: 'mistral-tiny',
messages: [{ role: 'user', content: prompt }],
}),
});

const data = await res.json(); console.log(res.status, data);
return data?.choices?.[0]?.message?.content || null;
} catch (error) {
console.error('Error:', error?.message || error); return null;
}

If you save your function and run it, most probably you'll get an error message in LOGS:

2026-02-02T12:14:17.299547912Z stderr: The function exceeded its time limits of 3000 milliseconds. Logs might be missing.

We need to give our function more time to wait for the LLM to answer!

Setting Timeouts

Head to Settings again, and click Edit on Limits. By default you have 3 secs (3000 milliseconds) to run your function before you get a timeout. We'll set that to 10 secs. Save the change, go back to Source and run the function again.

After that change, you should get a summary of the page!

Persisting data into MongoDB

We're now ready to store our body object in a MongoDB collection. One of the nicest things about MongoDB is that you work with your application objects in memory, and when ready, you send them to MongoDB using the driver (a library that will interact directly with the database). No need for ORMs or complicated frameworks in this case.

We'll start by importing the MongoDB driver:

import { MongoClient } from "mongodb";

After that, we'll write a simple function that will:

receive our object as an argument, named page.
connect to MongoDB using a MongoClient instance and the connect method.
write it into MongoDB using insertOne

async function store_in_mongodb(page) {
const mongodb_URI = process.env.MONGODB_URI; // get the MongoDB URI from an environment variable

const client = new MongoClient(mongodb_URI); try {
// connect to MongoDB await client.connect();
const database = client.db('read_it_later'); const collection = database.collection('pages');

const result = await collection.insertOne(page); return result;
} finally {
await client.close();
}
};

As we did previously with our environment variable MISTRAL_API_KEY, we'll need to add a new environment variable in Settings called MONGODB_URI with the URI of our MongoDB installation. The URI looks like this:

mongodb+srv://user:password@cluster.something-here.mongodb.net/

The last step will be to call this new function in main:

await store_in_mongodb(greeting);

Once this is done, save your function and send some links to your function and see how the collection pages gets populated!

Conclusion

In this article we've explored how to write a serverless function that can interact with an LLM and store results in MongoDB. It's incredible how far a few lines of code can take us these days. Not so long ago you needed to spend days setting up web and database servers, hosting everything, exposing it to the Internet, writing your code, etc. Now, using DigitalOcean integrated suit of services and hosted applications you focus on what matters most: your application code. Our next step could be building a new function to read from MongoDB, that will be the base for our UI, or add Semantic Search using MongoDB's Vector Search capabilities.

Here you have the complete code listing for our function:

export async function main(args) { const link = args.link;
if (!link) { return {
statusCode: 400,
headers: { "Content-Type": "application/json" }, body: { error: "Please send a link" }
};
}

const prompt = 'I need a summary of this page: ' + link; const summary = await chatWithLeChat(prompt);
const body = { URL: link , summary: summary
};

await store_in_mongodb(body);

return { statusCode: 200,
headers: { "Content-Type": "application/json" }, body: body
};
}

const API_KEY = process.env.MISTRAL_API_KEY; // secrets are stored in the function's Settings
const API_URL = 'https://api.mistral.ai/v1/chat/completions';

async function chatWithLeChat(prompt) { try {
// call the Mistral endpoint with POST const res = await fetch(API_URL, {
method: 'POST', headers: {
'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json',
},
body: JSON.stringify({ model: 'mistral-tiny',
messages: [{ role: 'user', content: prompt }],
}),
});

const data = await res.json(); console.log(res.status, data);
return data?.choices?.[0]?.message?.content || null;
} catch (error) {
console.error('Error:', error?.message || error); return null;
}
}
import { MongoClient } from "mongodb"; async function store_in_mongodb(page) {
const mongodb_URI = process.env.MONGODB_URI; // get the MongoDB URI from an environment variable

const client = new MongoClient(mongodb_URI); try {
// connect to MongoDB await client.connect();
const database = client.db('read_it_later'); const collection = database.collection('pages');

const result = await collection.insertOne(page); return result;
} finally {
await client.close();
}
};

No messages table! The data model behind my own Claude-based chatbot

MongoDB Guests — Thu, 02 Jul 2026 15:47:31 +0000

This tutorial was written by Néstor Daza.

This is the second article in a series about building Claudius, my own Claude-based chatbot (Github). The prologue made the case for building it, and for choosing MongoDB as its foundation.

Open the conversations collection in Claudius’ database and you find the usual fields of a thread header but nothing else: a userId, a title, some timestamps, and so on, but no array of messages, no messages collection sitting beside it either! The text of every conversation lives somewhere else entirely, in the LangGraph checkpointer, which I wire up later in this series. This absence is a modeling decision, and how I came up with the database schema for my chatbot is the theme of this article.

If you come from a relational background, you're used to modeling the data first when designing a database. For a project like this, you would start by finding the entities and normalizing them, and the final schema would come out of the data's structure: a conversations table and a messages table with a foreign key between them, because that is what the data looks like.

Document modeling runs the other way. You start from how the application reads and writes, and the shape of the document follows the access patterns. Claudius never reads conversation messages without the agent's full working state wrapped around them, and that state is persisted using the LangGraph checkpointer. A separate messages table would add nothing, since the app would always have to join it back to that state on every read. The access pattern says the messages belong with the agent state, so that is where they go, and conversations are left as the lightweight header the list view actually needs.

That inversion, modeling around use rather than around the data, runs through everything below.

Schema-flexible is not schemaless

This is the misconception lots of people often carry, and it is worth killing on the way in. A document database does not mean no schema; it means a flexible, use-case-based data model. A relational engine holds the schema for you through column types and constraints; MongoDB will store documents in whatever shape your application gives it, and can validate that shape with a collection validator if you want. Claudius keeps the schema in code, as one Zod schema per collection, because that single definition gives both the runtime check and the TypeScript type.

import { z } from "zod";
import { zObjectId } from "./common";

export const ConversationSchema = z.object({
  _id: zObjectId.optional(),
  userId: zObjectId,
  title: z.string(),
  modelId: z.string(),
  createdAt: z.date(),
  updatedAt: z.date(),
  archived: z.boolean(),
  expiresAt: z.date().optional(),
});

export type Conversation = z.infer<typeof ConversationSchema>;

The reason is drift. Declare a TypeScript interface for a document and a separate validator for the data coming in, and the two will disagree eventually, while the type system will lie to you with complete confidence. Deriving the type from the validator collapses them into one artifact. One definition gives you the runtime check at the boundary and the compile-time type everywhere else. For a relational reader, this is your DDL (Data Definition Language) and your ORM (Object-Relational Mapping) models together in the same structure, which is something relational stacks rarely pull off.

Another advantage is that every external input, whether an incoming HTTP body or a model's structured output, is parsed through Zod at the boundary, so by the time data reaches the logic, it is already validated and typed.

A quick tour of the model

There are eight collections in this phase: users, conversations, memories, documents, chunks, usage_events, settings, and, arriving later, jobs. Two more, checkpoints and checkpoint_writes, belong entirely to the checkpointer and are never written to directly, so I do not model them. Most of these schemas are unremarkable once you see the access-pattern framing, but two modeling moves are worth pausing on.

The first is settings. It holds a handful of global singletons, each a different shape, each identified by a string _id: the member allowlist, the model catalog, the per-role tiers, and the guest spend circuit breaker. They share one collection, so the Zod schema is a discriminated union based on _id, and parsing a settings document narrows it to the correct shape from its _id literal.

export const SettingsSchema = z.discriminatedUnion("_id", [
  AllowlistSettingsSchema,        // _id: "allowlist"
  ModelCatalogSettingsSchema,     // _id: "modelCatalog"
  TiersSettingsSchema,            // _id: "tiers"
  GuestCircuitBreakerSettingsSchema, // _id: "guestCircuitBreaker"
]);
export type Settings = z.infer<typeof SettingsSchema>;

In relational terms, this is a single typed configuration table whose rows legitimately carry different columns, which is usually awkward to model relationally without resorting to a JSON column, and here comes out clean and readable.

The second move is to use document embedding as a data modeling technique. The users document carries its dailyMessageCount as an embedded object holding the count and its reset time together, rather than as two flat fields or a side table, because the application always reads and writes them together as a unit. That is the document modeling mantra: data used together is stored together.

Let the database keep the rule

The most satisfying part of this phase is how little policy I had to write. Three product rules that I would normally enforce in application code are carried by the storage engine instead, because I shaped the data so the engine could hold them.

Retention is a TTL index

Guest data in Claudius is ephemeral. Guest-created conversations and memories carry an expiresAt date; member and admin documents leave the field off entirely. A TTL (time-to-live) index with expireAfterSeconds set to 0 tells MongoDB to delete each document at the exact moment stored in its own expiresAt field; documents without this field are never touched.

// TTL on the guest-only expiresAt field. expireAfterSeconds:0 
// means "expire exactly at the date stored in the field"; 
// documents without the field are never touched, so member/admin
// data is permanent.

await db
  .collection(COLLECTIONS.conversations)
  .createIndex({ expiresAt: 1 }, { name: "expiresAt_ttl", expireAfterSeconds: 0 });

await db
  .collection(COLLECTIONS.memories)
  .createIndex({ expiresAt: 1 }, { name: "expiresAt_ttl", expireAfterSeconds: 0 });

So, guest ephemerality, a product rule, is enforced by the engine. There is no cron job and no cleanup endpoint to remember to run. The relational equivalent is a scheduled sweep; here, the policy lives in the index.

One detail ties the TypeScript compiler to the database behavior. With exactOptionalPropertyTypes turned on in tsconfig.json, an optional field means the key is absent, not present, and set to undefined. The compiler setting and the storage rule reinforce each other.

Telemetry is a time-series collection

Every billable model call writes one usage_events document, recording the token counts, the latency, and what the call was for. That data is append-only and gets queried along a few low-cardinality dimensions over a time window, which is the textbook shape for a MongoDB time-series collection. It has a timeField, timestamp, and a single metaField that holds the grouping dimensions (userId, modelId, purpose) nested alongside the measurements.

Two things follow from this choice. A time-series collection has to be created explicitly with a timeseries spec before the first insert (they cannot be created on first write, the way an ordinary collection does), so the index script creates it behind an existence check. Once it exists, the engine's own machinery becomes visible: list the collections and a system.buckets.usage_events sits next to usage_events, which is where the bucketed storage lives:

[
  {"name":"memories","type":"collection"},
  {"name":"usage_events","type":"timeseries"},
  {"name":"system.buckets.usage_events","type":"collection"},
  {"name":"settings","type":"collection"},
  {"name":"users","type":"collection"},
  {"name":"conversations","type":"collection"},
  {"name":"accounts","type":"collection"},
  {"name":"chunks","type":"collection"},
  {"name":"system.views","type":"collection"}
]

The relational analogy is a metrics or rollup table you would otherwise hand-roll and maintain, except the bucketing is automatic and the query you write against it stays simple.

A pre-filter field is a security control

The project's hardest rule is that a vector search pre-filters by userId and can never return another user's data. That rule is not bolted onto the search in the application code. It is a property of the index.

Both memories and chunks get an Atlas Vector Search index on the embedding field, with a filter on userId (and on chunks, a second filter on documentId).

await ensureVectorIndex(db, COLLECTIONS.memories, "memories_vector", [
  { type: "vector", path: "embedding", numDimensions: 1024, similarity: "cosine" },
  { type: "filter", path: "userId" },
], created, skipped);

await ensureVectorIndex(db, COLLECTIONS.chunks, "chunks_vector", [
  { type: "vector", path: "embedding", numDimensions: 1024, similarity: "cosine" },
  { type: "filter", path: "userId" },
  { type: "filter", path: "documentId" },
], created, skipped);

Pre-filtering means the userId condition is applied during the indexed search on the same documents being scored, not afterward to whatever the search returns. Post-filtering is not only slower, since you score documents you then throw away, but it is a correctness and security risk, since the wrong documents can slip through ranking and limits before your filter ever runs.

This is also why chunks denormalizes userId. A vector search has no notion of a join, so the filter has to sit on the very documents being searched. A chunk belongs to a document that belongs to a user, but the chunk has to carry the owner itself, or the index cannot enforce the boundary. That is the embed-versus-reference tension made concrete: a chunk references its parent document by id and duplicates the one field the security boundary depends on.

Two gotchas surfaced while creating these indexes, and both are worth saying out loud. A search index can only be built on a collection that already exists, and chunks had no classic index, so the collection did not exist yet the first time the script reached for its vector index:

MongoServerError: Error retrieving collection UUID and view info ::
caused by :: Collection 'claudius.chunks' does not exist. (NamespaceNotFound)

The fix is to add an existence check and create the collection first only if it is missing. The second gotcha is that Atlas builds search indexes asynchronously, so createSearchIndex returns when the build is queued, not when it is queryable! We also need a name check that keeps reruns safe while it builds.

This is the final function to build the indexes from code using the driver's createSearchIndex, with the checks that keep the script safe to run on every deploy:

async function ensureVectorIndex(
  db: Db,
  collectionName: string,
  indexName: string,
  fields: Array<Record<string, unknown>>,
  created: string[],
  skipped: string[],
): Promise<void> {
  // A vector search index can only be built on an existing
  // collection, so create it first if nothing else has (e.g.
  // chunks has no regular index).
  const collections = await db
    .listCollections({ name: collectionName })
    .toArray();
  if (collections.length === 0) {
    await db.createCollection(collectionName);
  }

  const collection = db.collection(collectionName);
  const present = await collection.listSearchIndexes().toArray();
  if (present.some((idx) => idx.name === indexName)) {
    skipped.push(`${collectionName}.${indexName}`);
    return;
  }

  // Atlas builds the index asynchronously; createSearchIndex
  // returns once the build is queued. The name check above 
  // keeps re-runs idempotent.
  await collection.createSearchIndex({
    name: indexName,
    type: "vectorSearch",
    definition: { fields },
  });
  created.push(`${collectionName}.${indexName} (vector)`);
}

The plumbing that keeps the code honest

Two small things hold the userId rule together in practice. First, userId is an ObjectId everywhere, matching the user’s _id, so filters and lookups line up without conversion. Second, no collection is ever queried through a raw driver call. Every access goes through a typed accessor, conversationsCol(), memoriesCol(), and so on, each returning a typed collection for the right document shape. Centralizing the collection names means a rename happens in one place, and typing each accessor keeps the userId filter visible to the compiler at every call site, which is how a rule that lives in prose stays honest in code.

The whole application and the Auth.js adapter share a single, serverless-safe MongoDB client to a single fixed database name, so there is exactly one connection pool. How that database name quietly caused two separate failures is a good story, and it belongs to the next article, where I stand the foundation up.

What this article bought

No chatbot yet, but the shape of the thing is already decided. Retention, the telemetry layout, and the tenant-isolation boundary are properties of the schema and its indexes now, not code I have to remember to run later. That is the payoff of modeling around the access patterns first: the database carries more of the load because you shaped it to. The data model is the foundational piece of the whole app.

Next, we'll build this foundation up, with identity the client never gets a vote in, and a health check that proves the app can reach Atlas and Bedrock, plus a view on the unglamorous errors that cost me real time. After that comes the streaming chat backbone, which is where the conversation finally gets a place to live, and I open a real checkpoint document to show you the messages that were never in their own collection.

Advanced API Authentication Strategies with Node.js and MongoDB (Part 3)

MongoDB Guests — Thu, 02 Jul 2026 09:00:00 +0000

This article was written by Moses Anumadu.

Secure Session Management with JWT and Refresh Tokens in Node.js and MongoDB

This is the final part of this 3-part series. In parts 1 and 2, we implemented email-based authentication. Then we went further to implement TOTP-based multi-factor authentication (MFA), QR code onboarding, and half-authentication login flow.

What we have built so far is an API that allows users to prove their identity using email and password. In this section, we will go beyond that. The application should not only be able to recognize users but also protect the user through concepts like secure session management, token expiration, and session revocation. We will implement these concepts through the following:

JWT access tokens
refresh tokens
MongoDB-backed sessions
refresh token rotation
protected routes
secure logout flows

By the end of this section, we should have an authentication system that can be deployed to production and improved upon for more advanced features.

Pre-requisites

To follow along with this tutorial, ensure you have prior experience working with the following technologies:

Node.js and Express
MongoDB and Mongoose
A MongoDB Atlas account
Postman
Ngrok
Parts one and two of this series

With that said, let's get started.

Understanding Access Tokens vs Refresh Tokens

An access token is a JWT token that grants a user access to a protected route. It often has a very short-lived life cycle. A refresh token is a token with a longer expiration time solely for requesting an access token. Without the refresh token, the user would need to log out and log back in to generate a new access token. The refresh token is stored in the database, enabling the system to recognize the user without terminating the session.

You are probably wondering why you need both, right? Let's look at an example. Imagine that a hacker steals a user's access token, and with this token, he (the hacker) can do malicious things. If this access token does not have a short-lived life cycle, the attacker would have a longer window to do more harm. To prevent this, the refresh token is required to generate a new access token from time to time. So, even if an access token is stolen, within 15 minutes, that token becomes invalid. The attacker can't do any harm.

This is an extra layer of security necessary for a secure authentication system and to improve the user experience. The flow looks like: a user logs in, access token and refresh token are granted, access token lasts for 15 minutes, refresh token lasts for 7 days, access token expires after 15 minutes, user does not need to log out, user generates a new access token using the refresh token saved in the database.

Creating Token Utilities

Now, we understand why we need both an access token and a refresh token. Let's proceed to the implementation. In part 2, when we created the MFA token, we created src/utils/tokenUtils.js file. We need to update that file to generate our access token, refresh token, and MFA token. Open src/utils/tokenUtils.js and replace the code with the code below:

const jwt = require("jsonwebtoken");

const crypto = require("crypto");

const generateAccessToken = (user) => {
  return jwt.sign(
    {
      userId: user._id,
      email: user.email,
    },
    process.env.JWT_ACCESS_SECRET,
    {
      expiresIn: process.env.ACCESS_TOKEN_EXPIRES_IN,
    }
  );
};

const generateRefreshToken = () => {
  return crypto.randomBytes(64).toString("hex");
};

const hashToken = (token) => {
  return crypto
    .createHash("sha256")
    .update(token)
    .digest("hex");
};

const generateMFAToken = (user) => {
  return jwt.sign(
    {
      userId: user._id,
      type: "mfa",
    },
    process.env.JWT_ACCESS_SECRET,
    {
      expiresIn: process.env.MFA_TOKEN_EXPIRES_IN,
    }
  );
};

module.exports = {
  generateAccessToken,
  generateRefreshToken,
  hashToken,
  generateMFAToken,
};

We added three methods generateAccessToken, generateRefreshToken, hashToken to the page. The hashToken will be used later. It will be used to encrypt our refresh token into a one-way SHA-256 hash before it is stored in the database or compared when validating. The generateAccessToken and generateRefreshToken generate an access token and a refresh token, respectively.

Why Refresh Tokens Are Not JWTs

Also, did you notice that our refresh tokens were generated using secure random bytes? This line of code here: crypto.randomBytes(64).toString("hex");. This simply gives us more control over it. The refresh token should be random, unpredictable, and most importantly, database-controlled. Refresh tokens, unlike access tokens, do not need readable claims.

So, this way, we can easily revoke it, rotate it, and control the session validation or invalidation.

Creating the Session Model

Our refresh token is database-controlled. That ultimately means we need to store and retrieve it from the database. To achieve this, we need to create a MongoDB model for storing user sessions. Create src/models/Session.js and update the page with the code below:

const mongoose = require("mongoose");

const sessionSchema = new mongoose.Schema(
  {
    userId: {
      type: mongoose.Schema.Types.ObjectId,
      ref: "User",
      required: true,
    },

    refreshTokenHash: {
      type: String,
      required: true,
    },

    userAgent: {
      type: String,
      default: null,
    },

    ipAddress: {
      type: String,
      default: null,
    },

    expiresAt: {
      type: Date,
      required: true,
    },

    revokedAt: {
      type: Date,
      default: null,
    },
  },
  {
    timestamps: true,
  }
);

module.exports = mongoose.model("Session", sessionSchema);

Notice that we are storing refreshTokenHash. Always remember that sensitive data at rest should also be encrypted. We created the fields we need to save for each user session. Notice fields like ipAddress, userAgent, expiresAt and revokedAt.

Issuing Tokens After MFA Verification

Now we can generate both a refresh token and an access token, and our MongoDB model is ready to save session values in the database. Next, we need to modify the authentication flow to include these. The flow should be: a user logs in, completes MFA, the application issues an access token and a refresh token to the user, and finally, the session values (including the refresh token) are stored in our MongoDB session collection. Let's proceed to the implementation.

!!!
Returning refresh tokens in JSON bodies is unsafe for browser clients and encourages XSS-exposed storage patterns. The safer pattern is HTTP-only cookie transport for refresh credentials. This is the approach we will follow in the next section.
!!!

Updating the Login Controller

In the next section, we will send refresh tokens using HTTP-only cookies transport as this is the safer option to prevent XSS-expose attacks.
The code in src/controllers/authController.js needs to be updated. Let's start by adding the import values and HTTP-only cookies configurations.

Open src/controllers/authController.js and add the following import statement to the top part of the page

const jwt = require("jsonwebtoken");
const Session = require("../models/Session");

const {
  generateAccessToken,
  generateRefreshToken,
  hashToken,
  generateMFAToken,
} = require("../utils/tokenUtils");

After the import statements, add the following HTTP-only cookie configurations. We will use these later in the code.

const getRefreshTokenExpiryMs = () => {
  const refreshDays = Number(
  process.env.REFRESH_TOKEN_EXPIRES_DAYS
  );

  return refreshDays * 24 * 60 * 60 * 1000;
};

const getRefreshTokenCookieOptions = () => {
  return {
    httpOnly: true,
    secure: process.env.NODE_ENV === "production",
    sameSite: "strict",
    path: "/api/auth",
    maxAge: getRefreshTokenExpiryMs(),
  };
};

const setRefreshTokenCookie = (res, refreshToken) => {
  res.cookie(
  "refreshToken",
  refreshToken,
  getRefreshTokenCookieOptions()
  );
};

const clearRefreshTokenCookie = (res) => {
  res.clearCookie("refreshToken", {
    ...getRefreshTokenCookieOptions(),
    maxAge: undefined,
  });
};

Updating the MFA Login Verification Flow

Next, replace the success section inside verifyMFALogin controller method with the code below:

Revoke this section

return res.status(200).json({
success: true,
message: "MFA login successful",
});

And replace with this:

// Issue access token
const accessToken = generateAccessToken(user);

// Generate refresh token
const refreshToken =
  generateRefreshToken();

// Hash refresh token
const refreshTokenHash =
  hashToken(refreshToken);

// Session expiry
const expiresAt = new Date();

expiresAt.setDate(
  expiresAt.getDate() +
    Number(
      process.env.REFRESH_TOKEN_EXPIRES_DAYS
    )
);

// Store session
await Session.create({
  userId: user._id,
  refreshTokenHash,
  userAgent: req.headers["user-agent"],
  ipAddress: req.ip,
  expiresAt,
});
setRefreshTokenCookie(res, refreshToken);
      return res.status(200).json({
       success: true,
       message: "Login successful",
       accessToken,
     });

From the additions we made, after password verification and MFA verification, a token is issued, and a session is created for the authenticated user.

Creating JWT Authentication Middleware

Now, we can issue an access token and a refresh token. Next, we need a way to protect our routes so that only users with the right access can access them. To do this, we need to implement middlewares.

A good example can be creating a middleware that protects routes and lets only authenticated users have access to it. Let's implement that. Create the following file src/middleware/authMiddleware.js, and update it with the code below:

const jwt = require("jsonwebtoken");

const User = require("../models/User");

const requireAuth = async (
  req,
  res,
  next
) => {
  try {
    const authHeader =
      req.headers.authorization;

    if (
      !authHeader ||
      !authHeader.startsWith("Bearer ")
    ) {
      return res.status(401).json({
        success: false,
        message: "Access token required",
      });
    }

    const token = authHeader.split(" ")[1];

    const decoded = jwt.verify(
      token,
      process.env.JWT_ACCESS_SECRET
    );

    const user = await User.findById(
      decoded.userId
    );

    if (!user) {
      return res.status(401).json({
        success: false,
        message: "Invalid user",
      });
    }

    req.user = user;

    next();
  } catch (error) {
    return res.status(401).json({
      success: false,
      message:
        "Invalid or expired access token",
    });
  }
};

module.exports = requireAuth;

Creating a Protected Route

At this point, the middleware is ready. We need to attach it to our routes to restrict access to only authenticated users. Let's create a controller to get the authenticated user getMe and a route for it /api/auth/me then protect it with the middleware we created above. To create the controller method, open src/controllers/authController.js and add the following controller method to the page.

const getMe = async (req, res) => {
  return res.status(200).json({
    success: true,
    user: {
      id: req.user._id,
      email: req.user.email,
      mfaEnabled: req.user.mfaEnabled,
    },
  });
};

Also, update the export block to contain the getMe method we just added, like so

module.exports = {
  register,
  login,
  setupMFA,
  verifyMFA,
  verifyMFALogin,
  getMe,
};

Adding the Protected Route

Next, let's create the route. Open src/routes/authRoutes.js and add the following to the page.

First, import the middleware by copying and pasting the code below to the top section of the page

const { getMe } = require("../controllers/authController");
const requireAuth = require("../middleware/authMiddleware");

Then add the route below to the route on the page.

router.get("/me", requireAuth, getMe);

Testing Protected Routes

We've made progress. Let's test what we've built so far. We will test with Postman on the web and Ngrok. Ngrok will be used to tunnel our localhost address to something on the internet. Check Part One of this article for more on the setup. With that said,

Login

To generate an access token, we need to go through a series of verifications. First, we need to log in and generate an MFA token to verify MFA. Send a post request to the route below to log in.

POST /api/auth/login

Add the following to the body

{ 
  "email": "test_user@example.com",
  "password": "password123"
}

Your response should look similar to the image below if everything is done right.

MFA verification and access key generation

We are partially logged in. We need to verify MFA to be fully logged in. Send a Post request to the route below:

POST /api/auth/mfa/login/verify

Also, add the following to the body of the request:

{ "token": "TOKEN_GENERATED_BY_AUTH_APP",
  "mfaToken": "MFA_TOKEN_GENERATED_FROM_LOGIN"
}

Protected route

Next, send a GET request to the route below

GET /api/auth/me

With the following Header values

Authorization: Bearer YOUR_ACCESS_TOKEN

If the token is valid, the request should return the authenticated user information, like the image below

Also, in MongoDB Atlas, you can see that user sessions were created and stored in our session collection.

Implementing Refresh Token Rotation

Let's take our authentication a step further by implementing refresh token rotations. What we want to achieve is simple. Every refresh request should generate a new access token, generate a new refresh token, and invalidate the old refresh tokens. Let's jump right into it.

Creating the Refresh Endpoint

Add the following controller method to src/controllers/authController.js.


const refreshAccessToken = async (req, res) => {
   try {
     const refreshToken = req.cookies?.refreshToken;
      if (!refreshToken) {
       return res.status(401).json({
         success: false,
         message: "Refresh token cookie required",
       });
     }
      const refreshTokenHash = hashToken(refreshToken);
      const session = await Session.findOne({
       refreshTokenHash,
       revokedAt: null,
     });
      if (!session) {
       clearRefreshTokenCookie(res);
       return res.status(401).json({
         success: false,
         message: "Invalid session",
       });
     }
      // Expired session
     if (session.expiresAt < new Date()) {
       clearRefreshTokenCookie(res);
       return res.status(401).json({
         success: false,
         message: "Session expired",
       });
     }
      const user = await User.findById(session.userId);
      if (!user) {
       return res.status(401).json({
         success: false,
         message: "Invalid user",
       });
     }
      // ROTATE REFRESH TOKEN
     const newRefreshToken = generateRefreshToken();
      const newRefreshTokenHash = hashToken(newRefreshToken);
      session.refreshTokenHash = newRefreshTokenHash;
      await session.save();
     setRefreshTokenCookie(res, newRefreshToken);
      // Generate new access token
     const accessToken = generateAccessToken(user);
      return res.status(200).json({
       success: true,
       accessToken,
     });
   } catch (error) {
     console.error(error);
      return res.status(500).json({
       success: false,
       message: "Failed to refresh token",
     });
   }
 };

Next, let's update the exports with the freshAccesstoken method like so:

module.exports = {
  register,
  login,
  setupMFA,
  verifyMFA,
  verifyMFALogin,
  getMe,
  refreshAccessToken,
};

Adding the Refresh Route and Testing

Let's proceed by adding a route to test the refresh token feature. Open src/routes/authRoutes.js and update the page with the code below

router.post(
  "/refresh",
  refreshAccessToken
);

Let's proceed to test. Send a POST request to the route below.

POST /api/auth/refresh

Request body:

{
  "refreshToken": "YOUR_REFRESH_TOKEN"
}

If everything was done right, your response should look like the screenshot above. And the previous tokens should no longer work.

Implementing Logout and Session Revocation

A complete logout system not only removes the access token from the browser in the front end. It should also invalidate the refresh token and revoke the session from the backend. That is exactly what we will do in this section.

Creating the Logout Endpoint

Add the following controller method to src/controllers/authController.js

const logout = async (req, res) => {
   try {
     const refreshToken = req.cookies?.refreshToken;
      if (!refreshToken) {
       return res.status(400).json({
         success: false,
         message: "Refresh token cookie required",
       });
     }
      const refreshTokenHash = hashToken(refreshToken);
      await Session.findOneAndUpdate(
       {
         refreshTokenHash,
         revokedAt: null,
       },
       {
         revokedAt: new Date(),
       }
     );
     clearRefreshTokenCookie(res);
      return res.status(200).json({
       success: true,
       message: "Logged out successfully",
     });
   } catch (error) {
     console.error(error);
      return res.status(500).json({
       success: false,
       message: "Logout failed",
     });
   }
 };

From the code, we did not delete the session records. We marked them as revoked instead, as we can see below.

await Session.findOneAndUpdate(
{
refreshTokenHash,
revokedAt: null,
},
{
revokedAt: new Date(),
}
);

This is a good practice as it helps preserve session history for audit and security visibility.

Implementing Logout From All Devices

Let's take it a step further by allowing users to revoke all active sessions simultaneously. This would let them log out from all devices at once. This is a nice feature to have; it helps a user protect their account in the case of a malicious login from an unknown device.

Let's proceed, modify src/controllers/authController.js file, and add the following controller method:

const logoutAll = async (req, res) => {
   try {
     await Session.updateMany(
       {
         userId: req.user._id,
         revokedAt: null,
       },
       {
         revokedAt: new Date(),
       }
     );
     clearRefreshTokenCookie(res);
      return res.status(200).json({
       success: true,
       message: "Logged out from all devices",
     });
   } catch (error) {
     console.error(error);
      return res.status(500).json({
       success: false,
       message: "Failed to logout all sessions",
     });
   }
 };

Update the export block to contain all the methods below

module.exports = {
  register,
  login,
  setupMFA,
  verifyMFA,
  verifyMFALogin,
  getMe,
  refreshAccessToken,
  logout,
  logoutAll,
};

Adding Logout Routes

To add the routes for logout, update src/routes/authRoutes.js and add the code below. Also ensure that you have imported both logout and logoutAll methods from authController.js.

router.post("/logout", logout);

router.post(
  "/logout-all",
  requireAuth,
  logoutAll
);

Testing Logout

Send a post request to the route below. Also, pass the body value in the body of your request.

Request:

POST /api/auth/logout

Request body:

{
  "refreshToken": "YOUR_REFRESH_TOKEN"
}

Your response should look similar to the screenshot below

You can also test the logout all feature the same way. Send a Post request to the route below with a valid access token.

Request:

POST /api/auth/logout-all

Also, add a header with a user's access token.

Authorization: Bearer YOUR_ACCESS_TOKEN

Expected response:

{
  "success": true,
  "message":
    "Logged out from all devices"
}

Did you notice that the logout-all requires an access token passed in as a request header, not a refresh token like the logout route? This is because the logout-all does not have an active user session or know the user sending the request. It needs a way to identify the user, so it requires a user's access token.

All refresh token sessions should now become invalid. To be sure, you can also try using the same refresh token. It should fail because this session has been revoked.

Conclusion

A big thumbs up to you for sticking around till the end of this three-part series. We built a complete authentication API using Node.js, Express, MongoDB Atlas, and tested using Postman on the web and Ngrok for localhost routing.

In this final part of this series (part three), we discussed the difference between JWT access tokens and refresh tokens, why we need both, and walked through the programmatic implementation of the authentication by implementing the following:

JWT access token authentication
Session storage
refresh token rotation
Middleware and protected routes
secure logout and session revocation

The complete flow of the authentication with all three (3) parts put together looks like:

User registration, password authentication, MFA setup and verification, JWT access tokens and refresh token issuance, refresh token sessions, middlewares and protected routes, session.

Security is more of layers than single features. For further reading, check out the following topics for additional layers that can be added to an authentication.

Rate limiting
Email verification
HTTPS enforcement
Secure HTTP-only cookies
Brute-force protection
Device monitoring
Anomaly detection

Awesome. You can find the complete code on GitHub.

I'm building my own Claude-based chatbot, powered by MongoDB

MongoDB Guests — Thu, 02 Jul 2026 08:39:00 +0000

This tutorial was written by Néstor Daza.

I use Claude every day. It's a great tool for my day-to-day work, helping with everything from research and text processing to, above all, writing code (nothing surprising here). But today, that little coder voice in my head asked me: what would it take to build my own version, running on infrastructure I understand and control? What if I could have my own AI bot? So that is what I am doing, and this is the first entry in a series documenting it.

The app is called Claudius. It is a personal, Claude-style chat workspace I am building for myself, with MongoDB as its entire backbone and Claude models served through AWS Bedrock. Every article in the series will ship with public code. The app runs on MongoDB Atlas’s free tier, so nothing here is a pattern you read about and cannot reach. You can clone it, run it, and lift the parts you want into your own work.

Why build it when Claude already exists?

Yes, yes, Claude already exists, and it is very good, so why build a smaller, less-featured version of it? Because the best teacher is you, building with your own hands! Building the agent loop by writing the code, with state and retrieval, I actually have to figure out how to make it work, and the entire infrastructure needed to run it will not only show me a lot of what a finished product hides, but should also be a really fun project!

There is a personal payoff, too. I want a chat app where I own the data, one that remembers the things I tell it across conversations, sitting in a database I run. It is built for me first, and keeping it personal also keeps the scope honest.

The build is also great content. Writing is part of what I do, so a project I would build anyway turns into a series that other developers can follow. That's the reason you are reading this.

MongoDB is the whole backbone

Having MongoDB as the only datastore in the project is the decision that shapes everything else. Not a database plus a cache plus a vector store plus a queue, just MongoDB.

That is uncommon enough to need some explaining. A chat app like this has to keep users and conversations somewhere. It has to persist the agent's working state so a conversation survives a page reload. Retrieval over your documents and long-term memories needs a vector store. Background work, once it shows up, needs somewhere to queue. The usual answer is to use a separate product for each of those, and you end up operating four systems that have to be kept in sync. I am using MongoDB throughout, because the document model and Atlas Vector Search cover that whole surface, and one database is far less to run and reason about.

Embeddings come from Voyage AI, which is now part of MongoDB. That matters more than it first sounds. The data and the retrieval layer that sits on top of it come from the same place, so there is no second vendor to manage for the part of the app that handles search. Voyage's models are also strongly multilingual, which I care about because I work across AMER and LATAM in English and Spanish, and embedding quality in Spanish is the difference between retrieval that works and retrieval that only pretends to while quietly missing the point.

If you come from a relational background, I will translate and mention parallels and differences as we go. When a document-model choice replaces something you would have built with a join table or an extra service, I will say so, explain it, and show the relational equivalent to make the tradeoff clear.

Why is Claude running through Bedrock?

The one big piece that is not MongoDB is the model layer, and every Claude model the app uses is served through AWS Bedrock. This choice comes down to convenience and ease of use: being able to move from a fast, cheap model to a slower, more capable one is a single string in a request, which makes the model picker in the UI almost free to build. Keeping model access within a single cloud relationship also puts credentials and billing in one place, which matters the moment there is a usage bill to watch.

What it does, and what it isn't

So what does Claudius actually do? Four things only. I'm capping the scope of the whole project right here.

It holds a streamed conversation and lets me switch Claude models in the middle of a thread. It remembers, both within and across conversations, persistent facts instead of hoarding transcripts. It lets me upload a file and ask questions answered from its contents. And it can run a longer research task that plans an approach and works through web sources to return a cited answer.

But it is not a product! There is no commercial plan behind it, no growth target to hit, and more importantly, I'll leave the full-blown version of a Claude Agent to the good folks at Anthropic; my plan is to keep Claudius very slim. Sign-in is Google and nothing else, and a user's role is decided on the server, so no public path hands out anything on its own. It is built for me, and late in this series, I open a small public tier so readers can try the finished thing. That tier is hard-capped but open enough to show you what the end result looks like, so stay tuned for one of the final articles of this series!

This is not a clone!

One very important thing to be clear about: Claudius is a personal homage and a learning project. It is not affiliated with or endorsed by Anthropic, and it is not meant to replace Claude, which remains the real thing. This is me rebuilding the shape of a tool I use and admire, to understand how it stands up, while showcasing the power of MongoDB as the sole data foundation of a complete agentic AI application.

How it will be built

The build runs in six phases, and the article series will track them closely.

Phase 0 lays the foundations, the data model, and the auth/role system that everything else assumes. Phase 1 brings the streaming chat backbone, Claude over Bedrock wired into the frontend, the first real conversation. Phase 2 adds file upload and retrieval for what you upload. Phase 3 is the one I am most looking forward to: long-term memory that survives across conversations. Phase 4 moves the heavier work, including the research agent, onto a background worker. Phase 5 closes the loop with usage metering and cost controls, and opens the small public tier.

Because every phase ships with public code, hosted in Github. The repo carries an annotated .env.example that lists every credential the build needs and the phase it belongs to, so you can reproduce each step instead of just reading it.

When the public tier goes live near the end of the series, it will live at askclaudius.dev, and you will be able to open the finished app and use it yourself.

That's enough on the why. The next article comes with the decision that surprised me most: Claudius has no message table! I'll show you where the conversation really lives, and why the document model is the right call and not just a clever hack. If you came up on SQL, this is the one to read!

Advanced API Authentication Strategies with Node.js and MongoDB (Part 2)

MongoDB Guests — Mon, 29 Jun 2026 09:00:00 +0000

Implementing MFA and TOTP with Node.js and MongoDB

This article was written by Moses Anumadu.

In part one (1) of this series, we implemented basic authentication. Users can register and also log in. In this section, we will take it a step further by adding multi-factor authentication (MFA) using a time-based one-time password (TOTP).

Basic authentication, which uses only a password and email, is arguably not secure enough for today's internet. Many users reuse their passwords, and attackers can exploit this vulnerability.

The core principle of multi-factor authentication is that it combines something the user knows with something the user owns to verify the user's identity. Something the User knows can be a password. Something the user owns can be a token sent to the user's device or email. The user needs to prove he knows the password and own the device where TOTP was sent.

If conditions are met, the user can be verified. With that said, let's get started on how to implement this in a Node.js and MongoDB application.

Pre-requisites

To follow along with this tutorial, ensure you have prior experience working with the following technologies:

Node.js and Express
MongoDB and Mongoose
A MongoDB Atlas account
Postman
Ngrok
Part one of this series

Adding MFA with TOTP

Let's go over what the flow of our MFA implementation would look like. So think of it like this:
First, the authenticated user has to enable MFA in the app. Next, the server generates a shared secret. Next, the user would need to scan a QR code with their phone camera or any of the authenticator apps of their choice (Google Authenticator, Authy, Microsoft Authenticator, etc). Next, the authenticator app would store the secret; the next app generates a 6-digit code. Finally, the server would verify the code. If correct, the user is authenticated.

The important thing to note here is that both the server and the authenticator app share the same secret. Using the current time and that secret, both sides independently generate matching one-time codes.

Creating a Temporary Authentication Middleware

One more step before we proceed. JWT authentication will be implemented in part three (3) of this tutorial. Since we have not implemented it yet, but need a way to identify the logged-in user, we will identify the user using the request header. This is temporary and will be updated to use JWT in part three. For now, create tempAuth.js in src/middleware/ directory. Update the file with the code below

const User = require("../models/User");

const tempAuth = async (req, res, next) => {
  try {
    const email = req.headers["x-user-email"];

    if (!email) {
      return res.status(401).json({
        success: false,
        message: "Missing x-user-email header",
      });
    }

    const user = await User.findOne({ email });

    if (!user) {
      return res.status(401).json({
        success: false,
        message: "User not found",
      });
    }

    req.user = user;

    next();
  } catch (error) {
    console.error(error);

    return res.status(500).json({
      success: false,
      message: "Authentication middleware error",
    });
  }
};

module.exports = tempAuth;

This middleware is only temporary and will later be replaced with proper JWT authentication.

Generating MFA Secrets and QR Codes

We now have a way to temporarily identify the user. Let's proceed to the MFA secrets and QR codes implementation. If you can recall, in the first part of this series, we installed all the NPM packages we would need. Two of them were Otplib and Qrcode. It is the package of choice for this implementation. If you do not have them installed already, you can install them using the NPM command below:

npm install otplib

And

npm install --save qrcode

Once you confirm you have them installed, let's import and use them in the authController.js. Open src/controllers/authController.js. Add the code below to the top section of the page.

const QRCode = require("qrcode");

const {
  generateSecret,
  generateURI,
  verify,
} = require("otplib");

Next, add the code below after the login method on the page

const setupMFA = async (req, res) => {
  try {
    const user = req.user;

    // Generate shared secret
    const secret = generateSecret();

    // Generate OTP auth URL
    const otpAuthUrl = generateURI({
      label: user.email,
      issuer: "AdvancedAuthAPI",
      secret,
    });

    // Generate QR code image
    const qrCodeImageUrl =
      await QRCode.toDataURL(otpAuthUrl);

    // Store secret temporarily
    user.mfaSecret = secret;

    await user.save();

    return res.status(200).json({
      success: true,
      message: "MFA setup initialized",
      secret,
      qrCodeImageUrl,
    });
  } catch (error) {
    console.error(error);

    return res.status(500).json({
      success: false,
      message: "Failed to setup MFA",
    });
  }
};

module.exports = { register, login, setupMFA};

The code is well commented. Regardless, let's still go over a few lines and what they do. This line generates the shared secret: const secret = generateSecret();

The generated secret is then embedded into a special OTP URI in the block of code below

const otpAuthUrl = generateURI({
  label: user.email,
  issuer: "AdvancedAuthAPI",
  secret,
});

For the user to be able to scan, we converted the URI into a QR code using the qrcode package in the line of code below:

const qrCodeImageUrl =
await QRCode.toDataURL(otpAuthUrl);

When a user scans the QR code with their authenticator app, the authenticator app securely stores the shared secret.

Verifying MFA Codes

We have completed the MFA setup functionality. Let's proceed to the verification functionality. We need another controller method to verify the 6-digit code generated by the authenticator app. This will have a different endpoint also. Let's proceed. Still in src/controllers/authController.js add the following verification controller method below setupMFA:

const verifyMFA = async (req, res) => {
  try {
    const user = req.user;

    const { token } = req.body;

    if (!token) {
      return res.status(400).json({
        success: false,
        message: "MFA token is required",
      });
    }

    const verification = await verify({
      token,
      secret: user.mfaSecret,
    });

    const isValid = verification?.valid === true;

    if (!isValid) {
      return res.status(401).json({
        success: false,
        message: "Invalid MFA code",
      });
    }

    user.mfaEnabled = true;

    await user.save();

    return res.status(200).json({
      success: true,
      message: "MFA enabled successfully",
    });
  } catch (error) {
    console.error(error);

    return res.status(500).json({
      success: false,
      message: "Failed to verify MFA",
    });
  }
};

module.exports = { register, login, setupMFA, verifyMFA };

The token is passed along as req.body. When received in the code, it is verified using

const verification = await verify({
       token,
       secret: user.mfaSecret,
     });

If the code is valid, the user is logged in, and MFA is enabled. Did you notice that the MFA is only enabled after a successful verification? user.mfaEnabled = true;. This was done to prevent a broken MFA setup, which can accidentally lock a user out of their account. This prevents broken MFA setups and accidental account lockouts.

Adding MFA Routes

We need to update our authRoutes.js to include routes for both the setupMFA and verifyMFA controller methods. To do this, open src/routes/authRoutes.js and replace the content of the page with the code below

const express = require("express");

const {
  register,
  login,
  setupMFA,
  verifyMFA,
} = require("../controllers/authController");

const tempAuth = require("../middleware/tempAuth");

const router = express.Router();

router.post("/register", register);
router.post("/login", login);
router.post("/mfa/setup", tempAuth, setupMFA);
router.post("/mfa/verify", tempAuth, verifyMFA);

module.exports = router;

Testing MFA Setup

In part one (1) of this series, we set up Ngrok for tunneling our local host to the internet and tested our endpoints using Postman. If you do not have that setup, follow the link to set up to follow along.

If your project is not running already, start it using the command below

npm run dev

Then, send a POST request to the following endpoint:

POST /api/auth/mfa/setup

Remember our temporary middleware, set the header value to the value below

Headers:
x-user-email: test_user@example.com

The response should include a QR code image URL. Check out the images below for more details

Copy the URL from the response and paste it into a browser. You should see a QR code image, like what we have below

Next, scan the QR code using any authenticator app of your choice. After scanning, your authenticator app should begin generating 6-digit codes like the image below.

Testing MFA Verification

Let's proceed to test the MFA verification endpoint. Send a post request to the route below

POST /api/auth/mfa/verify

Also, send the following header values:

x-user-email: test_user@example.com

Then, the request body should contain the following:

{
  "token": "MFA_app_generated_code"
}

Don't forget to replace the token placeholder in the request body with the correct code from your authenticator app.

The images below should throw more light on the steps.

Implementing the Half-Authenticated Flow

Our MFA setup and verification now work. However, it is completely independent of the login and sign-up. We have created routes for the MFA but have not linked it to the login and sign-up flow. What we have now gives a user full authentication once a correct email and password are provided. We need to change that. We need a partial authentication flow: this is what I mean, when a user provides a correct email and password, we need to partially identify the user, and yet, prompt for MFA. Only when MFA is completed can the user be fully authenticated.

To achieve this, we will issue a temporary JWT token to the user after a correct password and email are provided; at this state the user is not yet authenticated but can be identified with this JWT token. Then, when the MFA process is completed, only then will the user be fully authenticated.

When we are done, the flow should be: password verified, issue a temporary JWT token to identify the user, MFA code generated from the authenticator app, the user submits the OTP code, and finally, authentication is completed. Let's proceed.

Creating MFA Tokens

Let's write the code to generate the temporary JWT token for the MFA process. Create src/utils/tokenUtils.js the following file and update it with the code below

const jwt = require("jsonwebtoken");

const generateMFAToken = (user) => {
  return jwt.sign(
    {
      userId: user._id,
      type: "mfa",
    },
    process.env.JWT_ACCESS_SECRET,
    {
      expiresIn: process.env.MFA_TOKEN_EXPIRES_IN,
    }
  );
};

module.exports = {
  generateMFAToken,
};

In the code above, we imported require("jsonwebtoken"); and used it to generate the JWT token. Token expiration and secret values come from the env file created earlier in part one of this series.

Updating the Login Flow

We need to update the login controller method to add the generated MFA JWT token. To continue, open src/controllers/authController.js and add the following.

First, add the import below to the top section of the page.

const jwt = require("jsonwebtoken");

const {
  generateMFAToken,
} = require("../utils/tokenUtils");

Next, let's update the login controller with the code below. Paste the code just above the return statement.

// MFA enabled
if (user.mfaEnabled) {
  const mfaToken = generateMFAToken(user);

  return res.status(200).json({
    success: true,
    requiresMFA: true,
    mfaToken,
  });
}

Now, users with MFA enabled no longer receive full authentication immediately after password verification. Instead, they receive a temporary MFA token.

Completing MFA Login

We need another controller method to process the MFA verification. Add the following controller below verifyMFA method:

const verifyMFALogin = async (req, res) => {
  try {
    const { token, mfaToken } = req.body;

    if (!token || !mfaToken) {
      return res.status(400).json({
        success: false,
        message:
          "Token and MFA token are required",
      });
    }

    // Verify temporary MFA token
    const decoded = jwt.verify(
      mfaToken,
      process.env.JWT_ACCESS_SECRET
    );

    if (decoded.type !== "mfa") {
      return res.status(401).json({
        success: false,
        message: "Invalid MFA session",
      });
    }

    const user = await User.findById(
      decoded.userId
    );

    if (!user || !user.mfaEnabled) {
      return res.status(401).json({
        success: false,
        message: "Invalid user",
      });
    }

    // Verify OTP
    const verification = await verify({
      token,
      secret: user.mfaSecret,
    });

    const isValid =
      verification?.valid === true;

    if (!isValid) {
      return res.status(401).json({
        success: false,
        message: "Invalid MFA code",
      });
    }

    return res.status(200).json({
      success: true,
      message: "MFA login successful",
    });
  } catch (error) {
    console.error(error);

    return res.status(401).json({
      success: false,
      message:
        "Invalid or expired MFA session",
    });
  }
};

Also, don't forget to update the export block with the code below.

module.exports = {
  register,
  login,
  setupMFA,
  verifyMFA,
  verifyMFALogin,
};

Adding the MFA Login Verification Route

Let's create routes for the above changes. Open src/routes/authRoutes.js and update the page with the code below:

router.post(
  "/mfa/login/verify",
  verifyMFALogin
);

Testing the Full MFA Login Flow

The first step is to log in normally. Send a Post request to the route below

POST /api/auth/login

If MFA is enabled, the response should contain an mfaToken just like the image below:

Next, verify MFA by sending a Post request to the route below

POST /api/auth/mfa/login/verify

The request should pass the code below in the body.
Request body:

{
  "token": "123456",
  "mfaToken": "..."
}

After testing, your response should look similar to the image below.

Conclusion

In this section, we added an extra layer on top of the existing authentication system we built in part one. After entering the correct email and password, users must configure and verify MFA using TOTP. To achieve this, we implemented the following in the code:

login verification
TOTP-based MFA
QR code onboarding
half-authenticated login flows

We've gone halfway, but we're not done. In Part 3, we will take it a step further by adding

JWT access tokens
refresh tokens
MongoDB-backed sessions
refresh token rotation
protected routes
secure logout and session revocation

See you in part 3. Cheers.

Advanced API Authentication Strategies with Node.js and MongoDB (Part 1)

MongoDB Guests — Thu, 25 Jun 2026 09:00:00 +0000

This article was written by Moses Anumadu.

Building Password Authentication with Node.js and MongoDB

Most database-driven applications require users to be authenticated. This is not a surprise. The surprise might come when you hear about the number of cyberattacks carried out daily and their complexity. According to Akamai Technologies, there are over 300 million and over 500 million credential-stuffing attacks per day. Given this volume of attacks, it is reasonable for applications to add more layers of authentication (MFA) to the traditional email-and-password authentication.

This three-part tutorial will guide you through building a production-style authentication system that goes beyond the basic signup and login using Node.js, Express, and MongoDB Atlas.

In this first part (Part 1) of the three-part series, we will implement the foundation of the authentication that we will build upon throughout the rest of the series. We will implement the following:

A secure password hashing with bcrypt.
User registration with email and password.
User logs in with email and password.

In Part 2, we will continue building on the existing codebase. We will add secure session management to the code by implementing the following:

Login verification
TOTP-based MFA setup and verification
QR code onboarding for TOTP setup
Half-authenticated login flows

And in Part 3, we will make it an authentication that you can deploy or use in your real-world application by implementing the following:

JWT access tokens
refresh tokens
MongoDB-backed sessions
refresh token rotation
protected routes
secure logout and session revocation

Pre-requisites

To follow along with this tutorial, ensure you have your development environment set up for the stack above and:

An understanding of Node.js and Express
An Understanding of MongoDB
A MongoDB Atlas account
Postman for testing API endpoints

Alright, let's get started.

Project Setup

To get started, we need to create a fresh Node.js project and install all the necessary dependencies. In your directory of choice, create the project using the command below:

mkdir devrel-node-api-authentication
cd devrel-node-api-authentication
npm init -y

An advanced authentication system like the one we are building relies on several dependencies in Node.js. We’ll install a few packages to handle those responsibilities. From your terminal, navigate to the project directory and then install dependencies using the command below

npm install express mongoose dotenv bcryptjs jsonwebtoken otplib qrcode && npm install --save-dev nodemon

Let's take a moment to go over all the packages we just installed. Express provides the web server and routing system for building our API, while Mongoose letting us interact with MongoDB through models and schemas. dotenv helps us load environment variables such as database credentials and secret keys. bcryptjs securely hashes passwords before storing them in the database and jsonwebtoken enables us to create and verify JWT tokens for authentication. For MFA functionality, otplib generates and validates time-based one-time passwords (TOTP), while qrcode converts our MFA setup information into a scannable QR code for authenticator apps. Finally, nodemon improves the development experience by automatically restarting the server whenever code changes are detected.

After the installation, we need to update the script section in our package.json file with the code below:

"scripts": {
  "dev": "nodemon src/server.js"
}

This would enable us to serve the project using npm run dev

Creating the Project Structure

We are making progress. Let's proceed by creating a structure for the project. In your project, create the following files and folders. The project structure should look like the sample below.

src/
├── config/
├── controllers/
├── middleware/
├── models/
├── routes/
├── utils/
├── app.js
└── server.js

Configuring MongoDB Atlas

Next, let's configure our application to interact with our MongoDB Atlas cluster. Ensure you have your Atlas connection string. If you do not have an Atlas account, follow the link to sign up and create an Atlas cluster, then obtain your connection string. With that said, create a


 file in the project root directory and update the content with the code below:


```bash
MONGO_URI_BASE=mongodb+srv://USERNAME:PASSWORD@cluster0.xxxxx.mongodb.net

JWT_ACCESS_SECRET=supersecretaccesskey
JWT_REFRESH_SECRET=supersecretrefreshkey

ACCESS_TOKEN_EXPIRES_IN=15m
REFRESH_TOKEN_EXPIRES_DAYS=7
MFA_TOKEN_EXPIRES_IN=5m

PORT=5000

Now that we have our Atlas connection string, let's proceed to connect our application to MongoDB using Mongoose. Create src/config/db.js and update the file with the code below.

const mongoose = require("mongoose");

const databaseName = "devrel-node-auth-db";
const appName = "devrel-tutorial-nodejs-authentication-geeksforgeeks";

const connectDB = async () => {
try {
  const mongoUri = `${process.env.MONGO_URI_BASE}/${databaseName}?retryWrites=true&w=majority&appName=${appName}`;

  await mongoose.connect(mongoUri);

  console.log("MongoDB connected");
  console.log(`Database: ${databaseName}`);
  console.log(`App Name: ${appName}`);
} catch (error) {
  console.error("MongoDB connection failed:");
  console.error(error.message);

  process.exit(1);
}
};

module.exports = connectDB;

Notice that the database name and appName are defined directly inside the codebase rather than inside the environment file. This keeps infrastructure-level configuration consistent across environments.

Creating the Express App

Now that we have the database configuration done, let's proceed to create an Express application. To keep things organized, we will create the app instance and register global middlewares in src/app.js. Update the file with the code below.

const express = require("express");
const authRoutes = require("./routes/authRoutes");
const app = express();

app.use(express.json());

app.use("/api/auth", authRoutes);
module.exports = app;

In src/app.js, we imported and used the authRoutes.js file. Let's go ahead and create this file before we proceed.
In src/routes/ directory, create the authRoutes.js file and update it with the code below:

const express = require("express");

const router = express.Router();

router.get("/health", (req, res) => {
 res.status(200).json({ message: "Auth routes are working" });
});

module.exports = router;

We created a simple /health route to verify that the application setup was correct.

Creating the Server Entry Point

Next, in copy and paste the code below into the src/server.js file.

const dotenv = require("dotenv");
const app = require("./app");
const connectDB = require("./config/db");

dotenv.config();

const PORT = process.env.PORT || 5000;

const startServer = async () => {
 await connectDB();
 app.listen(PORT, () => {
   console.log(`Server running on port ${PORT}`);
 });
};

startServer();

Now, we can test the configuration so far. In your project directory, start the development server using the command below:

npm run dev

If everything is configured correctly, you should see the following from your terminal:

MongoDB connected
Server running on port 5000

Creating the User Model

With all the configurations done, let's jump to the exciting part. So, the first step in authentication is creating a user. We need to implement code to create a user and securely store the password using bcrypt for Node.js in our MongoDB collection.

Create src/models/User.js file and update the file with the code below:

const mongoose = require("mongoose");

const userSchema = new mongoose.Schema(
 {
   email: {
     type: String,
     required: true,
     unique: true,
     lowercase: true,
     trim: true,
   },

   passwordHash: {
     type: String,
     required: true,
   },

   mfaEnabled: {
     type: Boolean,
     default: false,
   },

   mfaSecret: {
     type: String,
     default: null,
   },
 },
 {
   timestamps: true,
 }
);

module.exports = mongoose.model("User", userSchema);

From the code above, we created a User model. Mongoose was used to create our User schema and User model. One more thing to note is that, according to the schema, we are storing passwordHash instead of password. PasswordHash ensures that the password is not stored in plain text but is hashed using bcrypt.

Building User Registration

Let's proceed to the actual logic to create a new user. In src/controllers/authController.js, copy and paste the code below.

const bcrypt = require("bcryptjs");
const User = require("../models/User");

//Now add the registration controller:

const register = async (req, res) => {
  try {
    const { email, password } = req.body;

    // Basic validation
    if (!email || !password) {
      return res.status(400).json({
        success: false,
        message: "Email and password are required",
      });
    }

    // Password length validation
    if (password.length < 6) {
      return res.status(400).json({
        success: false,
        message: "Password must be at least 6 characters",
      });
    }

    // Prevent duplicate accounts
    const existingUser = await User.findOne({ email });

    if (existingUser) {
      return res.status(409).json({
        success: false,
        message: "User already exists",
      });
    }

    // Hash password
    const passwordHash = await bcrypt.hash(password, 12);

    // Create user
    const user = await User.create({
      email,
      passwordHash,
    });

    return res.status(201).json({
      success: true,
      message: "User registered successfully",
      user: {
        id: user._id,
        email: user.email,
      },
    });
  } catch (error) {
    console.error(error);

    return res.status(500).json({
      success: false,
      message: "Server error",
    });
  }
};
module.exports = { register };

From the code above, you can see that we validated for empty email and password values, password length, and prevented duplicate accounts by checking whether the email already exists. The next important thing to note is that the password was hashed using bcrypt
const passwordHash = await bcrypt.hash(password, 12);.

Bcrypt automatically handles salting, secure hashing, and computational cost. The second parameter (12) represents the salt rounds value. The higher this number, the more difficult it is for an attacker to crack this password.

Updating Authentication Routes

Let's create a route link for the Register logic. We already created the src/routes/authRoutes.js file. Now open the file and update the content with the code below.

const express = require("express");

const {
  register,
} = require("../controllers/authController");

const router = express.Router();

router.post("/register", register);

module.exports = router;

Testing Registration

It's time to test what we have built so far. For this tutorial, I will be testing with Postman on the web and tunneling my local environment using Ngrok. Feel free to test with what works for you or follow along with me.

If your server is not already running, navigate to your project directory and start the server with the command below;

npm run dev

In a different terminal window, start Ngrok using the command below:

Ngrok http 5000

You should expect an output similar to the image below:

Ngrok tunnels our localhost:5000 URL to https://b76b-197-157-218-195.ngrok-free.app or something similar. The Ngrok URL will be used to test in Postman, not our localhost URL.

To test, send a POST request to the register route: /api/auth/register. Also, add the following to the request body:

{
  "email": "test_user@example.com",
  "password": "password123"
}

Your output should be similar to the image below:

Try creating a duplicate user with the same record, and notice you should get a response similar to the image below

If you inspect your MongoDB Atlas database, you should now see a users collection containing the new user document with an encrypted password.

Building Password Authentication

Now, users can register. Let's proceed to Login. Registered users should be able to securely login to the system using their email and password. Still in src/controllers/authController.js, just below the register function, copy and paste the code below.

const login = async (req, res) => {
  try {
    const { email, password } = req.body;

    // Basic validation
    if (!email || !password) {
      return res.status(400).json({
        success: false,
        message: "Email and password are required",
      });
    }

    // Find user
    const user = await User.findOne({ email });

    // Prevent email enumeration attacks
    if (!user) {
      return res.status(401).json({
        success: false,
        message: "Invalid credentials",
      });
    }

    // Compare password with stored hash
    const isPasswordValid = await bcrypt.compare(
      password,
      user.passwordHash
    );

    if (!isPasswordValid) {
      return res.status(401).json({
        success: false,
        message: "Invalid credentials",
      });
    }

    return res.status(200).json({
      success: true,
      message: "Login successful",
      user: {
        id: user._id,
        email: user.email,
        mfaEnabled: user.mfaEnabled,
      },
    });
  } catch (error) {
    console.error(error);

    return res.status(500).json({
      success: false,
      message: "Server error",
    });
  }
};

Also, update the export, add the register function we just created, like so:

module.exports = {
  register,
  login,
};

In the code, we did a number of validations. The first one checked for empty strings, then we checked if this user exists in the database. Did you notice that both invalid email and invalid password return the same response: "Invalid credentials"? This prevents attackers from discovering which email addresses exist in the system. After that, we compared the input password with the password in the database. Also note that the password was not decrypted, it was instead compared against the encrypted version already stored in our database.

Adding the Login Route

Next, let's add a route for the login. Replace the code in src/routes/authRoutes.js with the code below to create a route for both /register and /login.

const express = require("express");

const {
  register,
  login,
} = require("../controllers/authController");

const router = express.Router();

router.post("/register", register);
router.post("/login", login);

module.exports = router;

Testing Login

To test, send a POST request to the login route: /api/auth/login. Also, add the following to the request body:

{
  "email": "test_user@example.com",
  "password": "password123"
}

We are making progress. We now have a very basic authentication system with Login and Register features. This is obviously nowhere near battle-ready for today's internet. So, we will proceed and strengthen this system with Multi-Factor Authentication (MFA).

Conclusion

In this part, we kept it simple and implemented user registration and login. Users can register with an email and a password; a JWT token is not issued yet at this stage. The system now only knows that the user's email and password are valid. To achieve this, we implemented the following:

A secure password hashing with bcrypt.
User registration with email and password.
User logs in with email and password. In the next part ( 2), we will build upon the foundation we create here by adding secure session management using:
login verification
TOTP-based MFA setup and verification
QR code onboarding
half-authenticated login flows See you in part 2.