monocloud-management-js

MonoCloud Management JS SDK (@monocloud/management)

Typed JavaScript / TypeScript SDK for the MonoCloud Management API. Use it to programmatically manage users, applications, groups, API resources, sign-in options, branding, logs, keys, and trust stores in a MonoCloud tenant.

Package identity — read this first

Use: @monocloud/management (this skill).

This is not the same SDK as:

• @monocloud/auth-nextjs — frontend user sessions (different skill: monocloud-auth-nextjs).
• @monocloud/backend-node — API token validation (different skills: monocloud-auth-express, monocloud-auth-fastify).

If you see imports from @monocloud/management-core directly, that's the internal core package — applications should import from @monocloud/management. The core types (MonoCloudConfig, MonoCloudResponse, MonoCloudException, etc.) are re-exported from @monocloud/management.

Installation

npm install @monocloud/management

Supported Node.js: >= 11.0.0.

Authentication — Management API key

You need a Management API key generated in the MonoCloud dashboard (Settings → API Keys). Treat it like a root credential:

• Never ship it to a browser or commit it to source control.
• Always read it from process.env.
• A management key is tenant-scoped and has full admin permissions.

Environment variables (and config keys)

The SDK can be configured by environment variables or explicit options. Options always win.

Env var	Option	Required?	Purpose
MC_MANAGEMENT_DOMAIN	domain	yes	Tenant URL, e.g. https://acme.us.monocloud.app
MC_MANAGEMENT_API_KEY	apiKey	yes	Management API key
MC_MANAGEMENT_TIMEOUT	config.timeout	no	Per-request timeout in milliseconds

The domain value should be the bare tenant URL (no /api, no trailing slash). The SDK appends /api/... internally.

Quick start — env-driven

import { MonoCloudManagementClient } from '@monocloud/management';

// Reads MC_MANAGEMENT_DOMAIN and MC_MANAGEMENT_API_KEY from process.env.
const management = MonoCloudManagementClient.init();

const { result, status, pageData } = await management.users.getAllUsers(1, 25);
console.log(`Page ${pageData?.current_page} of ${pageData?.total_count} users`);
for (const user of result) console.log(user.id, user.username);

Quick start — explicit options

import { MonoCloudManagementClient } from '@monocloud/management';

const management = MonoCloudManagementClient.init({
  domain: process.env.MC_MANAGEMENT_DOMAIN!,
  apiKey: process.env.MC_MANAGEMENT_API_KEY!,
  config: { timeout: 30_000 }, // optional, milliseconds
});

Never inline the API key as a string literal. Always read from process.env (or an equivalent secret store).

Client surface

MonoCloudManagementClient exposes one property per Management API resource area:

Property	Resource	Source file (in this SDK)
.branding	BrandingClient	clients/branding-api.ts
.clients	ClientsClient (OAuth applications)	clients/clients-api.ts
.groups	GroupsClient	clients/groups-api.ts
.keys	KeysClient	clients/keys-api.ts
.logs	LogsClient	clients/logs-api.ts
.options	OptionsClient (tenant settings)	clients/options-api.ts
.resources	ResourcesClient (API resources)	clients/resources-api.ts
.trustStores	TrustStoresClient	clients/trust-stores-api.ts
.users	UsersClient	clients/users-api.ts

Each resource client method returns Promise<MonoCloudResponse<T>> (or Promise<MonoCloudPageResponse<T>> for paginated lists). The response object always has .result, .status, and (for paginated calls) .pageData.

See references/api-surface.md for the full method-by-method surface.

Response shape

interface MonoCloudResponse<T> {
  result: T;
  status: number;
  headers: Record<string, string>;
}

interface MonoCloudPageResponse<T> extends MonoCloudResponse<T> {
  pageData?: {
    total_count: number;
    page_size: number;
    current_page: number;
    has_next: boolean;
    has_previous: boolean;
  };
}

Pagination metadata is returned in the X-Pagination response header and parsed onto pageData.

Pagination — idiomatic loop

async function eachUser(client: MonoCloudManagementClient) {
  let page = 1;
  while (true) {
    const { result, pageData } = await client.users.getAllUsers(page, 100);
    for (const u of result) yield u;
    if (!pageData?.has_next) break;
    page += 1;
  }
}

Most list endpoints accept (page, size, filter, sort):

• page — 1-indexed.
• size — items per page.
• filter — Lucene-style expression (varies per endpoint; see API reference).
• sort — "<field>:<1 | -1>" (1 = asc, -1 = desc).

Common operations

Create a user

const { result: user } = await management.users.createUser({
  name: 'Alice Example',
  // see CreateUserRequest in the SDK types for all fields
});

Patch user metadata

await management.users.patchPrivateData(user.id, {
  private_data: { onboarded: true, plan: 'pro' },
});

await management.users.patchPublicData(user.id, {
  public_data: { display_name: 'Alice' },
});

patch* requests send only the fields you include. To clear a field, send null explicitly — the SDK preserves nulls.

Look up a user

try {
  const { result: user } = await management.users.findUserById(id);
  return user;
} catch (e) {
  if (e instanceof MonoCloudNotFoundException) return null;
  throw e;
}

List clients (applications)

const { result: clients, pageData } = await management.clients.getAllClients(1, 50);

Logs

const { result: logs } = await management.logs.getLogs(/* params */);

Errors

Every non-2xx response throws a typed exception that extends MonoCloudException:

Class	Thrown for
MonoCloudBadRequestException	400 with model state
MonoCloudUnauthorizedException	401 (bad / missing API key)
MonoCloudPaymentRequiredException	402
MonoCloudForbiddenException	403
MonoCloudNotFoundException	404
MonoCloudConflictException	409
MonoCloudIdentityValidationException	422 with identity validation errors
MonoCloudKeyValidationException	422 with key validation errors
MonoCloudModelStateException	422 with model-state validation errors
MonoCloudResourceExhaustedException	429
MonoCloudServerException	5xx
MonoCloudRequestException	network / non-HTTP failure
MonoCloudException	base class — catch-all

Always catch the most specific you care about; fall through to MonoCloudException for unexpected cases.

import {
  MonoCloudConflictException,
  MonoCloudIdentityValidationException,
  MonoCloudException,
} from '@monocloud/management';

try {
  await management.users.createUser({ name });
} catch (e) {
  if (e instanceof MonoCloudConflictException) return reply.code(409).send({ error: 'duplicate' });
  if (e instanceof MonoCloudIdentityValidationException) return reply.code(422).send({ errors: e.errors });
  if (e instanceof MonoCloudException) {
    request.log.error({ err: e, status: e.statusCode }, 'MonoCloud Management API call failed');
    throw e;
  }
  throw e;
}

Replacing the HTTP layer (optional)

MonoCloudManagementClient.init(options, fetcher?) accepts a second arg implementing the Fetcher interface from @monocloud/management. Use it to plug in a custom fetch (e.g. for tests, retries, or a non-Node runtime). For production code, prefer the built-in fetcher and configure timeouts via config.timeout.

Common pitfalls

1. Putting the API key in browser code. Management keys are full-tenant admin. They must only run server-side.
2. Trailing /api/v1 on domain. Pass the bare tenant URL — the SDK appends paths.
3. Confusing private_data and public_data. Public data is exposed in user-facing tokens; private is admin-only. Both are arbitrary JSON.
4. Treating patch* as put*. Patch is merge: fields you don't include are left alone. Set a field to null to clear it; omit it to leave unchanged.
5. Catching Error instead of MonoCloudException. The typed hierarchy lets you branch on status (404 vs 409 vs 422) without parsing strings.
6. Forgetting pagination. getAll* returns the first page by default. Loop using pageData.has_next.

Onboarding checklist

1. npm install @monocloud/management.
2. Create a Management API key in the MonoCloud dashboard.
3. Set MC_MANAGEMENT_DOMAIN and MC_MANAGEMENT_API_KEY (in a server-only env file, .gitignored).
4. import { MonoCloudManagementClient } from '@monocloud/management'; create one shared client with init() and reuse it.
5. Wrap calls in try/catch against the specific MonoCloudException subclasses you expect.
6. Run node skills/monocloud-management-js/scripts/verify.js to confirm env + dependency wiring.

Deeper reference

• references/api-surface.md — resource-by-resource method index and request/response shapes.
• references/troubleshooting.md — symptom → cause → fix index for the most common failure modes (401s, domain /api duplication, browser-side key leaks, patch* merge semantics, generic catch (Error), single-page reads, millisecond vs seconds timeouts).