Rotating a provider credential, end to end

The flow#

1. Trigger — a credential has to change: it expired, the provider rotated it, somebody left, or it is suspected of having been seen.
2. User or external event — a person opens the mailbox or integration and enters the new value; or the provider invalidates the old one first and Connect finds out by failing.
3. Authentication and workspace resolution — the session resolves to one workspace, and the credential being replaced belongs to that workspace alone.
4. Ingest — the value arrives once, in the save. It is not logged, not echoed into a response and not written into any audit entry.
5. Canonical record — the settings store seals it. What is kept afterwards cannot be rendered back to a screen, including to the person who typed it.
6. Reasoning — none. Replacing a credential is an instruction, not a judgement the engine makes.
7. Knowledge, memory and rules — untouched. A credential is not memory, and forgetting a memory does not remove one.
8. Autonomy and approval — a permission question rather than an autonomy one: only a member allowed to change integrations can make this change.
9. Action through a provider — the next operation on the channel presents the new value. The provider is the only judge of whether it is right.
10. Result — health verdicts follow. Authenticating is not the same as being healthy: a mailbox that connects and returns nothing is a quiet mailbox, which is a signal rather than an error.
11. Relationship, timeline and memory — nothing about any person changes. A rotation is invisible to the people the workspace talks to.
12. Audit, usage and Needs You — the change is recorded as a change, without the value; a connection that fails afterwards escalates into Needs You rather than going quiet.

Verifying something you cannot read#

A screen that could show a stored credential would be a screen that leaks one, so no screen shows it. This changes how you confirm a rotation worked: there is nothing to compare, and the only meaningful evidence is the provider accepting an operation.

1. Save the new value while the old one is still valid at the provider.

   Result You have a working state to fall back to if the new value was mistyped.

2. Force an operation that must reach the provider — a fetch, or a send you were going to make anyway.

   Result Success is evidence. A screen that merely stops showing an error is not.

3. Read the health verdict rather than the connection state.

   Result Connected means the credentials were accepted. Healthy means mail is actually moving, which is the question you had.

4. Only then withdraw the old value at the provider.

   Result The rotation is finished, and at no point was the channel without a credential that works.

Work that is in flight#

• An operation the provider has already accepted completes at the provider. A rotation cannot reach back into it, and it does not need to.
• An operation not yet handed over uses the new value, because the value is read at the moment of use rather than cached at start-up.
• An operation refused because the old value stopped working is held rather than discarded, and the reason surfaces where health surfaces.
• A fetch that cannot complete does not advance its read cursor. Advancing a cursor past mail that was never read is how a mail agent loses messages permanently, so a refusal leaves the cursor where it was.

A connection based on a provider's own sign-in refreshes itself in normal operation, which is a rotation happening continuously rather than an event. The stored configuration is rewritten each time a fresh token arrives; a design that treated that record as read-only would drop every refresh and the connection would fail days later for no visible reason.

The failure this ordering prevents#

The expensive version of this operation is a copy. A credential copied somewhere convenient — a file, a second configuration, a note — is correct until whoever owns the original rotates it, and then it is wrong in a way nothing detects until the next restart. The symptom arrives long after the cause and looks exactly like a bad deployment, which is where the investigation goes first and stays longest.

A copy of a password somebody else rotates is that failure written up on its own terms. The rule it produces is short: one owner per credential, read at the moment of use, copied nowhere.

Questions#

Related#

• How provider credentials are stored
• A copy of a password somebody else rotates
• Mailbox health
• An integration disconnected
• Responding to a suspected access problem, end to end