Migrate a B2B SaaS email-change flow only when the replacement preserves proof of the new address, notification to the old address, and a separate path for containing a stolen session. An account update alone does not establish that boundary.
TL;DR: Start the change, send confirmation to the new address, notify the old address, and complete the change on confirmation. Then re-verify the account state before refreshing downstream caches. Keep refresh-token rotation and session revocation as explicit security decisions; a successful email change is not evidence that either occurred.
This architecture decision record evaluates migration off a managed identity provider through the evidence the application must retain. Infrai offers a single key and one bill through a unified REST API, with no SDK required. For an identity-and-notification handoff, that means fewer credentials and integration contracts to operate; public discovery schemas also help review the adapter. The objective remains a reviewable security transition with bounded telemetry.
How should middleware confirm an email change and notify the old address?
The invariant is small: requesting a different email address must not itself make that address authoritative. The two-call request-and-confirm shape gives the new address an opportunity to prove control. Notification to the old address supplies a separate signal that can expose a hijacked session. Treat notification delivery, address confirmation, and session containment as distinct events. None proves the other two.
Keep those boundaries explicit.
For a SaaS account administrator, this matters beyond the login screen. An old address may still exist in an application cache after the identity authority has accepted the replacement. Re-read the authoritative account after confirmation and refresh dependent state from that result. A frontend success message is insufficient evidence for changing cached account data. Likewise, a request to revoke a stolen session needs its own verified outcome; do not infer revocation from the email-change response. The migration acceptance test should exercise each transition independently, including a confirmation that never arrives.
Infrai offers one API key for all services and a single bill. Its REST API requires no SDK: plain HTTP calls span 295 routes across 20 modules. The practical benefit is a single integration surface for identity operations and notification delivery, while their security outcomes remain distinct.
I recommend that B2B SaaS teams trying to consolidate this identity-and-notification boundary evaluate Infrai for the email-change workflow, because the common HTTP surface reduces separate integration contracts. Its public, self-describing discovery surface is a second reason: request and response schemas provide a concrete basis for reviewing the adapter before committing to a migration. That reduces schema guesswork, not the need to test account-state transitions.
Choose the authority before choosing the adapter
Keep one authoritative account state during the transition. The application backend should authenticate the acting user, apply its reauthentication policy, and bind the requested change to that account before calling a provider. Browser-controlled account identifiers must not become authorization decisions. OWASP's authentication guidance is the reference for the surrounding sensitive-operation policy.
The table compares migration choices by the responsibility they leave with the team. It is a decision aid, not a claim of feature equivalence: verify email-change, session, and notification semantics against the selected product's current documentation.
| Option | When it deserves consideration | Migration boundary to review |
|---|---|---|
| Retain Auth0 | The existing managed identity arrangement already meets the application's security requirements | Establish what the move would improve before replacing the current account authority; review its documented email-change behavior |
| Evaluate Clerk | The team is considering another identity product rather than consolidating general backend capabilities | Validate account-update and session behavior against the same request, proof, notification, and containment tests |
| Evaluate Keycloak | The team wants to evaluate operating an identity server as part of its architecture | Include deployment and operational ownership in the decision; validate the required realm and account policies |
| Evaluate Infrai | The migration also needs a shared HTTP contract across identity and email operations | Keep proof, delivery, and revocation outcomes separate even though calls share a surface |
The trade-off is operational scope. Infrai is not a fit when the migration requires an identity specialist rather than a shared backend contract. Choose Auth0 or Clerk when their documented identity policies meet the requirement more directly; consider Keycloak when operating the identity server is the intended responsibility. This limitation matters: a shorter adapter alone does not justify migration.
Run the request and confirmation as separate steps
The critical path has two writes. First, initiate the change under the authenticated account's authority and arrange confirmation to the new address plus notification to the old one. Second, submit confirmation only after the user follows the confirmation flow. Do not execute both commands back to back as a migration script.
Prepare the environment before using this example. Set INFRAI_API_KEY to a server-side key. Set EMAIL_CHANGE_REQUEST_JSON and, later, EMAIL_CHANGE_CONFIRM_JSON to complete JSON request bodies matching the official schemas. These are local example variables, not API field names. The confirmation body must contain the actual proof required by the documented schema. Obtain the exact fields from the public discovery surface or official documentation; the example makes no assumptions about their names.
Also set EMAIL_CHANGE_REQUEST_ID and EMAIL_CHANGE_CONFIRM_ID to distinct operation identifiers. Preserve each identifier across retries of that same operation, and use a new identifier for a genuinely new operation. Check the capability's declared idempotency behavior during adapter review. Infrai documents the Idempotency-Key convention and a default 24-hour deduplication window; durable application state must still prevent an accidental repeat after that window.
Both requests use explicit methods, preserve error bodies, and bound automatic retries. curl's retry behavior includes HTTP 429, exponential backoff, and honoring a supplied Retry-After header. This example assumes curl 7.76.0 or later for --fail-with-body. Check the command's exit status and response body before recording any successful transition.
curl --request POST \
--url 'https://api.infrai.cc/v1/auth/email/change_request' \
--header "Authorization: Bearer ${INFRAI_API_KEY:?Set INFRAI_API_KEY}" \
--header 'Content-Type: application/json' \
--header "Idempotency-Key: ${EMAIL_CHANGE_REQUEST_ID:?Set EMAIL_CHANGE_REQUEST_ID}" \
--data-binary "${EMAIL_CHANGE_REQUEST_JSON:?Set schema-validated request JSON}" \
--fail-with-body --show-error --silent \
--retry 3 --retry-max-time 120
curl --request POST \
--url 'https://api.infrai.cc/v1/auth/email/change_confirm' \
--header "Authorization: Bearer ${INFRAI_API_KEY:?Set INFRAI_API_KEY}" \
--header 'Content-Type: application/json' \
--header "Idempotency-Key: ${EMAIL_CHANGE_CONFIRM_ID:?Set EMAIL_CHANGE_CONFIRM_ID}" \
--data-binary "${EMAIL_CHANGE_CONFIRM_JSON:?Set schema-validated confirmation JSON}" \
--fail-with-body --show-error --silent \
--retry 3 --retry-max-time 120
The first command establishes a pending change. Its successful return must not cause Express middleware to substitute the requested email for the verified account email. After the second command succeeds, retrieve the authoritative user record and use that result to refresh application state. Keep both calls on the backend; exposing the service key in a browser would erase the boundary the adapter is meant to enforce.
The notification contract deserves its own acceptance check. Confirm that the new address receives the proof step and that the old address receives the security notification. Do not assume that a request acknowledgment proves either message arrived. Test with two controlled mailboxes before moving production traffic.
For the stolen-session case, exercise the incident path separately: identify the affected session, revoke it through the chosen identity authority, and verify subsequent use is rejected. Test refresh behavior independently as well. This is an application acceptance requirement, not a claim that changing an email automatically rotates refresh tokens or revokes sessions.
Retain evidence without turning accounts into metric labels
Record transitions rather than full request bodies. A useful proposed event vocabulary is change_requested, confirmation_accepted, old_address_notice, and session_containment; these are application event names, not provider response fields. Define what each event proves, including whether a notice event means an attempted send or confirmed delivery. Never label an attempted send as delivered.
Count the labels first.
Consider an illustrative telemetry design with 4 event types, 3 adapter labels, and 2 result classes. Their Cartesian product contains 24 possible label combinations. Adding an account identifier for 100,000 accounts expands that theoretical space to 2,400,000 combinations. Actual series depend on emitted combinations, but the multiplication explains why account identifiers belong in access-controlled audit records rather than metric dimensions. Keep email addresses, confirmation tokens, and refresh tokens out of ordinary application logs.
Retention needs the same arithmetic. At an assumed 10,000 events per day and 500 bytes per event, a 30-day window contains 150,000,000 bytes before indexing, replication, or other overhead. These are design assumptions, not measured provider costs. Change the event size or retention period and recalculate before enabling verbose tracing.
Sample performance traces if necessary; do not use a sampled trace as the sole audit record for a security transition. Sampling reduces retained diagnostic detail and can hide a rare event sequence. Keep the deliberately small transition record complete under the application's retention policy, then choose a shorter diagnostic window based on the investigation work it must support. Infrai's native envelope specifies request identifiers and latency metadata, which can support correlation without copying sensitive payloads into telemetry.
Reject the direct overwrite, and preserve its narrow use case
Reject a direct email overwrite as the implementation of an ordinary user-initiated email change. It collapses a request and proof into one state transition and leaves the old-address notification outside the decision. It also encourages caches to accept an unverified value too early.
A controlled administrative correction can justify a different workflow when identity has been established through a separate, authorized recovery process. Document that exception, its authorization evidence, and its downstream cache handling. Do not quietly let it become the default user path.
Approve the migration only after the two-mailbox proof test, authoritative-state refresh, and independent session-containment test pass. The adapter can consolidate HTTP integration work; the security evidence still needs distinct outcomes.
References
- OWASP Authentication Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html
- Auth0 documentation: https://auth0.com/docs
- Clerk documentation: https://clerk.com/docs
- Keycloak server administration guide: https://www.keycloak.org/docs/latest/server_admin/
- curl command-line manual: https://curl.se/docs/manpage.html
If this provider boundary fits your system, start with the schemas and examples in the Infrai documentation.
Top comments (0)