Enrollment and recovery

Enroll a Brainprint after your application authenticates the account and associates it with a GrayPass subject. That account binding establishes the reference for subsequent behavioral comparison.

Define the enrollment point, required authentication, and recovery roles before collecting evidence. See Subject lifecycle for the API sequence.

Establish the customer-side identity first

Authenticate the application user using your existing controls. Resolve the GrayPass subject from the authenticated server-side account, rather than trusting an arbitrary subject identifier in a browser request. Issue the browser token for that subject and the exact application origin.

Choose an enrollment point with meaningful customer-side assurance: for example, after a recent authenticated account-recovery review or an appropriately verified account setup. Apply your account-assurance requirements to that enrollment event.

Enrollment anchors

An anchor records the source of assurance the customer says supported enrollment.

Anchor	What the customer declares	Integration responsibility
`none`	No identity assurance was supplied.	Enrollment is unanchored.
`customer_session`	An authenticated customer application session; the default.	Authenticate the account owner before enrollment.
`idp`	An identity-provider assertion, with an evidence reference.	Verify the assertion in your identity-provider integration.
`passkey`	A customer-declared passkey enrollment anchor, with an evidence reference.	This declaration is distinct from a GrayPass-verified action challenge ceremony.
`verified_identity`	A customer-run identity-verification step, with an evidence reference.	Verify the provider result and retain its supporting evidence.

The anchor is recorded on the subject and enrollment. Use its reference to correlate the event with identity evidence verified and retained in your system. identity_anchor_validity has status unsupported because this field records customer-declared provenance.

Collect enough evidence

Start an enrollment-purpose observer and let the person interact naturally with the supported page. Use enrollment_ready from evidence acknowledgements or observer.status() to determine when your backend can request completion. The server owns the readiness requirements and rechecks them when completing enrollment. Use its reported state as the completion signal.

Readiness reflects accepted windows, active interaction time, supported modalities, and evidence quality. Keep the page focused and show the returned counts, modalities, and rejection reasons as progress information. While enrollment_ready is false, continue natural interaction or address the reported collection issue. Complete enrollment when the server reports readiness.

Your backend completes enrollment after checking the authenticated subject and the intended enrollment session. Use browser status for progress display and backend authorization for completion.

Recovery policy

Policy	Recovery requirement	Appropriate consideration
`re_enroll_with_anchor`	Replacement anchor must meet at least the recorded original anchor strength.	Default; retain your own evidence for the replacement anchor.
`re_enroll_any`	Allows a weaker declared replacement anchor.	Deliberately weaker recovery; assess the account-takeover exposure.
`manual_review`	A permitted human review must approve recovery.	Provide a staffed process and review evidence outside the potentially compromised session.

Anchor strength orders the declared categories for recovery-policy checks. Select a category that matches the evidence verified by your application.

Recovery begins after revocation. Revocation removes the old template and invalidates outstanding subject proof/passkey paths. Beginning recovery returns the subject to a fresh enrollment state under the enforced recovery policy. Complete the new enrollment, then request authorization for subsequent actions.

A customer recovery procedure

Pause the sensitive action and authenticate the person through your approved recovery channel.
Review takeover indicators and any changed account details before trusting the existing browser session.
Revoke the subject when compromise or template replacement warrants it.
Obtain the required anchor evidence or human approval and begin recovery.
Collect and complete a new enrollment; register new passkeys where needed.
Request a new action authorization and proof with fresh binding and time limits.
Record the result in your own support and security workflow.

Support device and input-method changes with an accessible recovery route and accountable review. Use enrollment and recovery results for the application-security purpose described in Supported use.

What to monitor

Track enrollment attempts, recovery frequency, anchor changes, and privileged reviewer activity. Compare GrayPass events and Console activity with your account-authentication signals. Apply your account-recovery policy and reconcile current state through the API when investigating an event.