Integration credentials — API keys, tokens, OAuth client secrets — live in each integration app's secret store. A secret is saved once, encrypted, and bound to its app; from that moment it is write-only. No screen, API or export ever returns the value. Everything that needs the credential holds a reference (${secret:name}) instead, resolved freshly at execution time — which is exactly what makes rotation an in-place update with no configuration edits.
Prerequisites
- The integration administration capability, plus the Admin role on the app — secrets are the one part of an app that ConnectionManager does not cover.
- The new credential value from the external system, when rotating.
Procedure
Step 1 — Store a secret
Go to Setup → Process Studio → Integrations, open the app that owns the connection, and select Secrets. Confirm the app name and your Admin role before choosing Add Secret. Use a stable descriptive reference such as partner-api-token, paste the value once over a private connection, and save. Reopen the list and verify reference, key id and timestamps appear while the value does not; if the value is ever displayed, stop and report the security defect.
Step 2 — Reference it
Edit each connection or connector step and select or enter ${secret:partner-api-token} instead of the credential itself. Save, reopen and verify configuration contains only the reference. Search the app's flows and connections for old inline values before activation. One reference may serve several consumers; inventory them because every consumer must be tested during rotation.
Step 3 — Rotate
- Generate the replacement externally first. Prefer an overlap window and record the old/new key identifiers, owner and rollback deadline.
- Pause or avoid a high-volume window, open the same secret reference's rotate action, paste the replacement, and save once. Verify the last-rotated timestamp changed; references require no edit or restart because resolution occurs per execution.
- Run Test Connection on every inventoried consumer and preserve the result. A test on only one connection does not prove scopes required by another.
- Watch one real scheduled or manual read-only cycle on the health board and verify authentication plus business operation succeeded.
Step 4 — Revoke the old credential externally
Only after every consumer and one live cycle pass, revoke the old key at the provider. Verify a subsequent cycle still succeeds and close the rotation record with timestamps and evidence. If the replacement is mis-scoped, restore the old value under the same reference during the overlap window rather than editing connections.
Expected result
Every connection stores only a write-only secret reference, all consumers resolve the replacement credential without configuration changes, and both connection tests and a live cycle succeed. The former credential is revoked externally only after verification, with an auditable rotation timestamp and rollback evidence.
OAuth credentials
Connectors that authenticate with OAuth (Salesforce, the Zoho family) manage their own short-lived access tokens — you never store or rotate those. What you store are the durable pieces: client id, client secret, and the refresh token or integration-user password. Rotate each as its own secret, same procedure. Two behaviors worth knowing: a revoked refresh token or deactivated integration user is a configuration fault — runs fail with the provider's OAuth error until you fix the secret, and the platform deliberately does not endlessly retry a credential the provider has rejected; and rotating the client secret of a connected/API app usually invalidates refresh tokens minted under the old one, so plan those two rotations together.
Common problems
- Deleted a secret that was still referenced. Every connection test and run using the reference now fails at resolution. Re-create the secret under the same reference name with a valid value — the references never changed, so everything recovers immediately.
- Rotated in xMatix before the external system. Runs fail with auth errors until the external side catches up. No harm done: fix the external side (or paste the old value back) and re-test.
- Rotation "didn't take". It almost certainly did — check that you rotated the reference the failing connection actually uses (apps can hold several similar-sounding secrets), and read the run's error text, which carries the provider's own verdict.
Common questions
Can I read a secret back if I lose it?
No — write-only means exactly that; the value is not retrievable by anyone, including platform operators. Losing a credential is handled the same way as rotating it: generate a new one at the provider and upsert it under the same reference. Treat the external provider's console as the system of record for the credential itself.
Who can manage secrets?
Holders of the Admin role on that specific app (membership is granted per security profile on the app's Members tab). Viewer, Operator and ConnectionManager roles cannot add or rotate secrets — ConnectionManager covers connections only. Since secrets are write-only, even Admins only ever see metadata.
How often should keys rotate?
Follow your security policy and the provider's guidance — the mechanics here make rotation cheap, so quarterly rotations or immediate rotation on staff departure are practical rather than painful. The last-rotated timestamp on the Secrets tab is the audit surface: a secret that has never rotated shows it.
Is the credential exposed anywhere in configuration or logs?
Configuration holds only ${secret:...} references, and run diagnostics redact secret values from step input/output snapshots. The value exists in usable form only inside the executing connector call.