Skip to main content

MongoDB

MongoDB is a document-oriented NoSQL database platform that provides flexible schema design, powerful querying capabilities, and horizontal scalability. MongoDB Atlas is the fully-managed cloud database service.

This connector provides comprehensive access to both Atlas management operations (cluster management, user administration, backups, monitoring) and database operations (CRUD, queries, aggregations, indexes).

Authentication Types​

MongoDB supports 1 authentication method:

  • OAuth 2.0 (Client Credentials) - Uses Atlas service accounts for API authentication. Secure, automated access for managing Atlas resources and databases.
    • Pros: Secure, no password rotation needed, production-ready, supports programmatic access
    • Cons: Requires Atlas organization or project admin access to create service accounts
    • Best for: Automated workflows, CI/CD pipelines, production deployments, application integrations

General Settings​

Before using the connector, you need to configure:

  • Atlas Project ID - The unique identifier for your MongoDB Atlas project (also called Group ID). Find this in the Atlas UI under Project Settings.
  • Connection String - MongoDB connection string for database operations. Format: mongodb+srv://username:[email protected]/database

Setting up OAuth 2.0​

MongoDB Atlas uses service accounts for OAuth 2.0 authentication. Follow these steps:

1. Create a Service Account​

  1. Log in to MongoDB Atlas

  2. Navigate to Organization Settings or Project Settings (depending on desired scope)

  3. Click Service Accounts in the left sidebar

  4. Click Create Service Account

  5. Enter a descriptive name (e.g., "Webrix Integration")

  6. Assign appropriate roles:

    • For full management access: Project Owner
    • For database access only: Project Data Access Admin
    • For read-only access: Project Read Only

  7. Click Create

  8. Copy the Client ID and Client Secret immediately - the secret will not be shown again

    tip

    Store these credentials securely. If you lose the secret, you'll need to regenerate it, which will invalidate the old credentials.

  1. In your Atlas project, go to Network Access

  2. Click Add IP Address

  3. Add the IP addresses or CIDR blocks that will access your databases:

    • For Webrix cloud: Add Webrix's IP addresses (provided in the platform)
    • For development: Add your local IP or use 0.0.0.0/0 (not recommended for production)

  4. Add a comment to identify the purpose (e.g., "Webrix Integration")

  5. Click Confirm

3. Get Your Project ID​

  1. In Atlas, navigate to your project

  2. Click Settings in the left sidebar

  3. Copy the Project ID (also shown as Group ID in some places)

    Example: 507f1f77bcf86cd799439011

4. Get Your Connection String​

  1. In your Atlas project, go to Database (Clusters view)

  2. Click Connect on your cluster

  3. Choose Connect your application

  4. Select your driver (e.g., Node.js, Python)

  5. Copy the connection string - it should look like:

    mongodb+srv://username:[email protected]/?retryWrites=true&w=majority

  6. Replace username and password with your database user credentials (not your Atlas login)

    tip

    If you don't have a database user yet, create one:

    • Go to Database Access in Atlas
    • Click Add New Database User
    • Choose authentication method (usually SCRAM)
    • Set username and password
    • Assign appropriate database roles (readWrite, readAnyDatabase, etc.)

5. Configure in Webrix​

  1. In Webrix, go to Integrations → New → Built-in

  2. Select MongoDB and click Use

  3. Under Authentication Type, it will automatically use OAuth 2.0 (Client Credentials)

  4. Enter your credentials:

    • Client ID: Paste the service account Client ID from step 1
    • Client Secret: Paste the service account Client Secret from step 1

  5. Under General Settings:

    • Atlas Project ID: Paste your project ID from step 3
    • Connection String: Paste your connection string from step 4

  6. Click Save Changes

6. Test the Connection​

After saving, the integration will automatically authenticate using OAuth 2.0 and you can start using MongoDB tools.

Common Use Cases​

Cluster Management​

  • List and monitor all clusters in your project
  • Create new clusters for development or production
  • Scale clusters up or down by changing instance sizes
  • Pause clusters during non-usage periods to save costs
  • Test failover to verify high availability

Database User Management​

  • Create database users with specific roles and permissions
  • Update user roles and passwords
  • Scope users to specific clusters for enhanced security
  • Delete users when access is no longer needed

Data Operations​

  • Query documents with complex filters and aggregations
  • Insert, update, and delete documents
  • Create and manage collections
  • Build aggregation pipelines for analytics
  • Get collection statistics and monitor data growth

Index Management​

  • List all indexes on collections
  • Create indexes to improve query performance
  • Create Atlas Search indexes for full-text search
  • Drop unused indexes to improve write performance

Backup & Recovery​

  • List all available snapshots
  • Create on-demand snapshots before major changes
  • Restore data from snapshots to the same or different cluster
  • Monitor restore job progress

Monitoring & Alerts​

  • Configure alert rules for CPU, memory, disk space, connections
  • List active alerts and their status
  • Acknowledge alerts during incident response
  • Set up notifications for proactive monitoring

Troubleshooting​

"Unauthorized" or "Invalid Access Token" Error​

Cause: The OAuth token may have expired, or the service account credentials are incorrect.

Solution:

  1. Verify that the Client ID and Client Secret are correct
  2. Check that the service account hasn't been deleted or disabled in Atlas
  3. Ensure the service account has appropriate roles assigned
  4. Try regenerating the service account secret in Atlas and updating it in Webrix

"Project Not Found" Error​

Cause: The Project ID is incorrect, or the service account doesn't have access to the project.

Solution:

  1. Verify the Project ID is correct - check Atlas Project Settings
  2. Ensure the service account is created at the organization level and has project access, or is created within the specific project
  3. Check that the service account role includes the target project

Connection String Authentication Failed​

Cause: Database user credentials in the connection string are incorrect, or the user doesn't exist.

Solution:

  1. Verify the username and password in the connection string are correct
  2. Check that the database user exists in Database Access in Atlas
  3. Ensure the user has appropriate roles for the databases you're accessing
  4. Verify the authentication database (usually admin for SCRAM users)
  5. Check that the user isn't restricted to specific IP addresses

IP Access List Blocking Connections​

Cause: The IP address attempting to connect is not in the project's IP access list.

Solution:

  1. Go to Network Access in Atlas
  2. Add the IP address or CIDR block that needs access
  3. For Webrix cloud, add the IP addresses provided by Webrix
  4. Remember: IP access list changes take a few moments to propagate

"Cluster Not Found" Error for Data Operations​

Cause: The connection string points to a non-existent cluster, or the cluster name is misspelled.

Solution:

  1. Verify the cluster name in the connection string matches the cluster name in Atlas
  2. Check that the cluster is in a running state (not paused or terminated)
  3. Ensure the cluster is in the correct project

Rate Limiting​

Cause: MongoDB Atlas enforces API rate limits (100 requests per minute per project for most endpoints).

Solution:

  1. Implement retry logic with exponential backoff
  2. Batch operations where possible
  3. For data operations, use aggregation pipelines instead of multiple queries
  4. Monitor your API usage in Atlas Project Settings

Atlas Search Index Not Available​

Cause: Atlas Search is only available on M10+ clusters (not M0, M2, M5 free/shared tiers).

Solution:

  1. Verify your cluster tier - go to Atlas and check cluster configuration
  2. Upgrade to M10 or higher if you need Atlas Search functionality
  3. Use regular indexes and MongoDB's text search operators as an alternative on smaller tiers

Token Expiration​

Note: OAuth tokens expire after 1 hour. The connector automatically refreshes tokens as needed, but if you see intermittent authentication errors, this is normal behavior during token refresh.

MongoDB Connection String Format​

Connection strings support various formats and options:

Standard format:

mongodb+srv://username:[email protected]/database?options

Direct connection (without SRV):

mongodb://username:password@host1:27017,host2:27017/database?replicaSet=rs0

Common options:

  • retryWrites=true - Automatically retry write operations
  • w=majority - Wait for majority acknowledgment
  • authSource=admin - Specify authentication database
  • ssl=true - Enable SSL/TLS connection

Additional Resources​