Passkey policy option reference

This reference describes every UserStore IDP option used by the current passkey policy. Read UserStore passkeys first if you are selecting an operating model or planning a rollout.

Option names and enum values are case-sensitive. Durations are integer seconds unless the option name explicitly says milliseconds. List values accept comma, semicolon, or newline separators and are normalized by ProAuth.

TIP

Use GET /api/management/v2/idpinstances/{idpInstanceId}/passkey-policy to inspect the effective typed policy. Use the policy preview endpoint before writing options so that defaults, legacy precedence, cross-option constraints, impact, and approval requirements are evaluated together.

Enablement and login experience

Option	Values and default	Purpose and guidance
PasskeyEnabled	Boolean; default false	Enables UserStore login-passkey registration and authentication. Enabling this option alone does not remove passwords or require enrollment.
PasskeyLoginExperience	Button, ConditionalAndButton (default), PasskeyFirst	Controls presentation on the login page. Button requires an explicit action. ConditionalAndButton also permits browser autofill/conditional UI. PasskeyFirst starts with passkey authentication while retaining policy-allowed alternatives.
PasskeyEnrollmentPolicy	Optional (default), Encouraged, Required	Determines whether enrollment is available, promoted, or mandatory. Required is normally combined with a non-zero grace period for existing users.
PasskeyEnrollmentGracePeriodSeconds	0–31536000; default 0	Time allowed to satisfy required enrollment before policy enforcement. 0 means no grace period. A password-prohibited required-enrollment policy also needs an operational initial-enrollment route.
PasskeyAuthenticatorTimeoutSeconds	30–600; default 180	Timeout sent to the browser for WebAuthn ceremonies. It is a client hint, not a replacement for server-side challenge expiry and single-use consumption.

PasskeyFirst changes presentation, not assurance. A failed or cancelled passkey attempt exposes only alternatives permitted by the effective password, enrollment, and recovery policy.

Credential inventory and maturation

Option	Values and default	Purpose and guidance
PasskeyMaxCredentialsPerUser	1–50; default 20	Maximum active login passkeys for one user, checked when registration starts and completes. Keep enough capacity for replacement and device turnover.
PasskeyRequiredCredentialCount	1–10, and no greater than PasskeyMaxCredentialsPerUser; default 1	Minimum number of usable credentials required by readiness. For managed passwordless deployments, 2 protects against loss of one device.
PasskeyCredentialDiversityPolicy	DistinctCredential (default), DistinctAaguid, DistinctMetadataVendor, DistinctTrustRoot	Defines how the required credential count must be diversified. Stronger evidence-based modes require the corresponding attestation or metadata evidence.
PasskeyCredentialMaturationSeconds	0–2592000; default 86400 (24 hours)	Delay before a newly bound credential can satisfy destructive-action readiness. It limits the value of binding a credential and immediately using it to remove recovery paths.
PasskeyExistingCredentialEnforcement	Grandfather (default), GraceThenRestrict, BlockImmediately	Controls credentials that do not satisfy a newly tightened policy. See the behavior table below.

Credential diversity

Value	Requirement
DistinctCredential	Each credential ID is different. This prevents duplicate counting but does not prove separate devices or vendors.
DistinctAaguid	Credentials must have distinct authenticator AAGUIDs. Credentials without usable AAGUID evidence cannot satisfy the distinction.
DistinctMetadataVendor	Credentials must have distinct FIDO metadata statement evidence. Use when vendor independence is part of the control objective.
DistinctTrustRoot	Credentials must chain to distinct attestation trust roots. This is the strictest built-in evidence-diversity mode.

Existing-credential enforcement

Value	Behavior
Grandfather	An UnknownLegacy credential can remain usable even when historical RP ID, algorithm, or trust evidence cannot be reconstructed. Mandatory compromise evidence still blocks it.
GraceThenRestrict	A non-compliant credential remains usable only until its enforcement deadline. Use this for staged tightening with measurable remediation.
BlockImmediately	A credential must satisfy the current policy now. Use only after an impact assessment confirms users retain a usable path.

Password lifecycle

Option	Values and default	Purpose and guidance
PasskeyPasswordPolicy	Coexist (default), UserRemovable, RemoveWhenReady, Prohibited	Controls whether passwords remain, can be removed by the user, are removed by policy after readiness, or are prohibited.
PasskeyPasswordRemovalGracePeriodSeconds	0–2592000; default 0	Delay between scheduling and committing password removal. Readiness is evaluated again at commit. Use a non-zero period for managed migrations.
PasskeyPasswordRecreationPolicy	AllowedAfterStrongAuthentication (default), RecoveryOnly, Prohibited	Determines whether an absent password can be recreated. Passkey deletion itself never recreates a password.
PasskeyAdministrativeLastCredentialRemovalPolicy	Block (default), EnterRestrictedRecovery	Controls authorized administrative handling of the last usable credential. Self-service deletion of the final credential is always blocked. Confirmed compromise revocation always proceeds.

Password policy values

Value	Behavior
Coexist	Password and passkey remain ordinary sign-in methods. Password security remains part of the account's effective security.
UserRemovable	A user can explicitly request password removal after the server reports full readiness.
RemoveWhenReady	ProAuth schedules password removal after readiness and commits it after the configured grace period if final readiness still succeeds.
Prohibited	Password login and password recreation are unavailable. Existing users transition only through the configured migration and readiness process; newly provisioned users start in initial enrollment.

RemoveWhenReady and Prohibited require at least one recovery route, at least one verified security contact, and PasskeySecurityNotificationMode=Required.

Password recreation values

Value	Behavior
AllowedAfterStrongAuthentication	A policy-accepted strong authentication flow may establish a new password. Use only where returning to password login is an intentional product behavior.
RecoveryOnly	Password recreation is possible only as an outcome of the governed recovery process.
Prohibited	No passkey or recovery operation can reactivate password login.

User verification and sensitive-operation authentication

Option	Values and default	Purpose and guidance
PasskeyUserVerificationPolicy	Required (default), PreferredWithMfa	Controls the WebAuthn user-verification request. Required requires authenticator verification such as a PIN or biometric. PreferredWithMfa requests verification when available and relies on the complete authentication chain for required assurance.
PasskeyBindingAuthenticationPolicy	RecentAny, CurrentMaximumAal (default), PhishingResistant	Authentication evidence required before binding a new passkey or authorizing password removal.
PasskeyBindingAuthenticationMaxAgeSeconds	0–3600; default 300	Maximum age of the authentication used for credential binding. 0 effectively requires authentication at the current instant and is rarely operationally useful.
PasskeyDeletionAuthenticationPolicy	RecentAny, CurrentMaximumAal (default), PhishingResistant	Authentication evidence required for self-service credential deletion. It does not prevent emergency administrative compromise revocation.
PasskeyTimestampDriftToleranceMilliseconds	0–60000; default 0	Explicit tolerance for timestamp comparisons in supported ceremony checks. Increase only for a measured clock-skew requirement; synchronize server clocks instead.

Authentication evidence levels

Value	Evidence accepted within the maximum age
RecentAny	Any recorded authentication method. This is the least restrictive value.
CurrentMaximumAal	A user-verified passkey (pop and user AMR), or a fresh password where the specific binding workflow explicitly allows it.
PhishingResistant	A user-verified passkey plus a phr or phrh ACR earned by the complete authentication chain.

Authenticator class and attestation

Option	Values and default	Purpose and guidance
PasskeyAuthenticatorClassPolicy	Any (default), BackupEligibleRequired, BackedUpRequired, DeviceBoundOnly	Selects whether synced credentials, backed-up credentials, or only device-bound credentials can be usable.
PasskeyAttestationConveyance	none (default), indirect, direct, enterprise	WebAuthn attestation conveyance requested during registration. Do not request identifying attestation without a documented need and privacy assessment.
PasskeyAttestationTrustPolicy	None (default), MetadataIfAvailable, MetadataRequired, AaguidAllowList	Determines which attestation and FIDO metadata evidence a credential must have. A value other than None cannot be combined with conveyance none.
PasskeyAllowedAaguids	AAGUID list; default empty	Allow-list used by AaguidAllowList. The list must contain at least one value in that mode. Also useful as an explicit trust overlay.
PasskeyBlockedAaguids	AAGUID list; default empty	Authenticator models that baseline risk evaluation must block. Allowed and blocked sets cannot overlap.
PasskeyUndesiredAuthenticatorStatusPolicy	Warn, BlockNew (default), BlockAll	Response to an undesirable authenticator status from authoritative metadata. Mandatory compromise statuses cannot be ignored.

Authenticator class values

Value	Eligible credential
Any	Synced, backed-up, and device-bound credentials are accepted if other controls pass.
BackupEligibleRequired	The authenticator reports that the credential can be backed up or synced.
BackedUpRequired	The credential is backup-eligible and currently reports a backed-up state.
DeviceBoundOnly	The credential is neither backup-eligible nor backed up. Use for managed hardware policies.

Attestation trust values

Value	Requirement
None	Attestation and metadata are not required for usability. Other baseline checks still apply.
MetadataIfAvailable	Metadata is evaluated when present; compromised metadata blocks the credential, but absence alone does not.
MetadataRequired	Attestation must be verified and the credential must have trusted FIDO metadata evidence.
AaguidAllowList	Attestation must be verified and the AAGUID must be in PasskeyAllowedAaguids.

Required trust needs certificate-backed attestation validated against the authenticator's FIDO metadata trust roots. An AAGUID lookup alone is not proof of authenticator identity: none and self-attestation cannot satisfy MetadataRequired or AaguidAllowList. Under MetadataIfAvailable, those credentials may still register, but are recorded as untrusted and cannot later satisfy a required-trust policy without new verified enrollment.

Algorithms

Option	Values and default	Purpose and guidance
PasskeyAllowedAlgorithms	COSE algorithm identifiers; default -7,-35,-36,-37,-38,-39,-257,-258,-259	Customer-narrowable allow-list intersected with the server-supported safe set. At least one supported value is required. Narrow only after verifying every supported authenticator.

COSE ID	Algorithm
-7	ES256
-35	ES384
-36	ES512
-37	PS256
-38	PS384
-39	PS512
-257	RS256
-258	RS384
-259	RS512

EdDSA/Ed25519 is not in the current server-supported safe set and is not offered during registration.

Runtime risk and counter handling

Option	Values and default	Purpose and guidance
PasskeySignatureCounterAnomalyPolicy	RiskEvaluate (default), Hold, Block	Response to a genuine regression of a previously non-zero authenticator signature counter. Authenticators that consistently report zero remain valid.
PasskeyRiskProviderMode	BaselineOnly (default), OptionalProvider, RequiredProvider	Determines whether an external IPasskeyExternalRiskProvider contributes to credential binding, counter anomalies, and backup-state changes. Baseline rules cannot be disabled.
PasskeySuspiciousBindingHoldSeconds	0–604800; default 0	Hold duration for a suspicious binding decision. A held credential cannot satisfy authentication or readiness until the hold is cleared or expires.

Risk provider behavior

Mode	Provider absent or fails
BaselineOnly	No external provider is called; non-disableable ProAuth baseline rules decide.
OptionalProvider	The operation is held rather than treated as approved without evidence.
RequiredProvider	Credential binding or the evaluated operation is blocked.

Signature-counter behavior

Value	Result for a genuine non-zero regression
RiskEvaluate	Send the event through the configured risk-provider path. If no optional provider is available, the result is a hold.
Hold	Place the credential in an investigation hold.
Block	Block the credential operation immediately.

Relying party and origins

Option	Values and default	Purpose and guidance
PasskeyRpId	DNS relying-party ID; default derived from BaseServiceSettings:HostUrl	Cryptographic scope of the credential. It must equal the ceremony host or be its registrable-domain suffix. Do not change it directly while active credentials exist.
PasskeyRpName	String; default ProAuth	Human-readable relying-party name shown by authenticators when supported. It is not a security boundary.
PasskeyAllowedOrigins	Origin list; default empty	Additional exact ceremony origins. Values must be HTTPS origins without credentials, paths, queries, or fragments. HTTP is accepted only for loopback development. During RP migration this list can contain the verified overlap origins.

Origins are canonical authorities such as https://login.example.com; https://login.example.com/account is invalid. An allow-list entry does not by itself authorize an unrelated RP ID: the ceremony selector also verifies the exact RP/origin binding.

Use the API-driven RP ID migration instead of replacing PasskeyRpId on an active deployment.

Security contacts, notifications, and retention

Option	Values and default	Purpose and guidance
PasskeySecurityNotificationMode	Disabled, BestEffort (default), Required	Controls durable notification requirements for credential and password lifecycle events. Password-removing policies require Required.
PasskeyRequiredVerifiedSecurityContactCount	0–5; default 0	Number of verified, non-revoked security contacts required for readiness. Password-removing policies require at least 1.
PasskeyRevokedCredentialRetentionSeconds	0–31536000; default 7776000 (90 days)	Retention period for non-reactivatable credential tombstones before purge. Align with investigation, privacy, and audit-retention requirements.

Security contacts are UserStore-scoped security records, not arbitrary user-profile strings. A confirmed legacy email address can be backfilled as a provenance-marked verified contact; an unconfirmed address is not migrated.

Recovery and initial enrollment

Option	Values and default	Purpose and guidance
PasskeyRecoveryRoutes	Versioned JSON route set; default {"Version":1,"Routes":[]}	Alternative proof combinations accepted for account recovery. At least one route is required when passwords may be removed or are prohibited.
PasskeyInitialEnrollmentRoutes	Versioned JSON route set; default {"Version":1,"Routes":[]}	Alternative proof combinations accepted before a user with no primary authenticator binds the first passkey. Required for password-prohibited required enrollment.
PasskeyRecoveryCodeCount	1–20; default 10	Number of primary recovery codes generated when a user rotates the set. Rotation invalidates the previous set.
PasskeyRecoveryEmailTokenLifetimeSeconds	60–86400; default 900	Lifetime of a verified-contact recovery token.
PasskeyTemporaryAccessPassLifetimeSeconds	60–86400; default 3600	Lifetime of an operator-issued TAP. Approval and redemption must complete before expiry.
PasskeyRecoverySessionLifetimeSeconds	300–3600; default 900	Lifetime of the restricted session issued after recovery proof succeeds. It can bind a new primary authenticator but cannot complete ordinary OIDC sign-in.

Route-set format

Routes are ordinary option values containing versioned JSON. Version must currently be 1. Route names must be non-empty and unique. A route must contain at least one requirement. Requirements in the same route are combined with AND; separate routes are alternatives combined with OR.

{
  "Version": 1,
  "Routes": [
    {
      "Name": "TwoIndependentProofs",
      "Requirements": [
        {
          "TrustClass": "SavedCode",
          "Count": 1,
          "RequiredApprovals": 0,
          "ProviderCapability": null
        },
        {
          "TrustClass": "VerifiedAddress",
          "Count": 1,
          "RequiredApprovals": 0,
          "ProviderCapability": null
        }
      ]
    },
    {
      "Name": "QualifiedIdentityReproofing",
      "Requirements": [
        {
          "TrustClass": "IdentityProofing",
          "Count": 1,
          "RequiredApprovals": 0,
          "ProviderCapability": "qualified"
        }
      ]
    }
  ]
}

Recovery trust classes

Trust class	Meaning	Additional fields
VerifiedAddress	A proof delivered to a verified, non-revoked security contact.	Count is 1–10.
SavedCode	A saved, single-use primary recovery code.	Count is 1–10.
BoundAuthenticator	Proof from an existing usable primary authenticator.	Count is 1–10.
TemporaryAccessPass	A reason-bound, operator-issued TAP.	RequiredApprovals must be 1–10; the requester cannot approve their own operation.
IdentityProofing	Successful asynchronous proofing by a registered provider.	ProviderCapability identifies the required non-customer-defined capability, such as qualified.

Do not repeat the same trust class within one route; increase Count instead. A configured identity-proofing capability is operational only when exactly one registered provider supplies it.

Maker-checker approvals

Option	Values and default	Purpose and guidance
PasskeyHighImpactApprovalPolicy	JSON map; default {}	Number of independent approvals required for each high-impact operation. Values are 0–10. The exact command and concurrency state are captured when approval is requested and revalidated before execution.

Supported operation keys are:

• TemporaryAccessPassIssue
• PolicyWeakening
• DestructivePasswordActivation
• RpMigrationRetirement
• TrustOverlayChange
• DestructiveRecommendationApply

Example:

{
  "TemporaryAccessPassIssue": 2,
  "PolicyWeakening": 2,
  "DestructivePasswordActivation": 2,
  "RpMigrationRetirement": 2,
  "TrustOverlayChange": 2,
  "DestructiveRecommendationApply": 2
}

The requester cannot approve their own request. Approval of one command cannot authorize a changed command, changed option concurrency state, or different operation.

Cross-option validation

The policy resolver rejects invalid combinations before apply. Important rules include:

• PasskeyRequiredCredentialCount cannot exceed PasskeyMaxCredentialsPerUser or 10.
• RemoveWhenReady and Prohibited require an operational recovery route, at least one verified security contact, and required durable notifications.
• Required enrollment combined with Prohibited passwords requires an initial-enrollment route.
• An attestation trust policy other than None cannot use attestation conveyance none.
• AaguidAllowList requires at least one allowed AAGUID.
• Allowed and blocked AAGUID sets cannot overlap.
• The algorithm list must contain at least one server-supported safe algorithm.
• TAP route requirements must request at least one approval.
• Route names must be unique, requirements cannot be empty, and duplicate trust classes in one route are rejected.

Validation is necessary but does not prove operational readiness. The server can accept a syntactically valid provider-backed route even though the provider later becomes unavailable; runtime readiness reports whether the route is currently operational.

Legacy compatibility options

Do not add these options to a new policy. They remain readable so an upgrade preserves existing behavior until replacement options are deliberately configured.

Legacy option	Compatibility behavior	Replacement
PasskeyConditionalUiEnabled	Determines ConditionalAndButton versus Button only while PasskeyLoginExperience is absent.	PasskeyLoginExperience
PasskeyEnforcePasswordless	Preserves legacy forced-passkey login only while PasskeyPasswordPolicy is absent. It is not interpreted as permission to remove a password hash.	PasskeyPasswordPolicy and enrollment policy
PasskeyAllowLoginWithoutUserVerification	Preserves legacy non-UV assertion behavior only while PasskeyUserVerificationPolicy is absent.	PasskeyUserVerificationPolicy
Per-user PasskeyRequirePasskeyLogin profile value	Remains compatibility-read-only and appears in migration impact. It is never automatically converted into password removal.	IDP policy plus user authentication state

New-option presence wins over the corresponding legacy input. Removing a replacement option can therefore expose an older stored compatibility value; always preview removals.

Recommendation ownership

The four recommendations currently own and overwrite the complete replacement option set documented on this page. Applying a recommendation does not create PasskeyPolicyProfile and does not prevent later edits.

Use recommendation list/get APIs as the authoritative source for exact versioned values. The effective-policy endpoint is the authoritative source for the current resolved result.