Salesforce Marketing Cloud: Client Secret Rotation Guide

Marketing Cloud Engagement
OAuth 2.0 Client Secret Rotation Guide

1. Purpose

This document provides the recommended procedure for rotating an OAuth 2.0 client secret used by a Marketing Cloud Engagement installed package. The process is designed to allow the external application or integration to be updated before the existing secret is deactivated.

2. Step-by-Step Procedure

Step 1 — Open Installed Packages

1. Log in to Marketing Cloud Engagement with an administrator account.
2. Navigate to Setup.
3. In the Quick Find box, enter Packages.
4. Open Installed Packages.
Select the installed package containing the OAuth 2.0 API Integration whose secret is being rotated.

Step 2 — Generate and Stage the New Secret

1. In the selected package, locate the Staged Secret section.
2. Click Generate.

3. Enter a meaningful description for the new secret, for example: 'OAuth Secret Rotation - October 2026'.
4. Click Next.

5. Securely copy the newly generated client secret into the organization's approved password/secret-management system.
6. Click Finish.

Step 3 — Wait for Staging to Become Usable

Wait at least 5 minutes after staging the new secret.
During this period, Marketing Cloud can accept authentication requests using either the existing active secret or the newly staged secret.
This overlap allows the external application/integration to be updated before the old secret is deactivated.

Step 4 — Update the External Integration

Update every external application, middleware component, script, integration service, or API client that uses the package's client secret. Replace the old client secret with the newly staged secret.
Keep the Client ID unchanged unless the integration is being reconfigured for another package.
Keep the authentication base URI and other endpoint configuration unchanged unless the integration specifically requires a change.
Do not share the client secret in plain text through email or chat.
If the integration uses environment variables or a secrets manager, update the secret there and restart/redeploy the integration if required.

Step 5 — Activate the New Secret

1. Return to Setup → Installed Packages.
2. Open the same installed package.
3. In the Staged Secret section, click Activate.
4. Confirm the activation if prompted.

Activation makes the staged secret the active secret and immediately deactivates the previous active secret.Critical: Once the new secret is activated, any application still using the previous secret can no longer authenticate. Make sure all dependent integrations have been updated before activation.

3. Salesforce Reference

Official Salesforce Developers documentation:

Rotate an OAuth 2.0 Secret: 
https://developer.salesforce.com/docs/marketing/marketing-cloud/guide/rotate-oauth2-secret.html

Additional Salesforce documentation consulted for this guide includes the OAuth 2.0 API Integration, integration considerations, and API security documentation.