×

Welcome to Knowledge Base!

KB at your finger tips

This is one stop global knowledge base where you can learn about all the products, solutions and support features.

Categories
All
Database-MongoDB
Cloud Manager Administration API Error Codes — MongoDB Cloud Manager

Cloud Manager Administration API Error Codes¶

Note

Groups and projects are synonymous terms. Your {PROJECT-ID} is the same as your project id. For existing groups, your group/project id remains the same. This page uses the more familiar term group when referring to descriptions. The endpoint remains as stated in the document.

If you encounter an error when issuing a request to the Cloud Manager Administration API, Cloud Manager returns one of the following error codes:

Error HTTP Code Description
ACCOUNT_SUSPENDED
402 Group has an unpaid invoice that is more than 30 days old.
ACKNOWLEDGEMENT_COMMENT_TOO_LONG
400 Acknowledgement comment too long. It must not exceed <number> characters.
ADDRESS_ALREADY_IN_WHITELIST
409 The address <address> is already on the whitelist.
ALERT_CONFIG_NOT_FOUND
404 No alert configuration with ID <ID> exists in group <group> .
ALERT_NOT_FOUND
404 No alert with ID <ID> exists in group <group> .
API_KEY_CANNOT_CREATE_GROUP
401 API Keys cannot create groups .
API_KEY_CANNOT_CREATE_ORG
401 API Keys cannot create organizations .
API_KEY_NOT_FOUND
400 No API Key with ID {API-KEY-ID} exists.
API_KEY_WHITELIST_ACCESS_DENIED
400 API Key whitelists are only accessible by the API Key itself or by a user administrator.
API_KEY_WHITELIST_NOT_FOUND
404 The specified IP address does not exist in the corresponding API Key whitelist.
ATTRIBUTE_NEGATIVE_OR_ZERO
400 The attribute <attribute> cannot be negative or zero.
ATTRIBUTE_NEGATIVE
400 The attribute <attribute> cannot be negative.
ATTRIBUTE_READ_ONLY
400 The attribute <attribute> is read-only and cannot be changed by the user.
AUTH_MECHANISM_REQUIRES_SSL
400 Authentication mechanism <mechanism> requires SSL.
AUTOMATION_CONFIG_NOT_FOUND
404 No automation configuration exists for group <group> .
BACKUP_CONFIG_NOT_FOUND
404 No backup configuration exists for cluster <cluster> in group <group> .
BAD_USERNAME_IN_GROUP_REF
400 User <username> is not in group <group> .
BAD_USERNAME_REF
400 No user with username <username> exists.
BAD_WHITELIST_ADD_REQUEST
400 Should not specify both the IP address and the CIDR block.
BLOCKED_USERNAME
400 The specified username <username> is not allowed.
CANNOT_ADD_IP_ADDRESS_TO_API_KEY_WHITELIST
400 The specified address cannot be added to whitelists. Cloud Manager does not allow certain IP addresses to be whitelisted, such as 0.0.0.0/32 .
CANNOT_ADD_GLOBAL_ROLE
403 Adding a global role is not supported.
CANNOT_CHANGE_GROUP_NAME
403 Current user is not authorized to change group name.
CANNOT_CLOSE_ACCOUNT_ACTIVE_BACKUP
409 Cannot close account while the group has active backups; please terminate all backups.
CANNOT_CLOSE_ACCOUNT_FAILED_INVOICES
402 Cannot close account because there are failed invoices.
CANNOT_DELETE_FROM_CLUSTER_SNAPSHOT
403 Cannot individually delete a snapshot that is part of a cluster snapshot.
CANNOT_DELETE_LAST_OWNER
403 Cannot remove the last owner from the group. If you are trying to close the group by removing all users, please delete the group instead.
CANNOT_DEMOTE_LAST_ORG_OWNER
403 Cannot demote the last owner of the organization.
CANNOT_DEMOTE_LAST_OWNER
403 Cannot demote the last owner of the group.
CANNOT_DISTRIBUTE_SUBNETS
400 Cannot distribute subnets. There must be at least one subnet available.
CANNOT_DOWNLOAD_EXPIRED_JOB
403 Cannot download a log collection request job in the EXPIRED state.
CANNOT_DOWNLOAD_JOB_IN_PROGRESS
403 Cannot download a log collection request job in the IN_PROGRESS state.
CANNOT_EXTEND_EXPIRED_JOB
403 Cannot extend duration of logs that have already expired.
CANNOT_GET_BACKUP_CONFIG_INVALID_STATE
409 Cannot get backup configuration without cluster being monitored.
CANNOT_GET_VOLUME_SIZE_LIMITS
500 Cannot get volume size limits for volume type <type> .
CANNOT_MODIFY_MANAGED_HOST
403 Cannot modify host <host> because it is managed by Automation.
CANNOT_MODIFY_SHARD_BACKUP_CONFIG
409 Cannot modify backup configuration for individual shard; use cluster ID <ID> for entire cluster.
CANNOT_REMOVE_CALLER_FROM_WHITELIST
400 Cannot remove caller’s IP address <address> from whitelist.
CANNOT_SET_BACKUP_AUTH_FOR_MANAGED_CLUSTER
409 Username and password cannot be manually set for a managed cluster.
CANNOT_SET_CLUSTER_CHECKPOINT_INTERVAL_FOR_REPLICA_SET
400 Cluster checkpoint interval can only be set for sharded clusters, not replica sets.
CANNOT_SET_CREDENTIALS_FOR_AUTH_MECHANISM
400 Username and password fields are only supported for authentication mechanism MONGODB_CR or PLAIN .
CANNOT_SET_PASSWORD_FOR_AUTH_MECHANISM
400 Cannot change password unless authentication mechanism is MONGODB_CR or PLAIN .
CANNOT_SET_POINT_IN_TIME_WINDOW
400 Setting the point in time window is not allowed.
CANNOT_SET_REF_TIME_OF_DAY
400 Setting the reference point time of day is not allowed.
CANNOT_START_BACKUP_INVALID_STATE
409 Cannot start backup unless the cluster is in the INACTIVE or STOPPED state.
CANNOT_START_BACKUP_NO_BILLING_INFO
402 Cannot start backup without providing billing information.
CANNOT_START_RESTORE_JOB_FOR_DELETED_CLUSTER_SNAPSHOT
409 Cannot start restore job for deleted cluster snapshot.
CANNOT_START_RESTORE_JOB_FOR_DELETED_SNAPSHOT
409 Cannot start restore job for deleted snapshot.
CANNOT_START_RESTORE_JOB_FOR_INCOMPLETE_CLUSTER_SNAPSHOT
409 Cannot start restore job for incomplete cluster snapshot.
CANNOT_STOP_BACKUP_INVALID_STATE
409 Cannot stop backup unless the cluster is in the STARTED state.
CANNOT_TERMINATE_BACKUP_INVALID_STATE
409 Cannot terminate backup unless the cluster is in the STOPPED state.
CHECKPOINT_NOT_FOUND
404 No checkpoint with ID <ID> exists for cluster <cluster> .
CLUSTER_NOT_FOUND
404 No cluster with ID <ID> exists in group <group> .
CONFIG_RESTORE_JOB_NOT_FOUND
404 No restore job with ID <ID> exists for config server <config server> .
CONFIG_SNAPSHOT_NOT_FOUND
404 No snapshot with ID <ID> exists for config server <config server> .
DATABASE_NAME_REQUIRED
400 Metric <metric> requires a database name to be provided.
DATABASE_NOT_FOUND
404 No database with name <name> exists on host <host> .
DEFAULT_CONFIG_LIMIT_EXCEPTION
400 The limit check failed while trying to add the requested resource. Please try again.
DEFAULT_INVITATION_EXCEPTION
400 Failed to send an invitation to <username> to join <group> .
DEVICE_NAME_REQUIRED
400 Metric <metric> requires a device name to be provided.
DEVICE_NOT_FOUND
404 No device with name <name> exists on host <host> .
DOMAIN_NAME_TOO_LONG
400 The domain name for the machine is too long. Try shortening the hostname prefix.
DUPLICATE_ADDRESSES_IN_INPUT
400 Two or more of the IP addresses being added to the whitelist are the same.
EMAIL_OR_SMS_REQUIRED_FOR_GROUP_NOTIFICATION
400 Email and/or SMS must be enabled for group notifications.
EMAIL_OR_SMS_REQUIRED_FOR_USER_NOTIFICATION
400 Email and/or SMS must be enabled for user notifications.
EXPIRATION_DATE_MUST_BE_IN_FUTURE
400 Expiration date for log collection request job must be in the future.
EXPIRATION_DATE_TOO_DISTANT
400 Expiration date for log collection request job can only be as far as 6 months in the future.
FAILED_TO_CLOSE_ACCOUNT_CHARGE_FAILED
402 Cannot close account due to a charge failure.
FEATURE_UNSUPPORTED
403 Feature not supported by current account level.
FRACTIONAL_TIMESTAMP
400 Timestamp must be whole number of seconds.
GLOBAL_ALERTS_ONLY
400 The specified event type <type> can only be used for global alerts.
GROUP_ALREADY_EXISTS
409 A group with name <name> already exists.
GROUP_API_KEY_NOT_FOUND
404 No group with API Key <key> exists.
GROUP_MISMATCH
400 The specified group ID <ID> does not match the URL.
GROUP_NAME_NOT_FOUND
404 No group with name <name> exists.
GROUP_NOT_FOUND
404 No group with ID <ID> exists.
HOST_LAST_PING_NOT_FOUND
404 No last ping exists for host <host> in group <group> .
HOST_NOT_FOUND
404 No host with ID <ID> exists in group <group> .
HOSTNAME_AND_PORT_NOT_FOUND
404 No host with hostname and port <name:port> exists in group <group> .
INCORRECT_SECURITY_GROUP_COUNT
400 Instance must be created with exactly one SSH-enabled security group.
INVALID_AGENT_TYPE_NAME
400 An invalid agent type name <name> was specified.
INVALID_ALERT_CONFIG_ID
404 An invalid alert configuration ID <ID> was specified.
INVALID_ALERT_ID
404 An invalid alert ID <ID> was specified.
INVALID_ALERT_STATUS
400 An invalid alert status <status> was specified.
INVALID_ATTRIBUTE
400 Invalid attribute <attribute> specified.
INVALID_AUTH_MECHANISM
400 Invalid authentication mechanism <mechanism> .
INVALID_AUTH_TYPE_NAME
400 An invalid authentication type name <name> was specified.
INVALID_CHECKPOINT_ID
404 An invalid checkpoint ID <ID> was specified.
INVALID_CLUSTER_CHECKPOINT_INTERVAL
400 Cluster checkpoint interval must be 15, 30, or 60 minutes.
INVALID_CLUSTER_ID
404 An invalid cluster ID <ID> was specified.
INVALID_DAILY_SNAPSHOT_RETENTION_PERIOD
400 Daily snapshot retention period must be between 1 and 365 days.
INVALID_DIRECTORY
400 An invalid directory name <name> was specified.
INVALID_EMAIL_ADDRESS
400 An invalid email address was specified.
INVALID_ENUM_VALUE
400 An invalid enumeration value <value> was specified.
INVALID_EVENT_TYPE_FOR_ALERT
400 Event type <type> not supported for alerts.
INVALID_FILTERLIST
400 Backup configuration cannot specify both included namespaces and excluded namespaces.
INVALID_GRANULARITY
400 An invalid granularity <granularity> was specified.
INVALID_GROUP_ID
404 An invalid group ID <ID> was specified.
INVALID_GROUP_NAME_10GEN
400 Group name cannot contain “10gen-” or “-10gen”.
INVALID_GROUP_NAME
400 An invalid group name <name> was specified.
INVALID_GROUP_TOKEN
400 A group tag must be a string (alphanumeric, periods, underscores, and dashes) of length <MAX_TAG_LENGTH> characters or less.
INVALID_HOST_PORT
400 Invalid host port <number> .
INVALID_HOSTNAME_PREFIX
400 Invalid hostname prefix <prefix> . It must contain only alphanumeric characters and hyphens, may not begin or end with a hyphen (“-“), and must not be more than 63 characters long.
INVALID_HOSTNAME
400 Invalid hostname <name> .
INVALID_INSTANCE_COUNT
400 Invalid instance count <number> . It must be between <number> and <number> .
INVALID_INSTANCE_TYPE_NAME
400 Invalid instance type <type> . It must be one of the listed instance types returned in the machine configuration options.
INVALID_IOPS_INVALID_RATIO
400 The IOPS value <number> is not valid. The maximum ratio between the IOPS value and the volume size is 30 : 1.
INVALID_IOPS_OUT_OF_BOUNDS
400 The IOPS value <number> is not valid. It must be between the minimum and maximum values returned in the machine configuration options.
INVALID_JOB_ID
404 An invalid restore job ID <ID> was specified.
INVALID_JSON_ATTRIBUTE
400 Received JSON for the <attribute> attribute does not match expected format.
INVALID_JSON
400 Received JSON does not match expected format.
INVALID_KEY_ID
404 An invalid key ID <ID> was specified.
INVALID_LOG_REQUEST_SIZE
400 Log request size must be a positive number.
INVALID_MACHINE_ID
404 An invalid machine ID <ID> was specified.
INVALID_MACHINE_IMAGE
400 The specified machine image is invalid.
INVALID_METRIC_NAME
404 An invalid metric name <name> was specified.
INVALID_MONGODB_USERNAME
400 The username <username> is not a valid MongoDB login.
INVALID_MONTHLY_SNAPSHOT_RETENTION_PERIOD
400 Monthly snapshot retention period must be between 1 and 36 months.
INVALID_MOUNT_LOCATION
400 An invalid mount location <location> was specified. The mount location must be equal to or a parent of <location> .
INVALID_OPERATOR_FOR_EVENT_TYPE
400 Operator <operator> is not compatible with event type <type> .
INVALID_PERIOD
400 An invalid period was specified.
INVALID_PROVIDER_PARAMETERS
400 Invalid parameter combination specified for provider <provider> .
INVALID_QUERY_PARAMETER
400 Invalid query parameter <parameter> specified.
INVALID_REFERENCE_HOUR_OF_DAY
400 Snapshot schedule reference hour must be between 0 and 23, inclusive.
INVALID_REFERENCE_MINUTE_OF_HOUR
400 Snapshot schedule reference minute must be between 0 and 59, inclusive.
INVALID_REFERENCE_TIMEZONE_OFFSET
400 Snapshot schedule timezone offset must conform to ISO-8601 time offset format, such as “+0000”.
INVALID_REGION
400 No region <region> exists for provider <provider> .
INVALID_ROLE_FOR_GROUP
400 Role <role> is invalid for group <group> .
INVALID_ROOT_VOLUME_SIZE
400 Invalid root volume size <number> . It must be between the minimum and maximum values returned in the machine configuration options.
INVALID_SECURITY_GROUP
400 Security group <group> is invalid. It must be one of the security groups returned in the machine configuration options.
INVALID_SNAPSHOT_ID
404 An invalid snapshot ID <ID> was specified.
INVALID_SNAPSHOT_INTERVAL
400 Snapshot interval must be 6, 8, 12, or 24 hours.
INVALID_SNAPSHOT_RETENTION_PERIOD
400 Snapshot retention period must be between 1 and 5 days.
INVALID_SSH_KEY
400 An invalid SSH key was specified.
INVALID_USER_ID
404 An invalid user ID <ID> was specified.
INVALID_USERNAME
400 The specified username is not a valid email address.
INVALID_USER
400 No user <username> exists.
INVALID_VOLUME_NAME
400 Invalid volume name <name> . It must be one of the listed volume names returned in the machine configuration options.
INVALID_VPC_OR_SUBNET
400 Invalid or unavailable VPC <VPC> or subnet <subnet> .
INVALID_WEEKLY_SNAPSHOT_RETENTION_PERIOD
400 Weekly snapshot retention period must be between 1 and 52 weeks.
INVALID_WINDOW_ID
404 An invalid maintenance window ID <ID> was specified.
INVALID_ZONE
400 No zone <zone> exists for region <region> .
IP_ADDRESS_NOT_ON_WHITELIST
403 IP address <address> is not allowed to access this resource.
LAST_PING_NOT_FOUND
404 No last ping exists for group <group> .
409 Cannot set HTTP link expiration time after snapshot deletion time.
404 No job with the given ID exists in this group.
MACHINE_CONFIG_PARAMS_NOT_FOUND
400 No machine configuration parameters exist for provider <provider> .
MAINTENANCE_WINDOW_NOT_FOUND
404 No maintenance window with ID <ID> exists in group <group> .
MAINTENANCE_WINDOW_START_DATE_AFTER_END_DATE
400 Maintenance window configurations must specify a start date before their end date.
MAX_USERS_PER_GROUP_EXCEEDED
400 Maximum number of users per group ( <number> ) in <ID> exceeded while trying to add users.
MAX_USERS_PER_ORG_EXCEEDED
400 Maximum number of users per organization ( <number> ) in <ID> exceeded while trying to add users.
MAX_TEAMS_PER_GROUP_EXCEEDED
400 Maximum number of teams per group ( <number> ) in <ID> exceeded while trying to add teams.
MAX_USERS_PER_TEAM_EXCEEDED
400 Maximum number of Cloud Manager users per team exceeded while trying to add users. Teams are limited to 250 users.
MAX_TEAMS_PER_ORG_EXCEEDED
400 Maximum number of teams per organization exceeded while trying to add team. Organizations are limited to 250 teams.
METRIC_THRESHOLD_PRESENT
400 The metric threshold should only be specific for host metric alerts.
MISSING_ALERT_CONFIG_ID
404 No alert configuration ID was found.
MISSING_ATTRIBUTE
400 The required attribute <attribute> was not specified.
MISSING_AUTH_ATTRIBUTES
400 The attributes <attribute> and <attribute> must be specified for authentication type <type> .
MISSING_CREDENTIALS_FOR_AUTH_MECHANISM
400 Authentication mechanism <mechanism> requires username and password.
MISSING_MAINTENANCE_WINDOW_ALERT_TYPE_NAME
400 Maintenance window configurations must specify at least one alert type.
MISSING_MAINTENANCE_WINDOW_END_DATE
400 Maintenance window configurations must specify an end date.
MISSING_MAINTENANCE_WINDOW_START_DATE
400 Maintenance window configurations must specify a start date.
MISSING_METRIC_THRESHOLD
400 A metric threshold must be specified for host metric alerts.
MISSING_NOTIFICATIONS
400 At least one notification must be specified for an alert configuration.
MISSING_ONE_OF_ATTRIBUTES
400 Either the <attribute> attribute or the <attribute> attribute must be specified.
MISSING_ONE_OF_THREE_ATTRIBUTES
400 Either the <attribute> attribute, the <attribute> attribute, or the <attribute> attribute must be specified.
MISSING_OR_INVALID_ATTRIBUTE
400 The required attribute <attribute> was incorrectly specified or omitted.
MISSING_PASSWORD
400 Username cannot be changed without specifying password.
MISSING_QUERY_PARAMETER
400 The required query parameter <parameter> was not specified.
MISSING_ROLES_FOR_GROUP_NOTIFICATION
400 Group notifications cannot specify an empty list of roles.
MISSING_SYNC_SOURCE
409 Changing the storage engine will require a resync, so a sync source must be provided.
MISSING_THRESHOLD
400 A threshold must be specified for member health alerts.
MULTIPLE_GROUPS
409 Multiple groups exist with the specified name.
MUTUALLY_EXCLUSIVE_QUERY_PARAMETERS
400 Either the <parameter> query parameter or the <parameter> query parameter but not both should be specified.
NO_CHECKPOINT_FOR_PIT_RESTORE
409 A suitable checkpoint could not be found for the specified point-in-time restore.
NO_CURRENT_USER
401 No current user.
NO_FREE_TIER_API
403 The API is not supported for the Free Tier of Cloud Manager.
NO_GROUP_SSH_KEY
409 No group SSH key exists for group <group> .
NO_PAYMENT_INFORMATION_FOUND
402 No payment information was found for group <group> .
NO_PROVIDER_AVAILABILITY_ZONES
400 Could not retrieve availability zones from <account> account.
NO_PROVIDER_AVAILABLE_INSTANCE_TYPES
400 Could not retrieve available instance types from <account> account.
NO_PROVIDER_SECURITY_GROUPS
400 Could not retrieve security groups from <account> account.
NO_SSH_KEYS_IN_GROUP
404 No SSH keys found in group <group> .
NONZERO_DELAY_REQUIRED
400 The specified metric requires a nonzero delay for all notifications.
NOT_CONFIG_SERVER
404 Host <host> is not an SCCC config server.
NOT_DATABASE_OR_DISK_METRIC
404 Metric <metric> is neither a database nor a disk metric.
NOT_GLOBAL_USER_ADMIN
401 The currently logged in user does not have the global user administrator.
NOT_GROUP_USER_ADMIN
401 The currently logged in user does not have the user administrator role in group <group> .
NOT_IN_GROUP
401 The current user is not in the group, or the group does not exist.
NOT_ORG_ADMIN
401 The currently logged in user does not have the administrator role in organization <organization> .
NOT_SHARDED
400 Only sharded clusters and replica sets can be patched.
NOT_USER_ADMIN
401 The currently logged in user does not have the user administrator role for any group, team, or organization containing user <username> .
NOTIFICATION_INTERVAL_OUT_OF_RANGE
400 Notifications must have an internal of at least 5 minutes.
NOTIFICATION_TYPE_IS_GLOBAL_ONLY
400 At least one notification is a type that is only available for global alert configurations.
ONLY_FAILED_JOB_CAN_BE_RESTARTED
400 A log collection request job can only be restarted if it is in the FAILED state.
ORG_NOT_FOUND
404 No organization with ID <ID> exists.
PROVIDER_AUTH_FAILED
401 Account failed to authenticate with <credentials> .
PROVIDER_CONFIG_ID_NOT_FOUND
404 No provider configuration with ID <ID> exists for provider <provider> .
PROVIDER_CONFIG_NOT_FOUND
404 No provider configuration exists for provider <provider> .
PROVIDER_NOT_FOUND
404 No provider <provider> exists.
PROVIDER_UNSUPPORTED
404 Provider <provider> not currently supported.
PROVISION_MACHINE_JOB_NOT_FOUND
404 No provision machine job with ID <ID> exists in group <group> .
PROVISIONED_MACHINE_COULD_NOT_TERMINATE
409 Provisioned machine with ID <ID> could not terminate because a MongoDB process, Monitoring, or Backup is currently running on the machine.
PROVISIONED_MACHINE_NOT_FOUND
404 No provisioned machine with ID <ID> exists in group <group> .
PROVISIONING_FAILED_FROM_PROVIDER
500 Unable to retrieve configuration options from the provider.
RATE_LIMITED
429 Resource <resource> is limited to <number> requests every <number> minutes.
RATE_LIMITED_IP
400 Rate limit of <number> invitations per <number> minutes exceeded.
RESOURCE_NOT_FOUND
404 Cannot find resource <resource> .
RESTORE_JOB_NOT_FOUND_IN_GROUP
404 No restore job with ID <ID> exists in group <group> .
RESTORE_JOB_NOT_FOUND
404 No restore job with ID <ID> exists for cluster <cluster> .
ROLE_NEEDS_GROUP_ID
400 Group-specific role <role> requires a group ID.
ROLE_NEEDS_NO_GROUP_ID
400 Global role <role> cannot be specified with a group ID.
ROLE_NEEDS_NO_ORG_ID
400 Role <role> cannot be specified with an organization ID.
ROLE_NEEDS_ORG_ID
400 Role <role> requires an organization ID.
ROLES_SPECIFIED_FOR_USER
403 Roles specified for user.
SNAPSHOT_NOT_FOUND
404 No snapshot with ID <ID> exists for cluster <cluster> .
SSH_KEY_ALREADY_EXISTS
409 An SSH key with the name <name> already exists.
SSH_KEY_NAME_NOT_FOUND
404 No SSH key with name <name> exists.
SSH_KEY_NOT_FOUND
404 No SSH key with ID <ID> exists.
THRESHOLD_PRESENT
400 A threshold should only be present for member health alerts.
TOO_MANY_GROUP_NOTIFICATIONS
400 At most one group notification can be specified for an alert configuration.
TOO_MANY_GROUP_TOKENS
400 Groups are limited to <MAX_TAGS_PER_GROUP> tags.
TOTAL_MODE_DEPRECATED
400 Mode TOTAL is no longer supported.
UNEXPECTED_ERROR
500 Unexpected error.
UNITS_MISMATCH
400 Threshold units cannot be converted to metric units.
UNSUPPORTED_AUTOMATION_AGENT_VERSION
Automation agent version is less than the accepted minimum version.
UNSUPPORTED_DELIVERY_METHOD
400 The specified delivery method is not supported.
UNSUPPORTED_FOR_CURRENT_CONFIG
403 Operation not supported for current configuration.
UNSUPPORTED_FOR_CURRENT_PLAN
403 Operation not supported for current plan.
UNSUPPORTED_NOTIFICATION_TYPE
400 Notification type <type> is unsupported.
UNSUPPORTED_SET_BACKUP_STATE
403 Setting the backup state to <state> is not supported.
UPGRADE_FOR_CLUSTER_CHECKPOINT_INTERVAL
409 Cluster checkpoint interval not supported by the Backup version; please upgrade .
UPGRADE_FOR_EXCLUDED_NAMESPACES
409 Excluded namespaces are not supported by this Backup version; please upgrade.
UPGRADE_FOR_INCLUDED_NAMESPACES
409 Included namespaces are not supported by this Backup version; please upgrade .
USER_ALREADY_EXISTS
409 A user with username <username> already exists.
USER_NOT_FOUND
404 No user with ID <ID> exists.
USER_NOT_IN_GROUP
404 User <username> is not in group <group> .
USER_UNAUTHORIZED
401 Current user is not authorized to perform this action.
USERNAME_NOT_FOUND
404 No user with username <username> exists.
VOLUME_ENCRYPTION_NOT_AVAILABLE
400 Volume encryption is not available on instances of type <type> .
VOLUME_OPTIMIZATION_NOT_AVAILABLE
400 Volume optimization is not available on instances of type <type> .
WEAK_PASSWORD
400 The specified password is not strong enough.
WEBHOOK_URL_NOT_SET
400 Webhook URL must be set in the group before adding webhook notifications.
WHITELIST_ACCESS_DENIED
401 Cannot access whitelist for user <username> , which is not currently logged in.
WHITELIST_NOT_FOUND
404 IP address <address> not on whitelist for user <username> .
Add Existing MongoDB Processes to Cloud Manager — MongoDB Cloud Manager

Add Existing MongoDB Processes to Cloud Manager¶

On this page

  • Considerations
  • Prerequisites
  • Procedures

Cloud Manager provides a wizard for adding your existing MongoDB deployments to monitoring and management. The wizard prompts you to:

  • Install an Automation if it doesn’t already exist

  • Identify the sharded cluster , the replica set , or the standalone to add. You can choose to add the deployment to Monitoring or to both Monitoring and Automation .

    If you are adding a deployment that you intend to live migrate to Atlas, you need to add the deployment (and its credentials) only for Monitoring .

Considerations¶

Unique Names¶

Deployments must have unique names within the projects.

Important

Replica set, sharded cluster, and shard names within the same project must be unique. Failure to have unique names for the deployments will result in broken backup snapshots.

MongoDB Configuration Options¶

Automation doesn’t support all MongoDB options. To review which options are supported, see MongoDB Settings that Automation Supports .

TLS

If you enable TLS , the FQDN for the host serving a MongoDB process must match the SAN for the TLS certificate on that host.

Caution

To prevent man-in-the-middle attacks, keep the scope of TLS certificates as narrow as possible. Although you can use one TLS certificate with many SANs , or a wildcard TLS certificate on each host, you should not. To learn more, see RFC 2818, section 3.1 .

Preferred Hostnames¶

Set up a preferred hostname if you:

  • Require a specific hostname, FQDN , IPv4 address or IPv6 address to access the MongoDB process, or
  • Must specify the hostname to use for hosts with multiple aliases.

To learn more, see the Preferred Hostnames setting in Project Settings .

Managing Windows MongoDB Services¶

If you are adding an existing MongoDB process that runs as a Windows Service to Automation, Automation:

  • Stops and disables the existing service
  • Creates and starts a new service

Authentication Credentials on Source and Destination Clusters¶

If the Cloud Manager project has MongoDB authentication settings enabled for its deployments, the MongoDB deployment you import must support the project’s authentication mechanism.

We recommend that you import to a new destination project that has no running processes and doesn’t have authentication enabled.

If the source cluster uses authentication, and the destination Cloud Manager project doesn’t have any existing managed processes, Cloud Manager enables authentication in the destination project, imports the existing keyfile from the source cluster, and uses it to authenticate the user that conducts the import process.

If the source cluster and the destination Cloud Manager project both use authentication, and the project has processes, Cloud Manager attempts to use existing authentication settings in the destination project during the import process. For the import process to succeed, authentication credentials on the source cluster and the Cloud Manager destination project must be the same.

To ensure that import is successful, before you start the import process, add the Cloud Manager destination project’s credentials on the source cluster. To learn more, see Rotate Keys for Replica Set or Rotate Keys for Sharded Clusters.

Authentication Use Cases¶

If your MongoDB deployment requires authentication, when you add the deployment to Cloud Manager for monitoring, you must provide the necessary credentials .

  • If the deployment doesn’t use Automation, but did use Backup, Monitoring, or both, you can find those credentials where the credentials were before updating to the MongoDB Agent.
  • If the deployment doesn’t use Automation, but will use Backup, Monitoring, or both:
    1. Create the credentials for the MongoDB Deployment. To learn more, see Required Access for MongoDB Agent for Monitoring and Required Access for MongoDB Agent for Backup .
    2. Add the credentials that you granted to those functions to Cloud Manager after you add the MongoDB processes. To learn more, see Add Credentials for Monitoring and Add Credentials for Backup .
  • If the deployment uses Automation, Cloud Manager uses the credentials from the MongoDB Agent. You can delete the credentials from the legacy Backup, and Monitoring Agents. The MongoDB Agent uses those credentials for its Automation, Backup, and Monitoring functions.
  • If the deployment will use Automation but didn’t use it before you import it, add the mms-automation user to the database processes you imported and add the user’s credentials to Cloud Manager.

To learn more, see Add Credentials for Automation .

Automation and Updated Security Settings Upon Import¶

Adding a MongoDB deployment to automation may affect the security settings of the Cloud Manager project and the MongoDB deployment.

  • Automation enables the Project Security Setting . If the MongoDB deployment requires authentication but the Cloud Manager project doesn’t have authentication settings enabled, when you add the MongoDB deployment to automation, Cloud Manager updates the project’s security settings to the security settings of the newly imported deployment.

    The import process only updates the Cloud Manager project’s security setting if the project’s security setting is currently disabled. The import process doesn’t disable the project’s security setting or change its enabled authentication mechanism.

  • Automation Imports MongoDB Users and Roles . The following statements apply to situations where a MongoDB deployment requires authentication or the Cloud Manager project has authentication settings enabled.

    If the MongoDB deployment contains users or user-defined roles, you can choose to import these users and roles for Cloud Manager to manage. The imported users and roles are Synced to all managed deployments in the Cloud Manager project.

    • If you set the project’s Enforce Consistent Set value to Yes , Cloud Manager deletes from the MongoDB deployments those users and roles that are not imported.
    • If you set the project’s Enforce Consistent Set value to No , Cloud Manager stops managing non-imported users and roles in the project. These users and roles remain in the MongoDB deployment. To manage these users and roles, you must connect directly to the MongoDB deployment.

    If you don’t want the Cloud Manager project to manage specific users and roles, use the Authentication & Users and Authentication & Roles pages to remove these users and roles during import before you confirm and deploy the changes. To learn more, see Manage or Unmanage MongoDB Users .

    If the imported MongoDB deployment already has mms-backup-agent and mms-monitoring-agent users in its admin database, the import process overrides these users’ roles with the roles for mms-backup-agent and mms-monitoring-agent users as set in the Cloud Manager project.

  • Automation Applies to All Deployments in the Project . The project’s updated security settings, including all users and roles managed by the Cloud Manager project, apply to all deployments in the project, including the imported MongoDB deployment.

    Cloud Manager restarts all deployments in the project with the new setting, including the imported MongoDB deployment. After import, all deployments in the project use the Cloud Manager automation keyfile upon restart.

    The deployment that you import must use the same keyfile as the existing processes in the destination project or the import process may not proceed. To learn more, see Authentication Credentials on Source and Destination Clusters .

    If the existing deployments in the project require a different security profile from the imported process, create a new project into which you can import the source MongoDB deployment.

Examples of Imported Users¶

The following examples apply to situations where the MongoDB deployment requires authentication or the Cloud Manager project has authentication settings enabled.

If you import the MongoDB users and custom roles, once the Cloud Manager project begins to manage the MongoDB deployment, the following happens, regardless of the Enforce Consistent Set value:

  • The Cloud Manager project enables authentication, manages imported users and roles, and syncs the new users and roles to all its managed deployments.
  • The MongoDB deployment’s access control is enabled and requires authentication. The MongoDB deployment has all users and roles that the Cloud Manager project manages. These users and roles have Synced set to Yes .

If you don’t import the MongoDB users and custom roles, once the Cloud Manager project begins to manage the MongoDB deployment, the following happens:

If Enforce Consistent Set is set to Yes :

  • The Cloud Manager project enables authentication and doesn’t change its managed users and roles.
  • The MongoDB deployment’s access control is enabled and requires authentication.
  • Cloud Manager deletes the non-imported MongoDB users and roles from the deployment.
  • The MongoDB deployment has all users and roles that the Cloud Manager project manages. These users and roles have Synced set to Yes .

If Enforce Consistent Set is set to No :

  • The Cloud Manager project enables authentication and doesn’t change its security settings, including users and roles.
  • The MongoDB deployment’s access control is enabled and requires authentication.
  • The non-imported MongoDB users and roles remain in the MongoDB deployment.
  • The MongoDB deployment has all users and roles managed by the Cloud Manager project. These users and roles have Synced set to Yes .

Prerequisites¶

  • If mongod is enabled as a service on the deployment, a race condition might result where systemd starts mongod on reboot, rather than the Automation. To prevent this issue, ensure the mongod service is disabled before you add your deployment to Automation:

    1. Verify whether the mongod service is enabled:
    sudo systemctl is-enabled mongod.service
    
    1. If the service is enabled, disable it:
    sudo systemctl disable mongod.service
    
  • If the Cloud Manager project doesn’t have authentication settings enabled but the MongoDB process requires authentication, add the MongoDB Agent user for the Cloud Manager project with the appropriate roles. The import process displays the required roles for the user. The added user becomes the project’s MongoDB Agent user.

  • If the Cloud Manager project has authentication settings enabled, add the Cloud Manager project’s MongoDB Agent user to the MongoDB process.

    • To find the MongoDB Agent user, click Deployments , then Security , then Users .

    • To find the password for the Cloud Manager project’s MongoDB Agent user, use one of the following methods:

      Follow the steps in the Add MongoDB Processes procedure to launch the wizard in the UI. When you reach the modal that says Do you want to add automation to this deployment? :

      1. Select Add Automation and Configure Authentication .
      2. Click Show Password .
  • The import process requires that the authentication credentials and keyfiles are the same on the source and destination clusters. To learn more, see Authentication Credentials on Source and Destination Clusters .

Important

If you are adding a sharded cluster, you must create this user through the mongos and on every shard. That is, create the user both as a cluster wide user through mongos as well as a shard local user on each shard.

Procedures¶

Add MongoDB Processes¶

To add existing MongoDB processes to Cloud Manager:

1
2

Click Add and select Existing MongoDB Deployment

3

Follow the prompts to add the deployment.¶

Add Authentication Credentials to your Deployment¶

After you add existing MongoDB process to Cloud Manager, you might have to add authentication credentials for the new deployments if authentication is enabled for the project into which you imported the deployment. See Authentication Use Cases to learn in which situations you must add Automation, Monitoring, or Backup credentials for your new deployment.

If you are adding a deployment that you intend to live migrate to Atlas, you need to add the deployment (and its credentials) only for Monitoring .

Select the authentication mechanism that you want to use:

Add Credentials for Automation¶

To add credentials for a deployment that will use Automation but didn’t use it before you imported it to Cloud Manager:

1

Add the MongoDB Agent user to your databases.¶

The MongoDB Agent user performs automation tasks for your MongoDB databases. Make sure this MongoDB user has the proper privileges .

2
3

Click Edit Credentials

4

Continue through the modal until you see the Configure Cloud Manager Agents page.¶

5

Add the appropriate credentials:¶

Setting Value
MongoDB Agent Username Enter the MongoDB Agent username.
MongoDB Agent Password Enter the password for MongoDB Agent Username.

Add Credentials for Monitoring¶

To add credentials for a deployment that will not use Automation but will use Monitoring:

1
2

Click Credentials

3

Add the appropriate credentials:¶

Setting Value
Monitoring Username Enter the Monitoring username.
Monitoring Password Enter the password for Monitoring Username.

Add Credentials for Backup¶

To add credentials for a deployment that will not use Automation but will use Backup:

1
2

For your deployment, Click ellipsis icon , then click Edit Credentials

3

Add the appropriate credentials:¶

Setting Value
Backup Username Enter the Backup username.
Backup Password Enter the password for Backup Username.
Read article
MongoDB Compatibility Matrix — MongoDB Cloud Manager

MongoDB Compatibility Matrix¶

On this page

  • MongoDB Versions Compatible with Cloud Manager
  • Agent Compatibility
  • MongoDB Deployment Types

This page describes compatibility between Cloud Manager features and MongoDB.

Cloud Manager support for End of Life MongoDB versions

Cloud Manager doesn’t support Backup, Monitoring, or Automation for versions earlier than MongoDB 3.6.

MongoDB Versions Compatible with Cloud Manager¶

  • Cloud Manager can automate deployments running MongoDB versions 3.6 or later.
  • Cloud Manager can monitor deployments running MongoDB versions 2.6 or later.
  • Cloud Manager can back up deployments running MongoDB versions 2.6 or later.

Backup Considerations for MongoDB Versions¶

To learn more about backup considerations specific to MongoDB 4.4 and later and 4.2 and earlier, see Backup Considerations .

To learn more about MongoDB versioning, see MongoDB Versioning in the MongoDB Manual.

Agent Compatibility¶

Monitoring Compatibility¶

To monitor a deployment running MongoDB 3.6 or later release series, you must use Monitoring Agent version 2.7.0 or later.

Automation PowerPC Compatibility¶

To manage PowerPC Linux-based hosts, you must use Automation Agent 3.2.7.1927 or later.

MongoDB Deployment Types¶

Using Cloud Manager, you can configure all MongoDB deployment types: sharded clusters, replica sets, and standalones.

The shards in a sharded cluster must be replica sets. That is, a shard cannot be a standalone mongod . If you must run a shard as a single mongod (which provides no redundancy or failover), run the shard as a single-member replica set.

Note

You may not upgrade a sharded MongoDB deployment to version 3.4 if the deployment uses mirrored mongod instances as config servers. To allow the sharded deployment to be upgraded, see Convert Config Servers to a Replica Set . The conversion requires that the sharded deployment run MongoDB version 3.2.4 or later. Deployments running previous versions must upgrade to version 3.2.4 before an upgrade to version 3.4.

Read article
Stop Monitoring a Process — MongoDB Cloud Manager

Stop Monitoring a Process¶

On this page

  • Understand the Objectives
  • Complete the Prerequisites
  • Follow These Steps

This tutorial shows you how to stop monitoring a process . Once you stop monitoring a process, Cloud Manager stops displaying its status and tracking its metrics.

Understand the Objectives¶

Learn how to use the Cloud Manager Administration API to:

  • Find the host ID for the process.
  • Stop monitoring the process that matches the host ID.
  • Verify that Cloud Manager no longer monitors the process.

Complete the Prerequisites¶

Complete these prerequisites before you complete the tutorial.

  • Configure your access to the Cloud Manager Administration API .
  • Get the permissions needed to change monitoring settings. You need one of the following roles:
    • Project Monitoring Admin
    • Project Owner
  • Terminate the backups for the process before you stop monitoring it.

Follow These Steps¶

Complete all the following steps to use the API to stop monitoring a process.

1

Find the host ID for the process.¶

Use the Get One Host by Hostname and Port resource to find the process and retrieve the id value.

Learn What This Step Does¶

The Get One Host by Hostname and Port resource uses the hostname and port you specify to find the process. Then, it returns information about this process. You can find the id needed for the next step in the response.

Issue This Command¶

Copy the following curl command. Paste it into your preferred terminal or console. Replace the displayed placeholders with these values:

Placeholder Description
{PUBLIC-KEY} Public part of your API key.
{PRIVATE-KEY} Private part of your API key.
{PROJECT-ID} Unique identifier of the project that owns the host.
{HOSTNAME} Primary hostname that Cloud Manager uses to connect to the instance. This may be a hostname, an FQDN , an IPv4 address, or an IPv6 address.
{PORT} Port on which the process listens.

Replace the placeholders in the command, then execute it.

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
     --request GET "https://cloud.mongodb.com/api/public/v1.0/groups/{PROJECT-ID}/hosts/byName/{HOSTNAME}:{PORT}"

Copy the Host’s ID¶

In the response body, copy the value returned in the id field. You need the value for the next step.

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "alertsEnabled" : true,
  "aliases": [ "server1.example.com:27017", "203.0.113.3:27017" ],
  "authMechanismName" : "SCRAM-SHA-1",
  "clusterId" : "<cluster-ID-1>",
  "created" : "2021-04-22T19:56:50Z",
  "groupId" : "<project-ID-1>",
  "hasStartupWarnings" : false,
  "hidden" : false,
  "hostEnabled" : true,
  "hostname" : "server1.example.com",
  "id" : "{HOST-ID}",
  "ipAddress": "203.0.113.3",
}
2

Stop monitoring the process that matches the host ID.¶

Use the Stop Monitoring One Host resource to stop monitoring the host.

Learn What This Step Does¶

The Stop Monitoring One Host resource doesn’t actually delete the host. The resource deletes the host from the list of hosts that Cloud Manager monitors. This removes the process from monitoring.

Issue This Command¶

Copy the following curl command. Paste it into your preferred terminal or console. Replace the displayed placeholders with these values:

Placeholder Description
{PUBLIC-KEY} Public part of your API key.
{PRIVATE-KEY} Private part of your API key.
{PROJECT-ID} Unique identifier of the project that owns the host.
{HOST-ID} Unique identifier of the host for the process. Use the id from step 1.

Replace the placeholders in the command, then execute it.

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
     --request DELETE "https://cloud.mongodb.com/api/public/v1.0/groups/{PROJECT-ID}/hosts/{HOST-ID}"
3

Verify that Cloud Manager no longer monitors the process.¶

Use the Get One Host by Hostname and Port resource again to attempt to find the process using its hostname and port. Then, verify that details returns No host with hostname and port {HOSTNAME}:{PORT} exists in group {PROJECT-ID} .

Learn What This Step Does¶

The Get One Host by Hostname and Port resource uses the hostname and port you specify to find the process. Then, it returns information about this process. You can tell that Cloud Manager doesn’t monitor the process if the details value in the response is No host with hostname and port {HOSTNAME}:{PORT} exists in group {PROJECT-ID} . This means that Cloud Manager can’t find the host in the list of processes that it monitors.

Issue This Command¶

Copy the following curl command. Paste it into your preferred terminal or console. Replace the displayed placeholders with these values:

Placeholder Description
{PUBLIC-KEY} Public part of your API key.
{PRIVATE-KEY} Private part of your API key.
{PROJECT-ID} Unique identifier of the project that owns the host.
{HOSTNAME} Primary hostname that Cloud Manager uses to connect to this instance. This may be a hostname, an FQDN, an IPv4 address, or an IPv6 address.
{PORT} Port on which the process listens.

Replace the placeholders in the command, then execute it.

curl --user "{PUBLIC-KEY}:{PRIVATE-KEY}" --digest \
     --request GET "https://cloud.mongodb.com/api/public/v1.0/groups/{PROJECT-ID}/hosts/byName/{HOSTNAME}:{PORT}"

Check the Response Details¶

In the response body, check the value returned in the details field. If details returns No host with hostname and port {HOSTNAME}:{PORT} exists in group {PROJECT-ID} , you succeeded. Cloud Manager no longer monitors the process.

Read article
Public API Principles — MongoDB Cloud Manager

Public API Principles

On this page

  • HTTP Methods
  • JSON
  • Linking
  • Lists
  • Envelopes
  • Pretty Printing
  • Response Codes
  • Errors
  • Authentication
  • Automation
  • Additional Information

The Cloud Manager Public API follows the REST architecture principles to expose internal resources that provide programmatic access to Cloud Manager’s features.

As with changes made through the web interface, changes made through the API are subject to Cloud Manager pricing . If you add servers and incur charges, you must have a valid credit card on file with Cloud Manager or risk having your account locked .

The API has the following features:

JSON entities
All entities are expressed in JSON .
Key-based access
Each Cloud Manager user or application needing to connect to Cloud Manager must generate an API key before accessing the Cloud Manager API .
Digest authentication
To ensure that your Public API Key is never sent over the network, API requests are authenticated using HTTP Digest Authentication.
Browsable interface
Using a consistent linking mechanism, you can browse the entire API by starting at the root resource and following links to related resources.
User Access Control

Each Cloud Manager user’s API capabilities match the permissions that their Cloud Manager Roles grant.

Example

A user with the Project Read Only role cannot modify any resource within that project whether through the Cloud Manager UI or the API .

API Network Whitelist
The Cloud Manager API supports a per-user API Whitelist for restricting API access to specific IP or CIDR addresses. For Cloud Manager users with a non-empty API whitelist, all API access must originate from a whitelisted IP address. An empty API whitelist grants access to all API endpoints from any IP address, except those that explicitly require whitelisting for access.
HTTPS Only
You can only access the API via HTTPS , ensuring all data sent over the network is fully encrypted using TLS .

HTTP Methods

All resources support a subset of these common HTTP Methods:

Method Purpose
GET Retrieve the JSON representation of a resource.
POST Create a new resource using the provided JSON representation.
PUT Replace a resource with the provided JSON representation.
PATCH Update the specified fields in a resource using the provided JSON representation.
DELETE Remove a resource.
HEAD Retrieve the response header without the JSON representation of the resource.

JSON

All entities are represented in JSON . The following rules for requests and conventions of responses apply:

Request Rules¶

Apply the Correct Content Type Header
When sending JSON to the server via POST or PUT , make sure to specify the correct content type request header: Content-Type: application/json
Set Dates as ISO 8601 Strings

When sending dates to the server (as query parameters or fields in POST or PATCH request entities), use dates formatted according to the ISO 8601 standard. If you don’t specify a time zone, Cloud Manager assumes UTC . Include a time zone designator to avoid any ambiguity.

Example

  • September 27, 2018 is expressed as 2018-09-27 .
  • September 27, 2018 at 4:00 PM EDT is expressed (with time zone) as 2018-09-27T16:00-04:00 .

In some cases, a timestamp is returned as a JSON representation of a BSON timestamp, most notably in the backup resources. This representation of a BSON timestamp provides a JSON document as an object with two fields:

Field Definition
date Seconds since the UNIX Epoch
increment An incrementing 32-bit integer ordinal for operations within a given second.

Example

The third operation at September 27, 2018 at 4:00 PM EDT is expressed (with time zone) as

{ date: 2018-09-27T16:00-04:00, increment: 3 }

Response Conventions¶

Rejects Invalid Fields

Invalid fields are rejected rather than ignored .

Example

You attempt to create a new entity and misspell one of the fields, or if you attempt to update an existing entity and include a field that cannot be modified, the Cloud Manager responds with an HTTP 400 status code and an error message stating which field was invalid.

Returns Dates as ISO 8601 Strings
All dates are returned as ISO 8601-formatted strings designated in UTC .
Labels Field to Disambiguate Units

Fields that contain numeric values in a particular unit are named so as to disambiguate the unit being used.

Example

A host’s uptime is returned in millseconds, so the name of the host entity field is uptimeMsec .

Returns Default Values for Fields without Other Values

Fields that do not have a current value are returned with an appropriate default value.

Example

Cloud Manager does not have any statistics for a newly discovered host, so any statistics-related fields have a value of zero.

Fields that do not have a sensible default value are omitted from the entity.

Example

A host that is not using authentication omits the username field from the returned entity.

Returns Fields in Alphabetical Order
The fields in the JSON documents that the Cloud Manager returns are in alphabetical order. The order could change. Do not depend on the order of the fields.

Linking¶

Each resource includes one or more links to sub-resources and/or related resources.

Example

A host has a link to the project it belongs to, the replica set it belongs to, and so on.

Links are placed in the links field of an entity, which is an array of link relation objects. Each link relation has two fields:

Field Definition
rel Name (or type) of the relation. Many of these are considered Extension Relation Types and are prefixed by http://mms.mongodb.com .
href Target URL .

All entities include at least one link relation called self , which is simply its own URL . When an entity is part of a list (i.e., when requesting all hosts in a project), then it only includes the self link relation.

Example

This is a portion of a host resource with a few links:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
{
  "id": "xxx",
  "projectId": "yyy",
  "hostname": "mongodb.example.com",
  "port": 27017,
  "links": [
    {
      "rel": "self",
      "href": "https://cloud.mongodb.com/api/public/v1.0/projects/xxx/hosts/yyy"
    },
    {
      "rel": "http://mms.mongodb.com/project",
      "href": "https://cloud.mongodb.com/api/public/v1.0/projects/xxx"
    }
  ]
}

To learn more, see the Web Linking Specification.

Note

Although the Web Linking Specification describes a format for including links in the HTTP response headers, it is not required. To make the API easily browsable, it includes the links in the response body rather than in the response headers.

Lists¶

Some resources return a list of entities.

Example

You can request a list of all hosts in a project .

When a list of entities is expected in a response, the results are returned in batches bounded by two query parameters:

Field Definition
pageNum Page number (1-based). Defaults to 1 if not specified.
itemsPerPage Number of items to return per page, up to a maximum of 500. Defaults to 100 if not specified.

The response entity contains three fields:

Field Definition
totalCount

Total number of items in the entire result set.

Example

If a project has a total of 57 hosts, and you make a request with pageNum=6 and itemsPerPage=10 , then totalCount is 57 .

results Result set, which is an array of entity documents.
links

Contains one to three link relations:

  • previous for the previous page of results (omitted for the first page);
  • next for the next page of results (omitted for the last page);
  • self for the current page (always present).

If you make a request for a list of entities and there are no results, then the API responds with an HTTP 200 status code and an empty results array. It does not respond with a 404 in this case, since the list of entities may not be empty at some point in the future.

If you had requested a list of entities in a context that does not exist (i.e., the list of hosts for a non-existent project), then this results in a an HTTP 404 response status.

Example

This is an HTTP response for the second page of 10 hosts in a project with a total of 57 hosts:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
{

  "totalCount": 57,
  "results": [
    {
      "id": "yyy",
      "projectId": "xxx",
      // additional host properties...
    },
    // additional host documents...
  ],
  "links": [
    {
      "rel" : "self",
      "href" : "https://www.mongodb.com/api/public/v1.0/projects/xxx/hosts?pageNum=2&itemsPerPage=10"
    },
    {
      "rel": "previous",
      "href": "https://www.mongodb.com/api/public/v1.0/projects/xxx/hosts?itemsPerPage=10&pageNum=1"
    },
    {
      "rel": "next",
      "href": "https://www.mongodb.com/api/public/v1.0/projects/xxx/hosts?itemsPerPage=10&pageNum=3"
    }
  ]
}

Envelopes¶

Some clients may not be able to access the HTTP response headers and/or status code. In that case, you can request that the response include an envelope , which is simply an extra layer of information in the JSON document that contains any relevant details that would normally be in the response headers.

By default, the API does not include the response in an envelope. To request one, simply add the query parameter envelope=true .

For responses that contain a single entity, the envelope contains two fields:

Field Definition
status HTTP status code.
content Requested entity.

For responses that contain a list of entities, there is already an envelope that wraps the results, so specifying envelope=true as a query parameter in this case only adds the status field to the existing envelope.

Pretty Printing¶

By default, extraneous whitespace is stripped from the JSON that Cloud Manager returns. To ask for pretty-printed JSON , simply append the pretty=true query parameter to any request:

curl --user '{USERNAME}:{APIKEY}' --digest \
 --header 'Accept: application/json' \
 --include \
 --request GET "https://cloud.mongodb.com/api/public/v1.0?pretty=true"

Note

All the examples in this document show pretty-printed JSON for clarity, although some example URL s may not contain this additional query parameter .

Response Codes¶

Responses utilize the standard HTTP response codes, including:

Code Meaning Notes
200 OK The request was successful. This is the typical response to a successful GET request.
201 Created A new resource was created. This is the typical response to a successful POST request.
202 Accepted A request for an asynchronous operation was accepted.
400 Bad Request Something was wrong with the client request.
401 Unauthorized Authentication is required but was not present in the request. Typically this means that the digest authentication information was omitted from the request, the provided credentials are incorrect, or the user associated with the given API key is not allowed to access the requested resource.
403 Forbidden Access to the specified resource is not permitted.
404 Not Found The requested resource does not exist.
405 Method Not Allowed

The HTTP method is not supported for the specified resource. Keep in mind that each resource may only support a subset of HTTP methods.

Example

You are not allowed to DELETE the root resource.

409 Conflict

This is typically the response to a request to create or modify a property of an entity that is unique when an existing entity already exists with the same value for that property.

Example

If you attempt to create a project with the same name as an existing project, the request fails.

5xx Various server errors Something unexpected went wrong. Try again later and consider notifying Cloud Manager Support.

Errors¶

When a request results in an error, the response body contains a JSON document with additional details about what went wrong. The document contains five fields:

Field Data Type Definition
detail string Human-readable description of the API request error.
error integer HTTP status code .
errorCode string Named constant representing the API request error as shown in Cloud Manager Administration API Error Codes .
parameters array of strings List of parameters passed in the API request.
reason string HTTP status code definition .

Example

Cloud Manager returns this response body for an incorrectly formatted request:

1
2
3
4
5
6
7
{
  "detail" : "Cannot find resource /api/public/v1.0/softwareComponents/version.",
  "error" : 404,
  "errorCode" : "RESOURCE_NOT_FOUND",
  "parameters" : [ "/api/public/v1.0/softwareComponents/version" ],
  "reason" : "Not Found"
}

To review the list of codes, see Cloud Manager Administration API Error Codes .

Authentication¶

As previously mentioned, the Cloud Manager API uses HTTP Digest Authentication. The details of digest authentication are beyond the scope of this document, but it essentially requires a username and a password which are hashed using a unique server-generated value called a nonce . The username is the username of a registered Cloud Manager account, and the password is a Public API Key associated with that account.

Keep the following points in mind:

  • The server-generated nonce is used by the client to hash the username and password before sending them back to the server to authenticate a request. The nonce is only valid for a short amount of time as per the digest authentication specification. This is to prevent replay attacks, so you cannot cache a nonce and use it forever.
  • Using digest authentication in combination with HTTPS provides an extra layer of security by ensuring that a password is never transmitted back to the server.
  • Some resource methods require even more security and are additionally protected by whitelists that allow access to the resource only from the IP addresses listed. Each user configures their own whitelist of IP addresses that allow access to the resource.

  • The Cloud Manager has a concept of roles , which allow more fine-grained control of the operations a user is allowed to perform. The API resources also enforce the same authorization rules, so the resources and methods that can be accessed by an API key are governed by the roles granted to the associated user.

    Example

    To DELETE a host, the user that owns the API key used to make the request must be a Project Monitoring Admin or Project Owner in the project to which the host belongs.

  • Many resources are tied to a project (former known as a group ), as evidenced by URL s of the following form:

    /api/public/v1.0/groups/{PROJECT-ID}/
    

    For these resources, the user tied to the API key must be a member of the project. Otherwise Cloud Manager responds with an HTTP 401 error.

Automation¶

The Automation Configuration Resource and Get Automation Status of Latest Plan resources provide endpoints that let you modify a project’s deployment and retrieve deployment status. You can modify a deployment by sending a new automation configuration to Cloud Manager. The automation configuration is where you describe and configure the MongoDB processes to be deployed. Cloud Manager refers to this as the deployment’s “goal state.” When you submit a new automation configuration through the API , the Automations adjust the current state of the system to match the goal state.

Important

There is no protection in the API to prevent concurrent modifications. If two administrators both start with a configuration based on the current version, make their own modifications, and then submit their modifications, the later modification wins.

Rate Limiting¶

Certain resources are subject to rate limiting.

For resources that are rate limited, Cloud Manager allows up to 100 requests per minute per project . Keep in mind that a Public API Key is assigned to a Cloud Manager user, but that user may access multiple projects.

Example

Consider two users: A and B.

User A belongs to project X, and user B belongs to projects X and Y.

  1. At 1:00:00pm, User A makes 50 requests to a rate limited resource in project X, all of which complete by 1:00:20pm.

  2. At 1:00:30pm, User B attempts to make 60 requests to a rate limited resource in project X.

    Since User A has already used up 50 requests within the 1:00pm minute for project X, the last 10 requests User B attempts to make are rejected. However, User B can make requests to a rate limited resource in project Y, since each project maintains a separate request counter.

  3. At 1:01pm, requests to project X may proceed, because the request counter used for rate limiting reset each minute.

If you exceed the rate limit, the API returns an HTTP 429 Too Many Requests response code.

Additional Information¶

See Cloud Manager Administration API Resources for a complete reference of all resources available in the Cloud Manager Public API .

Read article

Still Thinking?
Give us a try!

We embrace agility in everything we do.
Our onboarding process is both simple and meaningful.
We can't wait to welcome you on AiDOOS!