ExternalEncryptionRootKey | Object Reference for the Salesforce Platform

Root keys are used to generate data encryption keys (DEKs) in Salesforce, which are in turn used to encrypt and decrypt data. Root keys are also used as wrapping keys to secure DEKs in the Salesforce database.

Supported Calls

describeSObjects(), query(), update()

Special Access Rules

This object is available as part of the Shield and Salesforce Platform Encryption add-on subscriptions. Access to this object also requires the Cache-Only Key Service add-on subscription.

Fields

Field	Details
ActivatedDate	Type dateTime Properties Filter, Nillable, Sort, Update Description The date the key was activated in Salesforce.
CreatedBy	Type string Properties Filter, Group, Nillable, Sort, Update Description The email address of the user who created the root key. For example, `user@example.com`.
Description	Type string Properties Filter, Group, Nillable, Sort, Update Description The user-defined description of the root key.
LastModifiedBy	Type string Properties Filter, Group, Nillable, Sort, Update Description The email address of the user who most recently modified the key. For example, `user@example.com`.
Region	Type string Properties Filter, Group, Nillable, Sort, Update Description The region for the customer managed key. For example, if the RootKeyService is `AWS`, the region is an Amazon Web Services (AWS) region such as `us-east1`.
RootKeyIdentifier	Type string Properties Filter, Nillable, Sort, Update Description The unique key identifier from the external KMS, such as an AWS Amazon Resource Name (ARN). For example, `arn:aws:kms:us-west-2:123456789000:key/123ab456-7cd8-9012-3e4f-5gh678i901j2`
RootKeyService	Type string Properties Filter, Group, Nillable, Sort, Update Description The external key management service connected to Salesforce. For example, `AWS`.
Status	Type string Properties Filter, Group, Nillable, Sort, Update Description The status of the key. This is the only value that can be changed using update(). You can only change the status from Active to Inactive, or from Inactive to Active. Possible values are: `Activation Pending`—Salesforce is waiting for confirmation of a valid key policy in the external key store. `Active`—Can be used to encrypt new DEKs and decrypt existing DEKs. `Archived`—Can’t encrypt new DEKs. Can be used to decrypt previously created DEKs. `Canceled`—Root key activation canceled by a user. `Inactive`—The root key, and the DEKs that it encrypts, are inaccessible. Inaccessible DEKs can’t be used to decrypt data, which renders that data also inaccessible. `Unavailable`—The root key, and the DEKs that it encrypts, cannot be accessed. The root key has been removed or deactivated by the managing KMS.

Usage

Three functions are available: describeSObjects(),query(), and update()

Use your preferred developer environment to run the examples. Use the Salesforce developer Introduction to REST API for basic information on making REST calls into Salesforce. Also, Introducing the Salesforce Shield Platform Encryption REST API gives you starter information on using REST to work with Shield Platform Encryption.

Describe an external root key with describeSObjects()

To get information about the ExternalEncryptionRootKey sObject, use describe.

1curl --location 'https://DOMAIN.my.salesforce.com/services/data/v62.0/sobjects/'\ 
2ExternalEncryptionRootKey/describe'
3--header 'Content-Type: application/json' \
4--header 'Authorization: Bearer TOKEN'

On success, the response is the full JSON description of the ExternalEncryptionRootKey sObject.

Get info on an external root key with query()

To get information about a specific root key, use query on the ExternalEncryptionRootKey sObject. Use the Identifier value as listed on the Key Management Page for the root key Id in the WHERE clause.

1curl --location 'https://DOMAIN.my.salesforce.com/services/data/v62.0/query?' \
2?q=SELECT+FIELDS(ALL)+FROM+ExternalEncryptionRootKey+WHERE+Id='48q001t5ddzbucnAAA'+\
3--header 'Content-Type: application/json' \
4--header 'Authorization: Bearer TOKEN'

On success, the response is be similar to

1{
2    "totalSize": 1,
3    "done": true,
4    "records": [
5        {
6            "attributes": {
7                "type": "ExternalEncryptionRootKey",
8                "url": "/services/data/v62.0/sobjects/ExternalEncryptionRootKey/48q001t5ddzbucnAAA"
9            },
10            "Id": "48q001t5ddzbucnAAA",
11            "RootKeyIdentifier": "97ee8238-c5ac-4320-a2d0-a728aaefd567",
12            "CreatedDate": "2024-08-05T17:32:11.841+0000",
13            "CreatedBy": "charley.t.pulasky@wise-raccoon-od1ly6.com",
14            "LastModifiedDate": "2025-02-12T18:36:11.063+0000",
15            "LastModifiedBy": "charley.t.pulasky@wise-raccoon-od1ly6.com",
16            "RootKeyService": "SF",
17            "Region": "KEY REGION",
18            "Status": "Active",
19            "Description": null,
20            "ActivatedDate": null
21        }
22    ]
23}

Update Status on an external root key with update()

To update the status of an ExternalEncryptionRootKey from Active to Inactive, or from Inactive to Active, use PATCH on the specific key object. Use the vaule for Identifier as listed on the Key Management Page for the root key identifier.

1curl --location --request PATCH 'https://DOMAIN.my.salesforce.com/services/data/v62.0/sobjects/ExternalEncryptionRootKey/ROOTKEYIDENTIFIER' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer TOKEN'\
4--data '{
5	"Status": "Active"
6}'

On success, the response is be similar to I SEE NO RESPONSE.