Subject lifecycle

A subject is a tenant- and environment-scoped pseudonymous record associated with a person in your application. Your application owns the mapping between its authenticated account and the GrayPass subject. Keep that mapping on the backend and verify account ownership on every lifecycle request.

Create and identify a subject

const subject = await graypass.createSubject({
  externalRef: authenticatedUser.id,
  anchor: 'customer_session',
  recoveryPolicy: 're_enroll_with_anchor',
});

Use a stable application identifier rather than an email address or display name when possible. GrayPass derives a scoped representation of the external reference. Treat linked metadata as pseudonymous personal data. Keep optional metadata limited to the fields needed by the integration, with credentials and payment information in their dedicated systems.

An anchor records how your application associated the subject with an account: none, customer_session, idp, passkey, or verified_identity. Choose the value supported by your actual account flow. Your application verifies that association and retains the evidence referenced by the declared anchor.

Enroll using server readiness

Mint a browser client token for the subject and registered origin. Start GrayPass.observe({ token, subject: subject.id, purpose: 'enroll' }). Let the person interact normally and inspect observer.status() or evidence acknowledgements. Call completeEnrollment(subject.id, observer.session) from your backend only when the server reports readiness.

Use the returned enrollment_ready flag, accepted window count, active seconds, and modalities to drive progress. A pending state means collection should continue or its rejection reasons need attention. Accepted coverage advances with valid interaction windows. Use the server readiness flag as the completion signal.

After successful backend completion, end the enrollment observer and start an observation session for later activity. If completion is refused, keep the enrollment state pending and inspect the returned reason.

Adaptation and revocation

The subject record exposes adaptation_frozen. The adaptation-freeze operation stops further model adaptation for that subject; use it as part of a reviewed investigation or recovery procedure. Existing evidence retains its original assessment.

Revocation invalidates continued reliance on the subject's current enrollment and associated access state. Your application should stop its observers, clear local GrayPass state, refuse pending operations that depend on the revoked subject, and require its own recovery process before re-enrollment. A signed proof can remain cryptographically well formed after lifecycle changes, which is why execution also checks online state.

await graypass.revokeSubject(subject.id);

Recovery and passkeys

Recovery begins through the subject recovery API, supplying an anchor and, when required, evidence reference consistent with the subject's recovery policy. The supported policies are re_enroll_with_anchor, re_enroll_any, and manual_review. Treat the policy as part of your account recovery design, not a substitute for it.

The ordinary recovery API does not supply an attributed manual approval. A subject configured for manual_review requires the authorized Console recovery workflow; a direct API request without that review is refused. Recovery starts from a revoked subject, and an anchor-based policy refuses a weaker replacement anchor.

Do not let possession of a browser token or subject ID alone authorize account recovery. Reauthenticate through your own trusted process. A passkey registration grant should likewise be issued only after an authenticated server decision. Revoke a lost or unwanted subject passkey through the supported passkey revocation operation.

Export and deletion

const exported = await graypass.exportSubject(subject.id);
await graypass.deleteSubject(subject.id);

The export contains subject information and bounded enrollment, authorization, session, passkey, and consent records. It indicates whether a Brainprint is stored but does not export the template or passkey credential material. Authorization, session, passkey, and consent collections each contain at most 500 records; enrollment history contains at most 100. The response has no pagination for retrieving the remainder.

For history beyond those collection bounds, contact founders@graypass.org to arrange a complete export for the individual request or review. Store the downloaded export under your own access and retention controls.

Deletion removes the subject's operational records and model data. Financial records, audit records, and backups follow their respective retention procedures. See Privacy and Data flow.

After a lifecycle exercise, test that old tokens, sessions, and proofs cannot continue the protected flow. Also clean up your own subject mapping, pending business requests, local browser state, and any downloaded exports according to your policy.