DEV Community: MonoCloud Admin

Protecting Node.js APIs: Audiences, Scopes, and Bearer Tokens

MonoCloud Admin — Mon, 27 Apr 2026 12:41:12 +0000

Most APIs leak in the same handful of ways: missing audience checks, scope rules scattered across handlers, JWT validation that drifts out of date, tokens issued for one service quietly accepted by another. Each one is small on its own, and each one ends up in a postmortem.

This post walks through the patterns that prevent those failures — token validation done right, per-API audience isolation, route-level scope enforcement, and server-side token forwarding from a front end. The code samples come from MonoShop, a small reference repo we put together to make the patterns concrete, but the ideas apply to any Node.js API sitting behind an OAuth/OIDC provider.

Treat Each API as Its Own Resource

The first design decision in API authorization is granularity: what is a token actually issued for? The right answer is almost always each API, not "the platform."

If your billing API and your admin API both accept "any signed token from our IDP," they share a trust boundary. Compromise one and you've compromised both. The fix is to register each API as a separate protected resource with its own audience identifier — typically a URL string — and reject anything that doesn't match.

The MonoShop repo demonstrates this with two services:

Service	Audience	Required Scope
Product API	`http://api.monoshop.com/products`	`read:products`
Invoice API	`http://api.monoshop.com/invoices`	`read:invoices`

A token minted for one will not validate against the other, even though both trust the same identity provider. The audience claim is just a string, but it's the line between "user signed in" and "user can hit this specific service." Treat it like a service boundary, because it is one.

Token Validation, Done Right

Validating a JWT properly is more than calling jwt.verify. You need the right signing keys (fetched from the provider's JWKS endpoint), a strategy for key rotation, issuer verification, audience verification, expiry and clock-skew handling, and scope checks tailored to each route. Get any of it wrong and you've either broken legitimate users or, worse, accepted tokens you shouldn't.

This is the layer where silent bugs live. Most identity providers ship middleware that handles the pipeline end-to-end, and there are certified OAuth libraries that do the same — reaching for one of them is the simpler and safer default. Here's what that looks like — the entire Product API in MonoShop:

import { protectApi } from "@monocloud/backend-node/express";
import express from "express";
import { products } from "./data";

const app = express();
const protect = protectApi();

app.get("/products", protect({ scopes: ["read:products"] }), (req, res) => {
  res.json(products);
});

app.listen(4001);

The middleware fetches the JWKS, verifies the signature, checks the issuer, validates expiry, enforces the configured audience, and confirms the token carries the scopes the endpoint requires.

If you're using opaque tokens instead of JWTs, it introspects the token against the provider's introspection endpoint and runs the same checks against the response, including confirming the token hasn't been revoked. Your handler runs only when all of that passes.

Audience Isolation Should Be Configuration

Once each API is its own resource, enforcing the boundary should be a config value, not application code. A typical setup is one environment variable read by the middleware at startup:

MONOCLOUD_BACKEND_AUDIENCE=http://api.monoshop.com/products

The check happens before any of your code runs, which means you can't accidentally forget it on a new route. Same user, same issuer, same signing key — wrong audience, no access.

Scopes Belong Next to Routes

Authentication tells you who the caller is. Scopes tell you what they're allowed to do. The cleanest place to express that is right next to the route the rule applies to:

app.get("/products",  protect({ scopes: ["read:products"] }),  listProducts);
app.post("/products", protect({ scopes: ["write:products"] }), createProduct);

A token without read:products gets a 403 before listProducts is invoked. There's no if (user.can(...)) check inside the handler, no role table to keep in sync — the authorization rule is a property of the route, not a runtime branch.

The general principle: keep authorization declarative and visible at the boundary. If you can't read your route table and tell who's allowed to call what, you've buried the rules somewhere they'll fall out of sync.

Keep Tokens Server-Side

Bearer tokens are credentials. Anywhere you store them on the client - local storage, session storage, accessible cookies — you've extended the attack surface to include XSS anywhere on your front end, plus every third-party script you've ever loaded.

The safer pattern, especially with frameworks that have a server runtime, is to keep tokens in a server-side session and only forward them to APIs from server code. The Next.js front end in MonoShop uses a Server Action to do exactly that:

"use server";
import { getTokens } from "@monocloud/auth-nextjs";

export async function getProducts() {
  const tokens = await getTokens();

  const res = await fetch(`${process.env.NEXT_PUBLIC_PRODUCT_API_URL}/products`, {
    headers: { Authorization: `Bearer ${tokens?.accessToken}` },
  });

  return res.json();
}

The browser never sees the access token. It calls the Server Action; the server retrieves the token from the session, attaches it to the upstream request, and returns the result. The same shape works whether you have one API or ten — the front end requests tokens for the resources it needs at sign-in time, and the provider mints one access token per audience.

Scaling Out Without New Infrastructure

The pattern above scales naturally. Each new service is another protected resource with its own audience and scopes. Every API:

Trusts the same identity provider
Validates its own audience
Enforces its own scopes
Has no awareness of the others

There's no shared session store to coordinate, no internal token-exchange dance, no "auth service" in your dependency graph that everyone has to keep alive. Each API is independently protected by stateless token validation. MonoShop ships with two services to show the multi-API shape, but the third would be a copy-paste pointed at a new audience.

Trying It Locally

If you want to see the patterns in action:

git clone https://github.com/monocloud/monoshop-api-demo.git
cd monoshop-api-demo
npm install

Copy each .env.example to .env and fill in credentials from your identity provider (the repo uses MonoCloud — sign up is free if you want to follow along), then:

npm run dev

Open http://localhost:3000, sign in, and the dashboard will call both protected APIs and render their data. To confirm the protection actually works, hit the APIs directly:

curl http://localhost:4001/products
# 401 Unauthorized

Or with a token whose audience or scope doesn't match — same result. The middleware does its job before your handler ever sees the request.

Takeaways

The patterns worth carrying away, regardless of which provider you pick:

Treat each API as a separate resource with its own audience. Don't share tokens across services.
Enforce scopes at the route, not in the handler. Your authorization rules should be readable in the route table.
Keep tokens server-side. If you have a server runtime, forward them from there rather than handing them to the browser.
Don't roll your own JWT validation in production unless you're prepared to maintain it.

Ship Auth, Don't Build It

API authorization isn't usually where teams want to spend roadmap time. The patterns above are well-trodden, and the implementation is mostly maintenance work that doesn't differentiate your product. Pick a provider, lean on a vetted library, and let the boring parts stay boring.

Want to dig deeper? Start with the MonoCloud Docs, explore the Express Backend SDK, or clone MonoShop and start hacking.

OAuth for SaaS: What Every Developer and Technical Leader Needs to Know

MonoCloud Admin — Mon, 23 Mar 2026 20:51:36 +0000

If you're building a SaaS product today, OAuth isn't optional — it's foundational. It's the protocol behind "Sign in with Google," third-party integrations, API access control, and the secure service-to-service communication that holds modern platforms together.

Yet OAuth remains widely misunderstood. Teams confuse it with authentication, misuse its flows, or bolt it on as an afterthought, only to face security gaps and painful refactors later.

This guide cuts through the confusion. It explains what OAuth actually does, why SaaS platforms need it, which flows matter for which use cases, and the mistakes that trip up even experienced teams.

Why SaaS Applications Can't Avoid OAuth

A modern SaaS platform is rarely a single application. It's typically a constellation of components — a web dashboard, a mobile app, public APIs, third-party integrations, and a cluster of internal microservices — all needing access to shared resources like user data, billing records, and analytics.

The challenge: how do you let all of these components access the right data, for the right users, without passing around passwords or hardcoding secrets?

OAuth solves this by issuing tokens that represent delegated permissions. Instead of sharing credentials, an application receives a short-lived token that grants specific, limited access. The user stays in control. The credentials stay safe.

The Four Roles in Every OAuth Flow

OAuth defines four participants. Understanding who does what is the first step to implementing it correctly.

Resource Owner — the user who owns the data. In a SaaS context, this is your customer granting permission for an app to access their account.

Client — the application requesting access. This could be your web frontend, a mobile app, a CLI tool, or a third-party integration built on your API.

Authorization Server — the system that authenticates users, enforces permissions, and issues tokens. This is the engine of the whole flow. It handles consent screens, validates credentials, and decides what access to grant.

Resource Server — the API that holds protected data. It receives requests, validates the attached token's signature, expiration, audience, and scopes, and then either allows or rejects the request.

In practice, many SaaS teams run the authorization server as a managed service and distribute resource servers across their API landscape.

Access Tokens: The Core Mechanism

At the heart of OAuth is a simple idea: instead of giving an application a user's password, you give it a token.

That token represents a specific set of permissions, is scoped to a specific API, and expires after a defined period. The API receiving the token validates it and grants access accordingly.

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

This approach decouples authentication from authorization. The API doesn't need to know how the user signed in — it only needs to know that the token is valid and carries the right permissions.

Scopes: Fine-Grained Permission Control

Scopes define what a client application is allowed to do with a token.

A well-designed SaaS API uses granular scopes rather than broad, all-or-nothing permissions:

Scope	What It Allows
`read:products`	View the product catalog
`write:products`	Create or update products
`read:invoices`	View invoice data

When a token arrives at your API, the resource server checks whether its scopes match the operation being requested. A token with read:products can't update anything — the request gets rejected.

This model lets SaaS platforms implement nuanced permission systems across multiple APIs without reinventing access control for each one.

OAuth vs. API Keys vs. Session Cookies

OAuth isn't the only way to secure access. Here's how it compares to the other common approaches:

API keys are simple and useful for basic integrations, but they represent an application rather than a user, and offer no built-in permission model.

Session cookies work well for traditional web apps, but they're tied to browser sessions and don't translate to API-first architectures.

OAuth tokens are purpose-built for the kind of distributed, multi-client, API-driven systems that SaaS platforms actually are.

OAuth vs. OpenID Connect: Authorization vs. Authentication

One of the most common points of confusion: OAuth is not an authentication protocol. It's an authorization framework.

OAuth answers the question: "What is this application allowed to do?"

Authentication — proving who the user is — is handled by OpenID Connect (OIDC), which is a layer built on top of OAuth.

	OAuth	OIDC
Purpose	Authorization	Authentication
Token	Access Token	ID Token
Answers	"What can this app do?"	"Who is this user?"

Most SaaS platforms need both. OIDC handles user login and identity. OAuth handles API access and delegated permissions. Together, they form the standard identity and authorization stack for modern applications.

Choosing the Right OAuth Flow

Different client types require different OAuth flows. The choice depends on where the client runs, whether it can securely store secrets, and whether a user is involved.

Authorization Code Flow

The gold standard for web applications. The client exchanges a short-lived authorization code for tokens on the backend, keeping tokens out of the browser entirely. Ideal for SaaS dashboards and server-rendered applications.

Authorization Code + PKCE

An extension of the authorization code flow designed for clients that can't keep secrets — like single-page apps and mobile apps. PKCE (Proof Key for Code Exchange) adds a cryptographic challenge that binds the authorization request to the token request, preventing interception attacks. This is now the recommended default for any public client.

Client Credentials

Used when no user is involved. The application authenticates with its own credentials and receives a token representing itself. This is the standard flow for service-to-service communication, background jobs, and internal platform APIs.

Device Authorization Flow

Designed for devices with limited input capabilities — smart TVs, IoT devices, CLI tools. The user completes authentication on a separate device by visiting a URL and entering a code.

Refresh Tokens

Not a standalone flow, but a critical companion to the others. Refresh tokens let applications obtain new access tokens without forcing the user to sign in again, enabling long-lived sessions while keeping access tokens short-lived.

Five Mistakes That Trip Up SaaS Teams

1. Building it all from scratch

Implementing an authorization server, token lifecycle management, scope enforcement, and OIDC compliance is a significant engineering investment — and a risky one if security isn't your team's core expertise. Managed identity platforms exist precisely to solve this problem reliably.

2. Overly broad scopes

A scope called admin that grants access to everything defeats the purpose of scoped authorization. Use granular scopes like read:products and write:orders. If a token is compromised, the blast radius stays contained.

3. Long-lived access tokens

Access tokens should expire in minutes, not hours or days. A typical lifetime is 5 to 60 minutes. Refresh tokens handle renewal. Short-lived tokens limit the damage window if one is leaked.

4. Missing audience restrictions

Tokens should specify which API they're intended for. Without audience validation, a token issued for your billing API could be replayed against your admin API. Always set and validate the aud claim.

5. Treating login as authorization

A successful user login doesn't mean every API should accept every request. APIs should still validate audience, scopes, and token type independently. Authentication tells you who someone is; authorization tells you what they're allowed to do.

Where to Go From Here

OAuth has become the standard authorization model for modern SaaS platforms. It gives teams a consistent, secure way to protect APIs, enable integrations, and manage access across users, applications, and services.

Getting it right means choosing the correct flows for your client types, designing granular scopes, keeping tokens short-lived, and validating them properly at every API boundary.

If you'd rather focus on building your product than managing OAuth infrastructure, MonoCloud provides a complete authentication and authorization platform built for SaaS — handling OAuth, OIDC, user management, and access control so your team doesn't have to build and maintain it from scratch.

Add Authentication to Next.js With One Line of Code

MonoCloud Admin — Tue, 17 Mar 2026 20:53:56 +0000

export default authMiddleware()

That’s it. One line in your middleware file and your Next.js app has authentication — sign-up, sign-in, sign-out, session management, and protected routes. No wrestling with JWTs, no hand-rolling session logic, no third-party cookie headaches. Just drop it in and move on.

We built MonoGrub, a sample food ordering app, to show what this looks like in a real project. It’s open source, runs locally in five minutes, and covers the auth patterns you’ll actually need in production. Let’s walk through what it does.

One Line, Full Auth

When you call authMiddleware(), MonoCloud handles the entire OpenID Connect flow behind the scenes — redirects, token exchange, cookie-based sessions, silent refresh. Your users get a polished sign-up and sign-in experience, and you don't write a single line of auth plumbing.

But the real power shows up when you need more control. Want to lock down your admin section to a specific group of users? Pass a config:

export default authMiddleware({
  protectedRoutes: [
    { routes: ["/admin"], groups: ["admin"] }
  ],
});

That’s role-based access control, declared at the middleware layer, with zero custom logic in your page components. Add more routes, more groups, more rules — it’s all configuration, not code. By default, unauthorized users get a 403. Want something friendlier? Add an onGroupAccessDenied handler to redirect them wherever you like — MonoGrub sends them to a custom access-denied page.

Protecting Routes, APIs and UI

Authentication tells you who someone is. But most apps need to go further — you need to control what they can do. MonoGrub demonstrates this across every layer of a Next.js app.

Server Actions — Every sensitive operation in MonoGrub starts with a call to protect(). This validates the user's session server-side before any business logic runs. If the session is expired or invalid, the user is redirected to the sign-in page. No ambiguity, no race conditions.

API Routes — MonoGrub’s API endpoints use a protectApi() helper that gates access by auth status or group membership. The user's identity comes from the server-side session — not from anything the client submits — which eliminates an entire class of spoofing vulnerabilities.

Pages — For pages that require authentication, MonoGrub wraps them with protectPage(). If an unauthenticated user tries to access a protected page, they're automatically redirected to sign in — no manual checks or redirect logic needed in your component.

UI Components — Not everything needs a full page redirect. MonoGrub uses the client-side <Protected> component to conditionally render UI based on auth status. For example, the "Place Order" button is wrapped in <Protected> with a fallback that prompts the user to sign in. Authenticated users see the button; everyone else sees a sign-in prompt — no useEffect, no loading flicker, no auth state wiring.

The pattern is consistent: declare your access rules up front, and let MonoCloud enforce them. Your application code stays focused on what it’s actually supposed to do.

Profile Management, Without a User Table

Once your users are signed in, they’ll want to manage their accounts. MonoGrub handles profile updates — name changes, password resets — entirely through MonoCloud’s Management SDK. There’s no custom user table to maintain, no password hashing to get right, no “forgot password” flow to build from scratch.

Updating a user’s name is a single SDK call. Changing a password is another. After any update, we refresh the session so the UI stays in sync.

This is the kind of feature that’s easy to underestimate. It’s not glamorous, but building it from scratch is months of work you’ll never get back. With MonoCloud, it’s already done.

What MonoGrub Covers

To recap, here’s what you’ll find in the sample app:

Sign-up, sign-in, sign-out powered by MonoCloud’s OIDC flow
Route protection via middleware — both auth-required and role-required
Admin dashboard gated by group membership
Profile management using the Management SDK (name updates, password changes)
Protected API routes with server-side identity verification
Role-based UI — the navbar adapts based on the user’s group membership

Get It Running

Clone the repo, create a free MonoCloud account, add your credentials, and start the dev server:

git clone https://github.com/monocloud/monogrub-nextjs-demo.git
cd monogrub-nextjs-demo
npm install

Create a .env.local file in the project root with your MonoCloud credentials:

MONOCLOUD_AUTH_TENANT_DOMAIN=<your-tenant-domain>
MONOCLOUD_AUTH_CLIENT_ID=<your-client-id>
MONOCLOUD_AUTH_CLIENT_SECRET=<your-client-secret>
MONOCLOUD_AUTH_SCOPES=openid profile email groups
MONOCLOUD_AUTH_APP_URL=http://localhost:3000
MONOCLOUD_AUTH_COOKIE_SECRET=<your-cookie-secret>
MONOCLOUD_AUTH_REFETCH_USER_INFO=true
MONOCLOUD_AUTH_REFETCH_STRICT_PROFILE_SYNC=true
MONOCLOUD_API_KEY=<your-monocloud-api-key>

Then fire it up:

npm run dev

Open http://localhost:3000, and you’ve got a fully authenticated app running locally.

Ship Auth, Don’t Build It

Every hour you spend building authentication is an hour you’re not spending on your product. MonoCloud gives you production-grade auth with minimal integration effort — start with one line of middleware, and scale up to protected routes, RBAC, and user management as you need them.

Explore the source, adapt the patterns, and ship.

Want to dig deeper? Start with the MonoCloud Docs, explore the Management SDK, or clone MonoGrub and start hacking.