---
title: "Begin subject recovery"
method: POST
path: "/api/v1/subjects/{subject_id}/recovery"
tags: ["canonical"]
---

# Begin subject recovery

`POST /api/v1/subjects/{subject_id}/recovery`

## Request

- Base URL: `https://app.graypass.org` (the document declares no server; this is the origin it was published from)
- URL: `https://app.graypass.org/api/v1/subjects/{subject_id}/recovery`
- Auth: HTTP bearer

Move a revoked subject into the permitted re-enrollment path after your application establishes the required anchor.

## Path parameters

- `subject_id` string, required

## Request body

- RecoveryBegin: Start re-enrollment for a revoked subject under its configured recovery policy.
  - `anchor` 'none' | 'customer_session' | 'idp' | 'passkey' | 'verified_identity', required: Account anchor established by the customer identity process and recorded by GrayPass.
  - `anchor_evidence_ref` string, nullable: Reference to the customer’s anchor evidence; required for idp, passkey and verified_identity anchors. The customer identity process establishes the underlying claim. GrayPass retains the digest without independently verifying that identity claim.

## Response `200`

Subject reset to not_enrolled under the accepted replacement anchor.

- Subject: Pseudonymous subject lifecycle record within one environment.
  - `adaptation_frozen` boolean, required: Whether online template adaptation is frozen; true prevents silent template adaptation.
  - `anchor` string, required: Account anchor established by the customer identity process and recorded by GrayPass.
  - `created_at` string, required: Creation time as an ISO 8601 timestamp.
  - `enrollment_state` 'not_enrolled' | 'enrolling' | 'enrolled' | 'revoked' | 'deleted', required: Current enrollment lifecycle state. Revoked subjects need the configured recovery path; deleted subjects are no longer operationally retrievable.
  - `environment` string, required: Environment identifier that scopes this record; sandbox and live resources are separate.
  - `id` string, required: Identifier of this record. Treat it as opaque and retain it for subsequent operations.
  - `limitations` string[]: Applicable limitations that must accompany interpretation of the result.
  - `recovery_policy` string, required: Recovery rule governing whether re-enrollment requires an anchor or a separate manual-review process.
  - `revoked_at` string, nullable: Revocation time as an ISO 8601 timestamp, or null when not revoked.

## Other responses

- `422`: The canonical handler returns a Problem for invalid input; correct the request before retrying.

---

[API](https://skmtc.dev/graypass/apis/graypass-api.md) - [All operations](https://skmtc.dev/graypass/apis/graypass-api/llms.txt) - [OpenAPI document](https://skmtc.dev/graypass/apis/graypass-api/revisions/5f9ab64fdfdb?raw)