Verified security contacts

A verified security contact is a purpose-bound email address or phone number that ProAuth may use for profile display, security notifications, password recovery, passkey recovery, or login-name coupling. It is separate from an unverified profile value.

Why contacts are modeled separately

Treating every profile email as a recovery address creates a dangerous shortcut: any system that can edit the profile could also take over account recovery. ProAuth therefore records how a contact was verified, which security purposes it is allowed to serve, whether it is primary, and whether it is active, revoked, or superseded.

Generic user CRUD cannot mark a contact as verified. SCIM and federation can propose profile data, but they cannot manufacture possession evidence.

Contact purposes

Purposes is a flags value. A contact may have more than one purpose.

Purpose	Meaning	Guidance
PrimaryProfile	The primary user-facing profile contact.	Use for the address displayed as the user's main contact.
SecurityNotification	Destination for security-event notifications.	Assign at least one verified address whenever possible.
PasswordRecovery	May receive password-recovery proof.	Do not assign to shared mailboxes unless shared recovery is an explicit business requirement.
PasskeyRecovery	May participate in a passkey recovery route.	Mailbox proof remains a lower-assurance route and produces a restricted recovery session.
LoginName	Couples this email contact to the local login name.	Supported for email contacts only. Use when users sign in with their verified email address.

Supported contact types are Email and Phone. LoginName is invalid for a phone contact.

Keep roles understandable

For most consumer deployments, one verified primary email can serve PrimaryProfile, SecurityNotification, PasswordRecovery, and PasskeyRecovery. Workforce deployments often separate the login name from the notification or recovery address.

Lifecycle and provenance

The record includes a provenance value:

• UserVerified — the user completed a possession challenge;
• AdministratorVerified — a governed administrator workflow established verification;
• LegacyConfirmedBackfill — migration converted a previously confirmed UserStore email.

An unconfirmed legacy email is never backfilled as verified.

Add and verify a contact

Administrators use UserStore API v2:

GET  /api/userstore/v2/{userstoreId}/administration/users/{userId}/passkey-recovery/security-contacts
POST /api/userstore/v2/{userstoreId}/administration/users/{userId}/passkey-recovery/security-contacts
POST /api/userstore/v2/{userstoreId}/administration/users/{userId}/passkey-recovery/security-contacts/{contactId}/verify

Example enrollment request:

{
  "type": "Email",
  "value": "alex@example.com",
  "purposes": "PrimaryProfile, SecurityNotification, PasswordRecovery, PasskeyRecovery",
  "isPrimary": true
}

The create response does not contain the verification secret. ProAuth places the secret in a protected durable notification intent. The verification lifetime is controlled by PasskeyRecoveryEmailTokenLifetimeSeconds; see Passkey policy option reference.

Replace a contact safely

Replacing a verified contact is a separate transaction, not an in-place profile edit.

Use these endpoints:

POST /api/userstore/v2/{userstoreId}/administration/users/{userId}/passkey-recovery/security-contacts/{contactId}/replacement
POST /api/userstore/v2/{userstoreId}/administration/users/{userId}/passkey-recovery/security-contact-replacements/{transactionId}/confirm

The start command contains ReplacementValue, Purposes, and IsPrimary. The confirmation command contains both proof tokens and ExplicitConfirmation=true.

The transaction is bound to the UserStore user, current contact, candidate contact, purpose set, expiry, actor, and initiating tenant. Five failed proof attempts make it terminal. Confirmation also requires policy-compliant recent authentication. On success, ProAuth:

1. marks the current contact Superseded;
2. marks the candidate verified and Active;
3. applies primary profile or login-name coupling where requested;
4. advances the UserStore authentication-security epoch;
5. revokes dependent authentication state;
6. writes durable audit and notification events.

This dual-possession process prevents the common takeover sequence of changing an email address and immediately using it to reset the password.

Revoke a contact

DELETE /api/userstore/v2/{userstoreId}/administration/users/{userId}/passkey-recovery/security-contacts/{contactId}

Self-service removal requires current policy-compliant authentication. ProAuth refuses a removal that would leave the user below PasskeyRequiredVerifiedSecurityContactCount when that policy applies. Revoke a suspected compromised contact promptly; do not edit its value in place.

Account Management

UserStore users manage contacts from Account Management > Profile. The server derives the ProAuth user, active identity, UserStore user, tenant, authentication methods, assurance, and authentication time from the authenticated session. The browser cannot select another user.

The portal supports:

• viewing purpose, verification, lifecycle, primary status, and provenance;
• adding and verifying an email contact;
• replacing a verified contact with dual proof;
• removing a contact when recovery readiness remains valid.

The self-service JSON endpoints are under /account/security/api/passkeys/recovery/security-contacts. They are browser-session endpoints, not public management APIs.

Operational guidance

• Alert on repeated contact-replacement failures and changes followed by recovery activity.
• Send completion notifications to both the old and new contact.
• Treat LegacyConfirmedBackfill as migration provenance in investigations.
• Review shared recovery destinations and administrator-verified contacts regularly.
• Keep the notification outbox healthy; a contact that cannot receive its verification message cannot become an operational route.
• Do not log proof values, normalized full addresses, or protected notification payloads.