---
schema_version: "1"
id: a884151381dc98484ef45119674bc91f318ef0b2f0609f9d0cde676bc97f0eeb
title: TenantSecret
collection: legacydeveloper
version: current
locale: en-us
portal_url: https://docs.salesforce.com/legacydeveloper/current/en-us/object_reference/sforce_api_objects_tenantsecret.md
canonical_url: https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_tenantsecret.htm
source_site: developer.salesforce.com
content_type: documentation
content_hash: d36a919862f89ed99e5b1bedb49875067c583c174a56116dd024010d2e5ec2a8
description: This object stores an encrypted organization-specific key fragment that’s used with the primary secret (KDF seed) to produce org-specific data encryption keys. This object is available in API version 34.0 and later.
---
# TenantSecret

This object stores an encrypted organization-specific key fragment that’s used with the primary secret (KDF seed) to produce org-specific data encryption keys. This object is available in API version 34.0 and later.

You can rotate tenant secrets of the Data type once every four hours in a sandbox org or every 24 hours in production orgs. You can rotate tenant secrets of the SearchIndex type one time every seven days.

![Note](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/images/icon_note.png)

#### Note

This information is about Shield Platform Encryption and not Classic Encryption.

## Supported Calls

create(), query(), retrieve(), update()

## Fields

<table class="featureTable sort_table" summary="">


          <thead class="thead sorted" align="left">
            <tr>
              <th class="featureTableHeader  " id="d1957520e94">Field Name</th>

              <th class="featureTableHeader  " id="d1957520e97">Details</th>

            </tr>

          </thead>

          <tbody class="tbody">
            <tr>
              <td class="entry" headers="d1957520e94" data-title="Field Name"><span class="keyword parmname">Description</span></td>

              <td class="entry" headers="d1957520e97" data-title="Details">
                <dl class="dl detailList">

                  <dt class="dt dlterm">Type</dt>

                  <dd class="dd">textarea</dd>



                  <dt class="dt dlterm">Properties</dt>

                  <dd class="dd">Create, Nillable, Update</dd>



                  <dt class="dt dlterm">Description</dt>

                  <dd class="dd">
                    <p class="p">The description of the tenant secret.</p>

                  </dd>


                </dl>

              </td>

            </tr>

            <tr>
              <td class="entry" headers="d1957520e94" data-title="Field Name"><span class="keyword parmname">KeyDerivationMode</span></td>

              <td class="entry" headers="d1957520e97" data-title="Details">
                <dl class="dl detailList">

                  <dt class="dt dlterm">Type</dt>

                  <dd class="dd">picklist </dd>



                  <dt class="dt dlterm">Properties</dt>

                  <dd class="dd">Create, Filter, Group, Restricted picklist, Sort</dd>



                  <dt class="dt dlterm">Description</dt>

                  <dd class="dd">
                    <div class="p">The key derivation mode applied to customer-supplied key
                      material. Modes are: <dl class="dl detailList">

                        <dt class="dt dlterm">PBKDF2</dt>

                        <dd class="dd">The customer-supplied key material is used by the
                          Shield KMS to create a derived data encryption
                          key.</dd>



                        <dt class="dt dlterm">NONE</dt>

                        <dd class="dd">The customer-supplied key material is used by the
                          Shield KMS as the final data encryption key to directly
                          encrypt and decrypt data.</dd>


                      </dl>
                    </div>

                    <p class="p">Available in API version 43.0 and later.</p>

                  </dd>


                </dl>

              </td>

            </tr>

            <tr>
              <td class="entry" headers="d1957520e94" data-title="Field Name"><span class="keyword parmname">RemoteKeyCertificate</span></td>

              <td class="entry" headers="d1957520e97" data-title="Details">
                <dl class="dl detailList">

                  <dt class="dt dlterm">Type</dt>

                  <dd class="dd">string</dd>



                  <dt class="dt dlterm">Properties</dt>

                  <dd class="dd">Create, Filter, Group, Nillable, Sort, Update</dd>



                  <dt class="dt dlterm">Description</dt>

                  <dd class="dd">The name of the certificate whose public key is used to encrypt
                    the <span class="keyword parmname">SecretValue</span> during a remote key
                    callout.<p class="p">Available in API version 45.0 and later.</p>
                  </dd>


                </dl>

              </td>

            </tr>

            <tr>
              <td class="entry" headers="d1957520e94" data-title="Field Name"><span class="keyword parmname">RemoteKeyIdentifier</span></td>

              <td class="entry" headers="d1957520e97" data-title="Details">
                <dl class="dl detailList">

                  <dt class="dt dlterm">Type</dt>

                  <dd class="dd">string</dd>



                  <dt class="dt dlterm">Properties</dt>

                  <dd class="dd">Create, Filter, Group, Nillable, Sort</dd>



                  <dt class="dt dlterm">Description</dt>

                  <dd class="dd">A unique key identifier for key material fetched from a remote key
                    service.<p class="p">Available in API version 45.0 and later.</p>
                  </dd>


                </dl>

              </td>

            </tr>

            <tr>
              <td class="entry" headers="d1957520e94" data-title="Field Name"><span class="keyword parmname">RemoteKeyServiceID</span></td>

              <td class="entry" headers="d1957520e97" data-title="Details">
                <dl class="dl detailList">

                  <dt class="dt dlterm">Type</dt>

                  <dd class="dd">reference</dd>



                  <dt class="dt dlterm">Properties</dt>

                  <dd class="dd">Create, Filter, Group, Nillable, Sort, Update</dd>



                  <dt class="dt dlterm">Description</dt>

                  <dd class="dd">The named credential used to fetch remote key material from a
                    remote key service.<p class="p">Available in API version 45.0 and
                      later.</p>
                  </dd>


                </dl>

              </td>

            </tr>

            <tr>
              <td class="entry" headers="d1957520e94" data-title="Field Name"><span class="keyword parmname">SecretValue</span></td>

              <td class="entry" headers="d1957520e97" data-title="Details">
                <dl class="dl detailList">

                  <dt class="dt dlterm">Type</dt>

                  <dd class="dd">base64</dd>



                  <dt class="dt dlterm">Properties</dt>

                  <dd class="dd">Create, Nillable, Update</dd>



                  <dt class="dt dlterm">Description</dt>

                  <dd class="dd">
                    <p class="p">The encrypted 256-bit secret value encoded in base64.</p>

                  </dd>


                </dl>

              </td>

            </tr>

            <tr>
              <td class="entry" headers="d1957520e94" data-title="Field Name"><span class="keyword parmname">SecretValueCertificate</span></td>

              <td class="entry" headers="d1957520e97" data-title="Details">
                <dl class="dl detailList">

                  <dt class="dt dlterm">Type</dt>

                  <dd class="dd">string</dd>



                  <dt class="dt dlterm">Properties</dt>

                  <dd class="dd">Create, Filter, Group, Nillable, Sort, Update</dd>



                  <dt class="dt dlterm">Description</dt>

                  <dd class="dd">
                    <p class="p">The certificate needed to upload a customer-supplied tenant
                      secret. Each certificate has a unique name.</p>

                  </dd>


                </dl>

              </td>

            </tr>

            <tr>
              <td class="entry" headers="d1957520e94" data-title="Field Name"><span class="keyword parmname">SecretValueHash</span></td>

              <td class="entry" headers="d1957520e97" data-title="Details">
                <dl class="dl detailList">

                  <dt class="dt dlterm">Type</dt>

                  <dd class="dd">base64</dd>



                  <dt class="dt dlterm">Properties</dt>

                  <dd class="dd">Create</dd>



                  <dt class="dt dlterm">Description</dt>

                  <dd class="dd">
                    <p class="p">The matching tenant secret hash for an uploaded
                      customer-supplied tenant secret.</p>

                  </dd>


                </dl>

              </td>

            </tr>

            <tr>
              <td class="entry" headers="d1957520e94" data-title="Field Name">
                <span class="keyword parmname">Source</span>
              </td>

              <td class="entry" headers="d1957520e97" data-title="Details">
                <dl class="dl detailList">

                  <dt class="dt dlterm">Type</dt>

                  <dd class="dd">picklist</dd>



                  <dt class="dt dlterm">Properties</dt>

                  <dd class="dd">Create, Default on create, Filter, Group, Restricted picklist,
                    Sort</dd>



                  <dt class="dt dlterm">Description</dt>

                  <dd class="dd">The source of the encryption key material. Values are:<dl class="dl detailList">

                      <dt class="dt dlterm">HSM</dt>

                      <dd class="dd">A Salesforce-generated tenant secret.</dd>



                      <dt class="dt dlterm">Uploaded</dt>

                      <dd class="dd">A customer-supplied tenant secret or data encryption
                        key.</dd>



                      <dt class="dt dlterm">Remote</dt>

                      <dd class="dd">A tenant secret or data encryption key fetched from a key
                        service outside of Salesforce. Available in API version
                        44.0 and later.Tenant secrets with a
                        <span class="keyword parmname">Source</span> value of Remote are listed
                        as Fetched on the Key Management page in Setup.
                      </dd>


                    </dl>
                    <p class="p">Available in API version 43.0 and later.</p>
                  </dd>


                </dl>

              </td>

            </tr>

            <tr>
              <td class="entry" headers="d1957520e94" data-title="Field Name"><span class="keyword parmname">Status</span></td>

              <td class="entry" headers="d1957520e97" data-title="Details">
                <dl class="dl detailList">

                  <dt class="dt dlterm">Type</dt>

                  <dd class="dd">picklist</dd>



                  <dt class="dt dlterm">Properties</dt>

                  <dd class="dd">Filter, Group, Nillable, Restricted picklist, Sort, Update</dd>



                  <dt class="dt dlterm">Description</dt>

                  <dd class="dd">
                    <div class="p">The status of the tenant secret. Values are: <dl class="dl detailList">

                        <dt class="dt dlterm">Active</dt>

                        <dd class="dd">Can be used to encrypt and decrypt new or existing
                          data.</dd>



                        <dt class="dt dlterm">Archived</dt>

                        <dd class="dd">Can’t encrypt new data. Can be used to decrypt data
                          previously encrypted with this key when it was active.
                        </dd>



                        <dt class="dt dlterm">Destroyed</dt>

                        <dd class="dd">Can’t encrypt or decrypt data. Data encrypted with
                          this key when it was active can no longer be decrypted.
                          Files and attachments encrypted with this key can no
                          longer be downloaded.</dd>


                      </dl>
                    </div>

                  </dd>


                </dl>

                <p class="p">You can update the <span class="keyword parmname">Status</span> field through the API in
                  versions 44.0 or later.</p>

              </td>

            </tr>

            <tr>
              <td class="entry" headers="d1957520e94" data-title="Field Name"><span class="keyword parmname">Type</span></td>

              <td class="entry" headers="d1957520e97" data-title="Details">
                <dl class="dl detailList">

                  <dt class="dt dlterm">Type</dt>

                  <dd class="dd">picklist</dd>



                  <dt class="dt dlterm">Properties</dt>

                  <dd class="dd">Create, Default on create, Filter, Group, Restricted picklist,
                    Sort</dd>



                  <dt class="dt dlterm">Description</dt>

                  <dd class="dd">The type of tenant secret. The <span class="keyword parmname">Type</span> field is
                    available in API version 39.0 and later. The following values
                    appear in the <span class="keyword parmname">Type</span> picklist:<ul class="ul bulletList">
                      <li class="li">
                        <span class="keyword parmname">Analytics</span>—CRM Analytics data
                        (available in API version 39.0 and later).
                      </li>

                      <li class="li">
                        <span class="keyword parmname">Data</span>—data stored in the
                        Salesforce database. Includes data in encrypted fields,
                        files, and attachments but not search index files. Tenant
                        secrets created in API version 34.0 and later default to the
                        <span class="keyword parmname">Data</span> type.
                      </li>

                      <li class="li">
                        <span class="keyword parmname">Database</span>—transactional database
                        including standard and custom fields, metadata, and Apex
                        (available in API version 62.0 and later).
                      </li>

                      <li class="li">
                        <span class="keyword parmname">DeterministicData</span>—data stored in
                        the Salesforce database. Includes data in encrypted fields,
                        files, and attachments, but not search index files (available
                        in API version 39.0 and later).
                      </li>

                      <li class="li">
                        <span class="keyword parmname">EventBus</span>—Change Data Capture
                        event data (available in API version 43.0 and later).
                      </li>

                      <li class="li">
                        <span class="keyword parmname">SearchIndex</span>—search index files
                        (available in API version 39.0 and later). <p class="p">For Hyperforce
                          orgs on API version 63.0 and later, create secrets of type
                          <span class="keyword parmname">SearchIndex</span> with the <a class="xref" href="https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_dataencryptionkey.htm" title="The DataEncryptionKey object is part of the Bring Your Own Key (BYOK) feature, which allows users to upload a data encryption key (DEK) using a public key generated by the Salesforce Shield Key Management Service (KMS). Customers create their own DEKs and upload them to Salesforce. Users access this entity via the API to list DEK keys for auditing purposes. They can also programmatically use this object to create the certificate and to upload key material. This object is available in API version 63.0 and later.">DataEncryptionKey</a> object. For Hyperforce orgs
                          on API version 62.0 and earlier, and for all
                          non-Hyperforce orgs, create secrets of type
                          <span class="keyword parmname">SearchIndex</span> with the TenantSecret
                          object.
                        </p>
                      </li>

                    </ul>
                  </dd>


                </dl>

              </td>

            </tr>

            <tr>
              <td class="entry" headers="d1957520e94" data-title="Field Name"><span class="keyword parmname">Version</span></td>

              <td class="entry" headers="d1957520e97" data-title="Details">
                <dl class="dl detailList">

                  <dt class="dt dlterm">Type</dt>

                  <dd class="dd">int</dd>



                  <dt class="dt dlterm">Properties</dt>

                  <dd class="dd">Filter, Group, idLookup, Sort</dd>



                  <dt class="dt dlterm">Description</dt>

                  <dd class="dd">
                    <p class="p">The version number of this secret. The version number is unique
                      within your org.</p>

                  </dd>


                </dl>

              </td>

            </tr>

          </tbody>

        </table>

## Usage

Use this object to create or update an org-specific tenant secret or customer-supplied key material.

Use your preferred developer environment to run the examples. Use the Salesforce developer [Introduction to REST API](https://developer.salesforce.com/docs/atlas.en-us.264.0.api_rest.meta/api_rest/intro_rest.htm) for basic information on making REST calls into Salesforce. Also, the video [How To Use Salesforce APIs Collection With Postman](https://www.youtube.com/watch?v=DJ7_iW2B5tA) by Sudipta Deb provides step by step instructions on getting started using REST with Salesforce.

## Example 1:

Build an automated tenant secret creation and activation solution similar to the following.

1. Start by creating an Apex class to create the tenant secret. Specify the value of the tenant secret to encrypt data of a particular type.
    
    global class CreateNewSecret implements Schedulable {
       global void execute(SchedulableContext SC) {
          TenantSecret secret = new TenantSecret ();
          secret.description = 'Created new secret from scheduled job';
          secret.type= 'Database';
          insert secret;
       }
    }
                   
    
    ![Note](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/images/icon_note.png)
    
    #### Note
    
    Type is available in API version 39.0 and later. Type is optional; all tenant secrets default to the Data type.
2. Schedule the Apex class to run at the specified interval.
    
    This Apex code only needs to be run a single time to schedule the job. This code runs the job every 90 days.
    
    CreateNewSecret secret = new CreateNewSecret();
    String schedule = '0 0 0 1 JAN,APR,JUL,OCT ?';
    String jobID = system.schedule('Automated secret creation and activation', schedule, secret);
3. Validate that the job is scheduled.
4. Validate that tenant secrets are created after the job is run.

## Example 2

Upload a customer-supplied tenant secret.

1. Create a certificate that’s compatible with customer-supplied key material. See [Generate a BYOK-Compatible Certificate](https://help.salesforce.com/articleView?id=security_pe_byok_generate_cert.htm&language=en_US) in Salesforce Help.
2. Then upload your matching key material and key material hash. Include the unique name of the compatible certificate. The key material is uploaded in encrypted form.
    
          TenantSecret secret = new TenantSecret ();
          secret.description = 'New uploaded secret';
          secret.type= 'Data';
          secret.SecretValue = ...
          EncodingUtil.base64Decode('...');;
          secret.SecretValueCertificate = ...;
          secret.SecretValueHash = ...
          EncodingUtil.base64Decode('...');
          insert secret;
    
    You can use this [script to generate a customer-supplied tenant secret](https://help.salesforce.com/s/articleView?id=xcloud.security_pe_byok_script.htm&type=5&language=en_US) and tenant secret hash.
3. Validate that the key material is uploaded.

## Example 3

Opt out of key derivation on a key-by-key basis when you upload key material. When you upload your key material, specify 'Source':Uploaded and 'KeyDerivationMode':'NONE', and set non-null values for the SecretValueCertificate, SecretValue, and SecretValueHash.

## Example 4

Import a tenant secret of the Data type.

TenantSecret secret = \[SELECT Id FROM TenantSecret WHERE Type = 'Data' AND Version = 2\];
secret.SecretValue = "<previously\_exported\_secret\_as\_a\_String>";
update secret;

## Example 5

Export a tenant secret by writing the secret.SecretValue to a file. Here’s an example that uses a tenant secret of the Data type.

TenantSecret secret = \[SELECT SecretValue FROM TenantSecret WHERE Type = 'Data' AND Version = 2\];
secret.SecretValue =...;
update secret;

## Example 6

Destroy a tenant secret of the Data type.

![Warning](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/images/icon_note_warning.png)

#### Warning

Your tenant secret is unique to your organization and to the specific data to which it applies. When you destroy a tenant secret, related data isn’t accessible unless you previously exported the key and then import the key back into Salesforce.

TenantSecret secret = \[SELECT Id FROM TenantSecret WHERE Type = 'Data' AND Version = 2\];
secret.SecretValue = NULL;
secret.Status = Destroyed;
update secret;

## Example 7

Change the Status of a tenant secret from Archived to Destroyed. Include the SecretValue and new tenant secret Status.

TenantSecret secret = \[SELECT Id FROM TenantSecret WHERE Type = 'Data' AND Version = 2\];
secret.Status = Destroyed;
update secret;

Cache-Only Key Service customers can change the Status of cache-only key tenant secrets. For example, reactivate a cache-only key by changing its Status from Destroyed to Active.

## Example 8

Create a callout connection that fetches a cache-only key tenant secret from a key service outside of Salesforce.

1. Make sure that your org has at least one active Data in Salesforce key, either Salesforce-generated or customer-supplied. Then turn on Allow Cache-Only Keys with BYOK from the Advanced Settings page in Setup.
2. Create a certificate that’s compatible with customer-supplied key material. See [Generate a BYOK-Compatible Certificate](https://help.salesforce.com/articleView?id=security_pe_byok_generate_cert.htm&language=en_US) in Salesforce Help.
3. [Create and assemble your key material](https://help.salesforce.com/articleView?id=security_pe_byok_cache_create.htm&language=en_US).
4. Create a named credential to serve as your authenticated callout mechanism. You can define your named credential through Setup or [directly with Apex](https://developer.salesforce.com/docs/atlas.en-us.264.0.apexcode.meta/apexcode/apex_callouts_named_credentials.htm). Specify a BYOK-compatible certificate and an HTTPS endpoint.
5. Configure the connection to your remote key service. This connection uses a named credential and its associated certificate to fetch a specified cache-only key tenant secret.
    
    remote\_params = { 'Source': 'Remote', 
    'RemoteKeyIdentifier': ...,
    'RemoteKeyServiceId': ...,
    'RemoteKeyCertificate': ...}
    
    sf.TenantSecret.create(remote\_params)

#### See Also

- [System Fields](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/system_fields.htm "System fields are read-only fields found on most objects. These fields are automatically updated during API operations. For example, the ID field is automatically generated during a create operation and the LastModifiedDate is automatically updated when a user modifies a record.")