{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"redocly_category":"Guides","type":"markdown"},"seo":{"title":"Rotate client secrets","description":"Everything about Mosaic Journeys, SDKs, and APIs","siteUrl":"https://developer.transmitsecurity.com/","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"rotate-client-secrets","__idx":0},"children":["Rotate client secrets"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For security purposes, you can rotate a client secret without changing the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}," and without introducing downtime to your integration. This lets you update backend services gradually and revoke the old secret only after the rollout is complete."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This applies to OIDC clients that authenticate using a client secret, including management app clients."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"recommended-rotation-flow","__idx":1},"children":["Recommended rotation flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use this sequence to rotate a secret safely:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Generate a new client secret for the client."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Update your backend services, jobs, and integrations to start using the new secret."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verify that the updated systems can still obtain tokens successfully."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Revoke the old secret after the rollout is complete."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["During the transition period, both secrets remain valid so your systems can move over without changing the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]},"."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Limits and behavior"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Keep these rules in mind when planning the rollout:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A client can have up to two active client secrets at the same time."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You can't generate a third active secret until one of the current secrets is revoked."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["You can't revoke the last remaining secret."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["client_id"]}," does not change during rotation."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Existing integrations can keep working with the old secret until you revoke it."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"deployment-guidance","__idx":2},"children":["Deployment guidance"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To avoid service disruption during rotation:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store the new secret in your secret manager before updating application code or configuration."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Roll out backend services gradually if multiple systems share the same client."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Validate token retrieval after each rollout stage."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Revoke the old secret only after all environments and scheduled processes are confirmed to use the new one."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Important"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Never expose client secrets in browser or mobile code. Store them only in secure backend systems and secret-management tools."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"manage-rotated-secrets","__idx":3},"children":["Manage rotated secrets"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can manage client secret rotation in either of these ways:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Admin Portal"]}," > ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Applications"]}," > your app > your client > ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client configuration"]},": use the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client Secret 1"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["2"]}," settings to generate and revoke secrets."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API"]},": Use the client secret management endpoints under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v1/applications/{appId}/clients/{clientId}/secrets"]},"."]}]}]},"headings":[{"value":"Rotate client secrets","id":"rotate-client-secrets","depth":1},{"value":"Recommended rotation flow","id":"recommended-rotation-flow","depth":2},{"value":"Deployment guidance","id":"deployment-guidance","depth":2},{"value":"Manage rotated secrets","id":"manage-rotated-secrets","depth":2}],"frontmatter":{"title":"Rotate client secrets","markdown":{"toc":{"depth":3}},"seo":{"title":"Rotate client secrets"}},"lastModified":"2026-06-11T15:00:37.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/deployment/rotate_client_secrets","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}