Install and set up the MonoCloud Backend Node SDK

This guide shows how to install the MonoCloud Backend Node SDK and configure your Fastify API with MonoCloud.

By the end of this guide, you will have:

Your API configured in the MonoCloud Dashboard
The SDK installed in your Fastify project
Environment variables configured for token validation

If you already have a MonoCloud account and API, skip ahead to Install the SDK.

Create a MonoCloud account

If you don’t have an account yet, sign up at: https://www.monocloud.com

Create an API

In the MonoCloud Dashboard:

Click Add API
Set the Audience (for example https://api.example.com) — this uniquely identifies your API
Add any scopes your API requires (for example read, write)

Each API represents a single resource server secured by MonoCloud.

Install the SDK

Install the MonoCloud Backend Node SDK using your package manager:

Terminal

npm install @monocloud/backend-node

Node.js 18 or later is required.

Configure environment variables

The SDK reads configuration from environment variables prefixed with MONOCLOUD_BACKEND_.

Create a .env file in your project root:

.env

MONOCLOUD_BACKEND_TENANT_DOMAIN=https://<your-domain>
MONOCLOUD_BACKEND_AUDIENCE=https://<your-api-audience>

Where to find these values

Environment variable	Where to find the value in MonoCloud
`MONOCLOUD_BACKEND_TENANT_DOMAIN`	Domain from your tenant or API settings
`MONOCLOUD_BACKEND_AUDIENCE`	Audience from the API settings

Additional environment variables

Only required when using token introspection for opaque tokens:

.env

MONOCLOUD_BACKEND_CLIENT_ID=<your-client-id>
MONOCLOUD_BACKEND_CLIENT_SECRET=<your-client-secret>

Protect your API

Once environment variables are set, use protectApi() to protect your routes:

src/server.ts

import "dotenv/config";
import Fastify from "fastify";
import { protectApi } from "@monocloud/backend-node/fastify";

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

app.addHook("onRequest", protect());

app.get("/api/data", async () => {
  return { message: "Protected data" };
});

app.listen({ port: 3000 }, (err) => {
  if (err) throw err;
  console.log("Server running on http://localhost:3000");
});

protectApi() automatically reads configuration from environment variables. No additional setup is required.

Environment variable reference

Environment variable	Description	Required
`MONOCLOUD_BACKEND_TENANT_DOMAIN`	Your MonoCloud tenant domain URL	Yes
`MONOCLOUD_BACKEND_AUDIENCE`	The expected audience for token validation	Yes
`MONOCLOUD_BACKEND_CLIENT_ID`	Client ID (for token introspection)	No
`MONOCLOUD_BACKEND_CLIENT_SECRET`	Client secret (for token introspection)	No
`MONOCLOUD_BACKEND_CLIENT_AUTH_METHOD`	Client authentication method	No
`MONOCLOUD_BACKEND_CLOCK_SKEW`	Allowed clock drift in seconds	No
`MONOCLOUD_BACKEND_CLOCK_TOLERANCE`	Time tolerance for claim validation in seconds	No
`MONOCLOUD_BACKEND_INTROSPECT_JWT_TOKENS`	When `true`, JWT tokens are also introspected instead of only being validated locally	No
`MONOCLOUD_BACKEND_GROUPS_CLAIM`	Token claim name containing group memberships	No
`MONOCLOUD_BACKEND_GROUPS_MATCH_ALL`	When `true`, requires all specified groups to be present	No
`MONOCLOUD_BACKEND_JWKS_CACHE_DURATION`	JWKS cache duration in seconds	No
`MONOCLOUD_BACKEND_METADATA_CACHE_DURATION`	OIDC metadata cache duration in seconds	No

Next steps

Explore advanced protection patterns: