MongoDB Atlas Admin SDK

Type-safe TypeScript SDK for the MongoDB Atlas Administration API v2. Programmatically manage Atlas projects, clusters, organizations, alerts, and more.

Please Note

This SDK has been generated using the Atlas Admin OpenAPI spec. It is not officially supported by MongoDB. It is currently developed and maintained by Code Capsules.

Features

• Fully generated — Clients generated from the Atlas Admin OpenAPI spec for complete API coverage
• Type-safe — Strongly typed request options and response models with full IntelliSense support
• Multiple auth methods — OAuth2 service account authentication and Digest (API key) authentication
• JSDoc on API methods — Inline documentation for better developer experience

Installation

npm install @codecapsules/mongodb-atlas-admin-sdk

Quick Start

OAuth2 (recommended)

Use Atlas API keys with OAuth2 for production applications:

import { AtlasAdminClient } from "@codecapsules/mongodb-atlas-admin-sdk";

const client = new AtlasAdminClient({
  auth: {
    type: "oauth2",
    config: {
      clientId: process.env.MONGODB_ATLAS_CLIENT_ID!,
      clientSecret: process.env.MONGODB_ATLAS_CLIENT_SECRET!,
    },
  },
});

const status = await client.root.getSystemStatus();
console.log(status);

const projects = await client.projects.listGroups({
  query: { itemsPerPage: 10, includeCount: true },
});
console.log(projects.results);

Digest auth (Atlas API keys)

Use Atlas API keys for simpler setups:

import { AtlasAdminClient } from "@codecapsules/mongodb-atlas-admin-sdk";

const client = new AtlasAdminClient({
  auth: {
    type: "digest",
    config: {
      publicKey: process.env.MONGODB_ATLAS_PUBLIC_KEY!,
      privateKey: process.env.MONGODB_ATLAS_PRIVATE_KEY!,
    },
  },
});

const status = await client.root.getSystemStatus();
console.log(status);

API Structure

All API methods use a single options object. Path parameters, query parameters, and request bodies are passed via named fields:

const clusters = await client.clusters.listGroupClusters({
  groupId: "64f1f3fd9f0f0f0f0f0f0f0f",
  query: { itemsPerPage: 5, includeCount: true },
});

Client groups

The main client exposes API groups aligned with Atlas resource types:

| Group | Description | | ---------------------------- | ----------------------------- | | client.root | System status, root endpoints | | client.projects | Projects (groups) | | client.clusters | Clusters | | client.flexClusters | Flex clusters | | client.events | Atlas events | | client.organizations | Organizations | | client.alertConfigurations | Alert configurations | | client.streams | Atlas Streams |

Configuration

const client = new AtlasAdminClient({
  auth: {
    type: "oauth2",
    config: {
      clientId: "your-client-id",
      clientSecret: "your-client-secret",
    },
  },
  baseURL: "https://cloud.mongodb.com/api/atlas/v2", // default
  timeout: 30000, // default, in ms
  defaultHeaders: {
    "X-Custom-Header": "example",
  },
});

Error handling

The SDK throws AtlasError for non-2xx responses:

import { AtlasAdminClient, AtlasError } from "@codecapsules/mongodb-atlas-admin-sdk";

try {
  await client.projects.getGroup({ groupId: "invalid" });
} catch (error) {
  if (error instanceof AtlasError) {
    console.error(error.statusCode, error.endpoint, error.message);
  }
}

Advanced usage

Access the underlying HTTP client for custom requests:

const httpClient = client.getHttpClient();
const response = await httpClient.get("/groups");
console.log(response.data);

Requirements

• Node.js >= 18.0.0

Links

• MongoDB Atlas Documentation
• Atlas Administration API Reference
• MongoDB Support

License

MIT