Update Encryption at Rest Configuration for One Project

PATCH /api/atlas/v1.0/groups/{groupId}/encryptionAtRest

Updates the configuration for encryption at rest using the keys you manage through your cloud provider. MongoDB Cloud encrypts all storage even if you don't use your own key management. This resource requires the requesting Service Account or API Key to have the Project Owner role. This feature isn't available for M0 free clusters, M2, M5, or serverless clusters.

After you configure at least one Encryption at Rest using a Customer Key Management provider for the MongoDB Cloud project, Project Owners can enable Encryption at Rest using Customer Key Management for each MongoDB Cloud cluster for which they require encryption. The Encryption at Rest using Customer Key Management provider doesn't have to match the cluster cloud service provider. MongoDB Cloud doesn't automatically rotate user-managed encryption keys. Defer to your preferred Encryption at Rest using Customer Key Management provider's documentation and guidance for best practices on key rotation. MongoDB Cloud automatically creates a 90-day key rotation alert when you configure Encryption at Rest using Customer Key Management using your Key Management in an MongoDB Cloud project. MongoDB Cloud encrypts all storage whether or not you use your own key management.

Path parameters

groupId string Required

Unique 24-hexadecimal digit string that identifies your project. Use the /groups endpoint to retrieve all projects to which the authenticated user has access.

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.

Format should match the following pattern: ^([a-f0-9]{24})$.

Query parameters

envelope boolean

Flag that indicates whether Application wraps the response in an envelope JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.

Default value is false.
pretty boolean

Flag that indicates whether the response body should be in the prettyprint format.

Default value is false.

Prettyprint

application/json

Body Required

Required parameters depend on whether someone has enabled Encryption at Rest using Customer Key Management:

If you have enabled Encryption at Rest using Customer Key Management (CMK), Atlas requires all of the parameters for the desired encryption provider.

To use AWS Key Management Service (KMS), MongoDB Cloud requires all the fields in the awsKms object.
To use Azure Key Vault, MongoDB Cloud requires all the fields in the azureKeyVault object.
To use Google Cloud Key Management Service (KMS), MongoDB Cloud requires all the fields in the googleCloudKms object.

If you enabled Encryption at Rest using Customer Key Management, administrators can pass only the changed fields for the awsKms, azureKeyVault, or googleCloudKms object to update the configuration to this endpoint.

awsKms object

Amazon Web Services (AWS) KMS configuration details and encryption at rest configuration set for the specified project.

Amazon Web Services Key Management Service
Hide awsKms attributes Show awsKms attributes object
- accessKeyID string
  
  Unique alphanumeric string that identifies an Identity and Access Management (IAM) access key with permissions required to access your Amazon Web Services (AWS) Customer Master Key (CMK).
  
  Minimum length is 16, maximum length is 128.
- customerMasterKeyID string
  
  Unique alphanumeric string that identifies the Amazon Web Services (AWS) Customer Master Key (CMK) you used to encrypt and decrypt the MongoDB master keys.
  
  Minimum length is 1, maximum length is 2048.
- enabled boolean
  
  Flag that indicates whether someone enabled encryption at rest for the specified project through Amazon Web Services (AWS) Key Management Service (KMS). To disable encryption at rest using customer key management and remove the configuration details, pass only this parameter with a value of false.
- region string
  
  Physical location where MongoDB Cloud deploys your AWS-hosted MongoDB cluster nodes. The region you choose can affect network latency for clients accessing your databases. When MongoDB Cloud deploys a dedicated cluster, it checks if a VPC or VPC connection exists for that provider and region. If not, MongoDB Cloud creates them as part of the deployment. MongoDB Cloud assigns the VPC a CIDR block. To limit a new VPC peering connection to one CIDR block and region, create the connection first. Deploy the cluster after the connection starts.
  
  Values are US_GOV_WEST_1, US_GOV_EAST_1, US_EAST_1, US_EAST_2, US_WEST_1, US_WEST_2, CA_CENTRAL_1, EU_NORTH_1, EU_WEST_1, EU_WEST_2, EU_WEST_3, EU_CENTRAL_1, EU_CENTRAL_2, AP_EAST_1, AP_NORTHEAST_1, AP_NORTHEAST_2, AP_NORTHEAST_3, AP_SOUTHEAST_1, AP_SOUTHEAST_2, AP_SOUTHEAST_3, AP_SOUTHEAST_4, AP_SOUTH_1, AP_SOUTH_2, SA_EAST_1, CN_NORTH_1, CN_NORTHWEST_1, ME_SOUTH_1, ME_CENTRAL_1, AF_SOUTH_1, EU_SOUTH_1, EU_SOUTH_2, IL_CENTRAL_1, CA_WEST_1, AP_SOUTHEAST_5, AP_SOUTHEAST_7, MX_CENTRAL_1, or GLOBAL.
- requirePrivateNetworking boolean
  
  Enable connection to your Amazon Web Services (AWS) Key Management Service (KMS) over private networking.
- roleId string
  
  Unique 24-hexadecimal digit string that identifies an Amazon Web Services (AWS) Identity and Access Management (IAM) role. This IAM role has the permissions required to manage your AWS customer master key.
  
  Format should match the following pattern: ^([a-f0-9]{24})$.
- secretAccessKey string
  
  Human-readable label of the Identity and Access Management (IAM) secret access key with permissions required to access your Amazon Web Services (AWS) customer master key.
azureKeyVault object

Details that define the configuration of Encryption at Rest using Azure Key Vault (AKV).

Azure Key Vault
Hide azureKeyVault attributes Show azureKeyVault attributes object
- azureEnvironment string
  
  Azure environment in which your account credentials reside.
  
  Values are AZURE or AZURE_CHINA.
- clientID string(uuid)
  
  Unique 36-hexadecimal character string that identifies an Azure application associated with your Azure Active Directory tenant.
- enabled boolean
  
  Flag that indicates whether someone enabled encryption at rest for the specified project. To disable encryption at rest using customer key management and remove the configuration details, pass only this parameter with a value of false.
- keyIdentifier string
  
  Web address with a unique key that identifies for your Azure Key Vault.
- keyVaultName string
  
  Unique string that identifies the Azure Key Vault that contains your key. This field cannot be modified when you enable and set up private endpoint connections to your Azure Key Vault.
- requirePrivateNetworking boolean
  
  Enable connection to your Azure Key Vault over private networking.
- resourceGroupName string
  
  Name of the Azure resource group that contains your Azure Key Vault. This field cannot be modified when you enable and set up private endpoint connections to your Azure Key Vault.
- secret string
  
  Private data that you need secured and that belongs to the specified Azure Key Vault (AKV) tenant (azureKeyVault.tenantID). This data can include any type of sensitive data such as passwords, database connection strings, API keys, and the like. AKV stores this information as encrypted binary data.
  
  Azure Key Vault Secrets
- subscriptionID string(uuid)
  
  Unique 36-hexadecimal character string that identifies your Azure subscription. This field cannot be modified when you enable and set up private endpoint connections to your Azure Key Vault.
- tenantID string(uuid)
  
  Unique 36-hexadecimal character string that identifies the Azure Active Directory tenant within your Azure subscription.
enabledForSearchNodes boolean

Flag that indicates whether Encryption at Rest for Dedicated Search Nodes is enabled in the specified project.
googleCloudKms object

Details that define the configuration of Encryption at Rest using Google Cloud Key Management Service (KMS).

Google Cloud Key Management Service
Hide googleCloudKms attributes Show googleCloudKms attributes object
- enabled boolean
  
  Flag that indicates whether someone enabled encryption at rest for the specified project. To disable encryption at rest using customer key management and remove the configuration details, pass only this parameter with a value of false.
- keyVersionResourceID string
  
  Resource path that displays the key version resource ID for your Google Cloud KMS.
- roleId string
  
  Unique 24-hexadecimal digit string that identifies the Google Cloud Provider Access Role that MongoDB Cloud uses to access the Google Cloud KMS.
  
  Format should match the following pattern: ^([a-f0-9]{24})$.
- serviceAccountKey string
  
  JavaScript Object Notation (JSON) object that contains the Google Cloud Key Management Service (KMS). Format the JSON as a string and not as an object.
  
  Google Cloud Authentication

Responses

200 application/json

OK
Hide response attributes Show response attributes object
- awsKms object
  
  Amazon Web Services (AWS) KMS configuration details and encryption at rest configuration set for the specified project.
  
  Amazon Web Services Key Management Service
  
  Hide awsKms attributes Show awsKms attributes object
  
  accessKeyID string
  
  Unique alphanumeric string that identifies an Identity and Access Management (IAM) access key with permissions required to access your Amazon Web Services (AWS) Customer Master Key (CMK).
  
  Minimum length is 16, maximum length is 128.
  
  customerMasterKeyID string
  
  Unique alphanumeric string that identifies the Amazon Web Services (AWS) Customer Master Key (CMK) you used to encrypt and decrypt the MongoDB master keys.
  
  Minimum length is 1, maximum length is 2048.
  
  enabled boolean
  
  Flag that indicates whether someone enabled encryption at rest for the specified project through Amazon Web Services (AWS) Key Management Service (KMS). To disable encryption at rest using customer key management and remove the configuration details, pass only this parameter with a value of false.
  
  region string
  
  Physical location where MongoDB Cloud deploys your AWS-hosted MongoDB cluster nodes. The region you choose can affect network latency for clients accessing your databases. When MongoDB Cloud deploys a dedicated cluster, it checks if a VPC or VPC connection exists for that provider and region. If not, MongoDB Cloud creates them as part of the deployment. MongoDB Cloud assigns the VPC a CIDR block. To limit a new VPC peering connection to one CIDR block and region, create the connection first. Deploy the cluster after the connection starts.
  
  Values are US_GOV_WEST_1, US_GOV_EAST_1, US_EAST_1, US_EAST_2, US_WEST_1, US_WEST_2, CA_CENTRAL_1, EU_NORTH_1, EU_WEST_1, EU_WEST_2, EU_WEST_3, EU_CENTRAL_1, EU_CENTRAL_2, AP_EAST_1, AP_NORTHEAST_1, AP_NORTHEAST_2, AP_NORTHEAST_3, AP_SOUTHEAST_1, AP_SOUTHEAST_2, AP_SOUTHEAST_3, AP_SOUTHEAST_4, AP_SOUTH_1, AP_SOUTH_2, SA_EAST_1, CN_NORTH_1, CN_NORTHWEST_1, ME_SOUTH_1, ME_CENTRAL_1, AF_SOUTH_1, EU_SOUTH_1, EU_SOUTH_2, IL_CENTRAL_1, CA_WEST_1, AP_SOUTHEAST_5, AP_SOUTHEAST_7, MX_CENTRAL_1, or GLOBAL.
  
  requirePrivateNetworking boolean
  
  Enable connection to your Amazon Web Services (AWS) Key Management Service (KMS) over private networking.
  
  valid boolean
  
  Flag that indicates whether the Amazon Web Services (AWS) Key Management Service (KMS) encryption key can encrypt and decrypt data.
- azureKeyVault object
  
  Details that define the configuration of Encryption at Rest using Azure Key Vault (AKV).
  
  Azure Key Vault
  
  Hide azureKeyVault attributes Show azureKeyVault attributes object
  
  azureEnvironment string
  
  Azure environment in which your account credentials reside.
  
  Values are AZURE or AZURE_CHINA.
  
  clientID string(uuid)
  
  Unique 36-hexadecimal character string that identifies an Azure application associated with your Azure Active Directory tenant.
  
  enabled boolean
  
  Flag that indicates whether someone enabled encryption at rest for the specified project. To disable encryption at rest using customer key management and remove the configuration details, pass only this parameter with a value of false.
  
  keyIdentifier string
  
  Web address with a unique key that identifies for your Azure Key Vault.
  
  keyVaultName string
  
  Unique string that identifies the Azure Key Vault that contains your key. This field cannot be modified when you enable and set up private endpoint connections to your Azure Key Vault.
  
  requirePrivateNetworking boolean
  
  Enable connection to your Azure Key Vault over private networking.
  
  resourceGroupName string
  
  Name of the Azure resource group that contains your Azure Key Vault. This field cannot be modified when you enable and set up private endpoint connections to your Azure Key Vault.
  
  subscriptionID string(uuid)
  
  Unique 36-hexadecimal character string that identifies your Azure subscription. This field cannot be modified when you enable and set up private endpoint connections to your Azure Key Vault.
  
  tenantID string(uuid)
  
  Unique 36-hexadecimal character string that identifies the Azure Active Directory tenant within your Azure subscription.
  
  valid boolean
  
  Flag that indicates whether the Azure encryption key can encrypt and decrypt data.
- enabledForSearchNodes boolean
  
  Flag that indicates whether Encryption at Rest for Dedicated Search Nodes is enabled in the specified project.
- googleCloudKms object
  
  Details that define the configuration of Encryption at Rest using Google Cloud Key Management Service (KMS).
  
  Google Cloud Key Management Service
  
  Hide googleCloudKms attributes Show googleCloudKms attributes object
  
  enabled boolean
  
  Flag that indicates whether someone enabled encryption at rest for the specified project. To disable encryption at rest using customer key management and remove the configuration details, pass only this parameter with a value of false.
  
  keyVersionResourceID string
  
  Resource path that displays the key version resource ID for your Google Cloud KMS.
  
  roleId string
  
  Unique 24-hexadecimal digit string that identifies the Google Cloud Provider Access Role that MongoDB Cloud uses to access the Google Cloud KMS.
  
  Format should match the following pattern: ^([a-f0-9]{24})$.
  
  valid boolean
  
  Flag that indicates whether the Google Cloud Key Management Service (KMS) encryption key can encrypt and decrypt data.
400 application/json

Bad Request.
Hide response attributes Show response attributes object
- badRequestDetail object
  
  Bad request detail.
  
  Hide badRequestDetail attribute Show badRequestDetail attribute object
  
  fields array[object]
  
  Describes all violations in a client request.
  
  Hide fields attributes Show fields attributes object
  
  description string Required
  
  A description of why the request element is bad.
  
  field string Required
  
  A path that leads to a field in the request body.
- detail string
  
  Describes the specific conditions or reasons that cause each type of error.
- error integer(int32) Required
  
  HTTP status code returned with this error.
  
  External documentation
- errorCode string Required
  
  Application error code returned with this error.
- parameters array[object]
  
  Parameters used to give more information about the error.
- reason string
  
  Application error message returned with this error.
401 application/json

Unauthorized.
Hide response attributes Show response attributes object
- badRequestDetail object
  
  Bad request detail.
  
  Hide badRequestDetail attribute Show badRequestDetail attribute object
  
  fields array[object]
  
  Describes all violations in a client request.
  
  Hide fields attributes Show fields attributes object
  
  description string Required
  
  A description of why the request element is bad.
  
  field string Required
  
  A path that leads to a field in the request body.
- detail string
  
  Describes the specific conditions or reasons that cause each type of error.
- error integer(int32) Required
  
  HTTP status code returned with this error.
  
  External documentation
- errorCode string Required
  
  Application error code returned with this error.
- parameters array[object]
  
  Parameters used to give more information about the error.
- reason string
  
  Application error message returned with this error.
403 application/json

Forbidden.
Hide response attributes Show response attributes object
- badRequestDetail object
  
  Bad request detail.
  
  Hide badRequestDetail attribute Show badRequestDetail attribute object
  
  fields array[object]
  
  Describes all violations in a client request.
  
  Hide fields attributes Show fields attributes object
  
  description string Required
  
  A description of why the request element is bad.
  
  field string Required
  
  A path that leads to a field in the request body.
- detail string
  
  Describes the specific conditions or reasons that cause each type of error.
- error integer(int32) Required
  
  HTTP status code returned with this error.
  
  External documentation
- errorCode string Required
  
  Application error code returned with this error.
- parameters array[object]
  
  Parameters used to give more information about the error.
- reason string
  
  Application error message returned with this error.
404 application/json

Not Found.
Hide response attributes Show response attributes object
- badRequestDetail object
  
  Bad request detail.
  
  Hide badRequestDetail attribute Show badRequestDetail attribute object
  
  fields array[object]
  
  Describes all violations in a client request.
  
  Hide fields attributes Show fields attributes object
  
  description string Required
  
  A description of why the request element is bad.
  
  field string Required
  
  A path that leads to a field in the request body.
- detail string
  
  Describes the specific conditions or reasons that cause each type of error.
- error integer(int32) Required
  
  HTTP status code returned with this error.
  
  External documentation
- errorCode string Required
  
  Application error code returned with this error.
- parameters array[object]
  
  Parameters used to give more information about the error.
- reason string
  
  Application error message returned with this error.
409 application/json

Conflict.
Hide response attributes Show response attributes object
- badRequestDetail object
  
  Bad request detail.
  
  Hide badRequestDetail attribute Show badRequestDetail attribute object
  
  fields array[object]
  
  Describes all violations in a client request.
  
  Hide fields attributes Show fields attributes object
  
  description string Required
  
  A description of why the request element is bad.
  
  field string Required
  
  A path that leads to a field in the request body.
- detail string
  
  Describes the specific conditions or reasons that cause each type of error.
- error integer(int32) Required
  
  HTTP status code returned with this error.
  
  External documentation
- errorCode string Required
  
  Application error code returned with this error.
- parameters array[object]
  
  Parameters used to give more information about the error.
- reason string
  
  Application error message returned with this error.
500 application/json

Internal Server Error.
Hide response attributes Show response attributes object
- badRequestDetail object
  
  Bad request detail.
  
  Hide badRequestDetail attribute Show badRequestDetail attribute object
  
  fields array[object]
  
  Describes all violations in a client request.
  
  Hide fields attributes Show fields attributes object
  
  description string Required
  
  A description of why the request element is bad.
  
  field string Required
  
  A path that leads to a field in the request body.
- detail string
  
  Describes the specific conditions or reasons that cause each type of error.
- error integer(int32) Required
  
  HTTP status code returned with this error.
  
  External documentation
- errorCode string Required
  
  Application error code returned with this error.
- parameters array[object]
  
  Parameters used to give more information about the error.
- reason string
  
  Application error message returned with this error.

PATCH /api/atlas/v1.0/groups/{groupId}/encryptionAtRest

curl \ --request PATCH 'https://cloud.mongodb.com/api/atlas/v1.0/groups/32b6e34b3d91647abb20e7b8/encryptionAtRest' \ --header "Authorization: Bearer $ACCESS_TOKEN" \ --header "Content-Type: application/json" \ --data '{"awsKms":{"accessKeyID":"019dd98d94b4bb778e7552e4","customerMasterKeyID":"string","enabled":true,"region":"US_GOV_WEST_1","requirePrivateNetworking":true,"roleId":"32b6e34b3d91647abb20e7b8","secretAccessKey":"string"},"azureKeyVault":{"azureEnvironment":"AZURE","clientID":"string","enabled":true,"keyIdentifier":"https://EXAMPLEKeyVault.vault.azure.net/keys/EXAMPLEKey/d891821e3d364e9eb88fbd3d11807b86","keyVaultName":"string","requirePrivateNetworking":true,"resourceGroupName":"string","secret":"string","subscriptionID":"string","tenantID":"string"},"enabledForSearchNodes":true,"googleCloudKms":{"enabled":true,"keyVersionResourceID":"projects/my-project-common-0/locations/us-east4/keyRings/my-key-ring-0/cryptoKeys/my-key-0/cryptoKeyVersions/1","roleId":"32b6e34b3d91647abb20e7b8","serviceAccountKey":"string"}}'

Request examples

{ "awsKms": { "accessKeyID": "019dd98d94b4bb778e7552e4", "customerMasterKeyID": "string", "enabled": true, "region": "US_GOV_WEST_1", "requirePrivateNetworking": true, "roleId": "32b6e34b3d91647abb20e7b8", "secretAccessKey": "string" }, "azureKeyVault": { "azureEnvironment": "AZURE", "clientID": "string", "enabled": true, "keyIdentifier": "https://EXAMPLEKeyVault.vault.azure.net/keys/EXAMPLEKey/d891821e3d364e9eb88fbd3d11807b86", "keyVaultName": "string", "requirePrivateNetworking": true, "resourceGroupName": "string", "secret": "string", "subscriptionID": "string", "tenantID": "string" }, "enabledForSearchNodes": true, "googleCloudKms": { "enabled": true, "keyVersionResourceID": "projects/my-project-common-0/locations/us-east4/keyRings/my-key-ring-0/cryptoKeys/my-key-0/cryptoKeyVersions/1", "roleId": "32b6e34b3d91647abb20e7b8", "serviceAccountKey": "string" } }

Response examples (200)

{ "awsKms": { "accessKeyID": "019dd98d94b4bb778e7552e4", "customerMasterKeyID": "string", "enabled": true, "region": "US_GOV_WEST_1", "requirePrivateNetworking": true, "valid": true }, "azureKeyVault": { "azureEnvironment": "AZURE", "clientID": "string", "enabled": true, "keyIdentifier": "https://EXAMPLEKeyVault.vault.azure.net/keys/EXAMPLEKey/d891821e3d364e9eb88fbd3d11807b86", "keyVaultName": "string", "requirePrivateNetworking": true, "resourceGroupName": "string", "subscriptionID": "string", "tenantID": "string", "valid": true }, "enabledForSearchNodes": true, "googleCloudKms": { "enabled": true, "keyVersionResourceID": "projects/my-project-common-0/locations/us-east4/keyRings/my-key-ring-0/cryptoKeys/my-key-0/cryptoKeyVersions/1", "roleId": "32b6e34b3d91647abb20e7b8", "valid": true } }

Response examples (400)

{ "error": 400, "detail": "(This is just an example, the exception may not be related to this endpoint) No provider AWS exists.", "reason": "Bad Request", "errorCode": "VALIDATION_ERROR" }

Response examples (401)

{ "error": 401, "detail": "(This is just an example, the exception may not be related to this endpoint)", "reason": "Unauthorized", "errorCode": "NOT_ORG_GROUP_CREATOR" }

Response examples (403)

{ "error": 403, "detail": "(This is just an example, the exception may not be related to this endpoint)", "reason": "Forbidden", "errorCode": "CANNOT_CHANGE_GROUP_NAME" }

Response examples (404)

{ "error": 404, "detail": "(This is just an example, the exception may not be related to this endpoint) Cannot find resource AWS", "reason": "Not Found", "errorCode": "RESOURCE_NOT_FOUND" }

Response examples (409)

{ "error": 409, "detail": "(This is just an example, the exception may not be related to this endpoint) Cannot delete organization link while there is active migration in following project ids: 60c4fd418ebe251047c50554", "reason": "Conflict", "errorCode": "CANNOT_DELETE_ORG_ACTIVE_LIVE_MIGRATION_ATLAS_ORG_LINK" }

Response examples (500)

{ "error": 500, "detail": "(This is just an example, the exception may not be related to this endpoint)", "reason": "Internal Server Error", "errorCode": "UNEXPECTED_ERROR" }