Navigation

Enable and Configure Encryption at Rest for a Project

On this page

Note

Groups and projects are synonymous terms. Your {GROUP-ID} is the same as your project ID. For existing groups, your group/project ID remains the same. The resource and corresponding endpoints use the term groups.

Feature unavailable in Free and Shared Tier Clusters

This feature is not available for M0 (Free Tier), M2, and M5 clusters. To learn more about which features are unavailable, see Atlas M0 (Free Tier), M2, and M5 Limitations.

AWS and Azure Clusters Only

This feature is only available for Atlas M10 or greater replica set clusters deployed on AWS or Azure. Support for sharded clusters and clusters deployed on Google Cloud Project (GCP) are in development.

Overview

Enables, disables, and configures Encryption at Rest for an Atlas project with one of the following providers:

After configuring at least one Encryption at Rest provider for the Atlas project, Project Owners can enable Encryption at Rest for each Atlas cluster for which they require encryption. The Encryption at Rest provider does not have to match the cluster cloud service provider.

Atlas does not automatically rotate user-managed encryption keys. Defer to your preferred Encryption at Rest provider’s documentation and guidance for best practices on key rotation. Atlas automatically creates a 365-day key rotation alert when you configure Encryption at Rest using your Key Management in an Atlas project.

See Encryption at Rest for more information, including prerequisites and restrictions.

The Atlas API uses HTTP Digest Authentication. Provide your Atlas username and API key as the username and password when constructing the HTTP request.

For complete documentation on configuring API access for an Atlas project, see Configure Atlas API Access.

Base URL: https://cloud.mongodb.com/api/atlas/v1.0

Syntax

copy 
PATCH /groups/{GROUP-ID}/encryptionAtRest

Request Path Parameters

Path Element Required/Optional Description
GROUP-ID Required. The unique identifier for the project.

Request Query Parameters

This endpoint may use any of the HTTP request query parameters available to all Atlas API resources. These are all optional.

Name Type Description Default
pretty boolean Displays response in a prettyprint format. false
envelope boolean Specifies whether or not to wrap the response in an envelope. false

Request Body Parameters

The required request body parameters depend on whether Encryption at Rest is currently enabled:

  • If Encryption at Rest is not enabled, all of the parameters for the desired encryption provider are required. For example, if you want to use AWS KMS, all the fields in the awsKms document are required. If you want to use Azure Key Vault, all the fields in the azureKeyVault document are required.
  • If Encryption at Rest is enabled, administrators can update the configuration by passing only the changed fields for either the awsKms or azureKeyVault document to this endpoint.
Name Type Description
awsKms object Specifies AWS KMS configuration details and whether Encryption at Rest is enabled for an Atlas project.
awsKms.accessKeyID string The IAM access key ID with permissions to access the customer master key specified by customerMasterKeyID.
awsKms.customerMasterKeyID string The AWS customer master key used to encrypt and decrypt the MongoDB master keys.
awsKms.enabled boolean Specifies whether Encryption at Rest is enabled for an Atlas project. To disable Encryption at Rest, pass only this parameter with a value of false. When you disable Encryption at Rest, Atlas also removes the configuration details.
awsKms.region string

The AWS region in which the AWS customer master key exists:

  • CA_CENTRAL_1
  • US_EAST_1
  • US_EAST_2
  • US_WEST_1
  • US_WEST_2
  • SA_EAST_1
  • AP_NORTHEAST_1
  • AP_NORTHEAST_2
  • AP_SOUTH_1
  • AP_SOUTHEAST_1
  • AP_SOUTHEAST_2
  • EU_CENTRAL_1
  • EU_WEST_1
  • EU_WEST_2
  • EU_WEST_3
awsKms.secretAccessKey string The IAM secret access key with permissions to access the customer master key specified by customerMasterKeyID.
azureKeyVault object Specifies Azure Key Vault configuration details and whether Encryption at Rest is enabled for an Atlas project.
azureKeyVault.azureEnvironment string

The Azure environment where the Azure account credentials reside. Valid values are the following:

  • AZURE
  • AZURE_CHINA
  • AZURE_GERMANY
azureKeyVault.clientID string The client ID, also known as the application ID, for an Azure application associated with the Azure AD tenant.
azureKeyVault.enabled boolean Specifies whether Encryption at Rest is enabled for an Atlas project. To disable Encryption at Rest, pass only this parameter with a value of false. When you disable Encryption at Rest, Atlas also removes the configuration details.
azureKeyVault.keyIdentifier string The unique identifier of a key in an Azure Key Vault.
azureKeyVault.keyVaultName string The name of an Azure Key Vault containing your key.
azureKeyVault.resourceGroupName string The name of the Azure Resource group that contains an Azure Key Vault.
azureKeyVault.secret string The secret associated with the Azure Key Vault specified by azureKeyVault.tenantID.
azureKeyVault.subscriptionID string The unique identifier associated with an Azure subscription.
azureKeyVault.tenantID string The unique identifier for an Azure AD tenant within an Azure subscription.

Response

Name Type Description
awsKms object Specifies whether Encryption at Rest is enabled for an Atlas project and the AWS KMS configuration details.
awsKms.accessKeyID string The IAM access key ID with permissions to access the customer master key specified by customerMasterKeyID.
awsKms.customerMasterKeyID string The AWS customer master key used to encrypt and decrypt the MongoDB master keys.
awsKms.enabled boolean Specifies whether Encryption at Rest is enabled for an Atlas project.
awsKms.region string The AWS region in which the AWS customer master key exists.
azureKeyVault object Specifies Azure Key Vault configuration details and whether Encryption at Rest is enabled for an Atlas project.
azureKeyVault.azureEnvironment string The Azure environment where the Azure account credentials reside.
azureKeyVault.clientID string The client ID, also known as the application ID, for an Azure application associated with the Azure AD tenant.
azureKeyVault.enabled boolean Specifies whether Encryption at Rest is enabled for an Atlas project and the Azure Key Vault configuration details.
azureKeyVault.keyIdentifier string The unique identifier of a key in an Azure Key Vault.
azureKeyVault.keyVaultName string The name of an Azure Key Vault containing your key.
azureKeyVault.resourceGroupName string The name of the Azure Resource group that contains an Azure Key Vault.
azureKeyVault.subscriptionID string The unique identifier associated with an Azure subscription.
azureKeyVault.tenantID string Unique identifier for an Azure AD tenant within an Azure subscription.

Example Request

The following example enables and configures Encryption at Rest for an Atlas project using AWS KMS:

copy 
curl -X PATCH -i -u "username:apiKey" --digest \
 --header "Accept: application/json" \
 --header "Content-Type: application/json" \
 "https://cloud.mongodb.com/api/atlas/v1.0/groups/{GROUP-ID}/encryptionAtRest?pretty=true" \
 --data '
 {
   "awsKms": {
     "enabled": true,
     "accessKeyID" : "AKIAIOSFODNN7EXAMPLE",
     "secretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
     "customerMasterKeyID" : "030gce02-586d-48d2-a966-05ea954fde0g",
     "region" : "US_EAST_1"
   }
 }'

Example Response

copy 
{
  "awsKms" : {
    "accessKeyID" : "AKIAIOSFODNN7EXAMPLE",
    "customerMasterKeyID" : "030gce02-586d-48d2-a966-05ea954fde0g",
    "enabled" : true,
    "region" : "US_EAST_1"
  },
  "azureKeyVault" : {
    "clientID" : null,
    "enabled" : false,
    "keyIdentifier" : null,
    "keyVaultName" : null,
    "resourceGroupName" : null,
    "subscriptionID" : null,
    "tenantID" : null
  }
}

Example Request

The following example enables and configures Encryption at Rest for an Atlas project using Azure Key Vault:

copy 
curl -X PATCH --digest -i -u "{username}:{apiKey}" --header "Content-Type: application/json" \
 "https://cloud.mongodb.com/api/atlas/v1.0/groups/6cbbae2187d9d675e009g35f/encryptionAtRest?pretty=true" \
 --data '
 {
   "azureKeyVault" : {
     "enabled" : true,
     "clientID" : "g54f9e2-89e3-40fd-8188-EXAMPLEID",
     "azureEnvironment" : "AZURE",
     "subscriptionID" : "0ec944e3-g725-44f9-a147-EXAMPLEID",
     "resourceGroupName" : "ExampleRGName",
     "keyVaultName" : "EXAMPLEKeyVault",
     "keyIdentifier" : "https://EXAMPLEKeyVault.vault.azure.net/keys/EXAMPLEKey/d891821e3d364e9eb88fbd3d11807b86",
     "secret" : "EXAMPLESECRET",
     "tenantID" : "e8e4b6ba-ff32-4c88-a9af-EXAMPLEID"
   }
 }'

Example Response

copy 
{
  "awsKms" : {
    "accessKeyID" : null,
    "customerMasterKeyID" : null,
    "enabled" : false,
    "region" : null
  },
  "azureKeyVault" : {
    "enabled" : true,
    "clientID" : "g54f9e2-89e3-40fd-8188-EXAMPLEID",
    "azureEnvironment" : "AZURE",
    "subscriptionID" : "0ec944e3-g725-44f9-a147-EXAMPLEID",
    "resourceGroupName" : "ExampleRGName",
    "keyVaultName" : "EXAMPLEKeyVault",
    "keyIdentifier" : "https://EXAMPLEKeyVault.vault.azure.net/keys/EXAMPLEKey/d891821e3d364e9eb88fbd3d11807b86",
    "tenantID" : "e8e4b6ba-ff32-4c88-a9af-dc17efegdf63"
  }
}

Example Request

The following example disables Encryption at Rest for an Atlas project:

copy 
curl -X PATCH -i -u "username:apiKey" --digest --header "Content-Type: application/json" \
 "https://cloud.mongodb.com/api/atlas/v1.0/groups/{GROUP-ID}/encryptionAtRest?pretty=true" \
 --data '
 {
   "awsKms": {
     "enabled" : false
   }
 }'

Example Response

copy 
{
  "awsKms" : {
    "accessKeyID" : null,
    "customerMasterKeyID" : null,
    "enabled" : false,
    "region" : null
  }
}

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.