POST /api/admin/accounts/{sub}/purge

POST /api/admin/accounts/:sub/purge {confirm: "_{"}: erases a scheduled account now instead of at the end of
its grace period (accounts.purge_now: owners only, step-up, reason). Starts the purge job for this one account and
answers 202; the job records system.purge when it's done.}

Caller and authorization

Staff cookie session; permission accounts.purge_now; fresh password + TOTP step-up (10 minutes); X-Admin-Reason required (3–300 characters). Write requests need same-origin JSON and X-Admin-CSRF from this session.

This is the private staff console on https://admin.handwrites.io. A personal API key, organisation token, student login or isolated app-testing credential does not authenticate this route.

Request contract

The following is the accepted request shape, expressed as JSON Schema. It is not a runnable example. Runtime refinements and operation rules also apply.

{
  "type": "object",
  "properties": {
    "confirm": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Must equal the target account sub."
    }
  },
  "required": [
    "confirm"
  ]
}

Response and failures

Success: 202. Accepted for asynchronous work; this is not proof that deletion or recomputation has completed.

The wrapper returns {error:{code,message}} for CloudError failures, attaches Request-Id, and disables caching. Handle 401 by signing in; show role refusal for 403 forbidden, reauthenticate only for step_up_required, and collect a reason for 400 reason_required. A CSRF failure needs a current page/session token, not blind retries. Operation-specific 404/409/413/422/502/503 errors retain their status. Honor Retry-After on 429.

Usage notes

• Deletion/purge is not a smoke-test operation. HTTP 202 reports acceptance; confirm final status and the purge audit event separately.

Implementation contract

Source snapshot: admin/src/app/api/admin/accounts/[sub]/purge/route.ts. This reference describes the current working tree, not proof of deployment. The response service types and validators remain authoritative. The exact exported handler below makes conditional behavior reviewable. For helpers such as customer-routes or cloudRoute, see the shared API specification notes and the named service module.

/**
 * POST /api/admin/accounts/:sub/purge {confirm: "<sub>"}: erases a scheduled account now instead of at the end of
 * its grace period (accounts.purge_now: owners only, step-up, reason). Starts the purge job for this one account and
 * answers 202; the job records system.purge when it's done.
 */
export const POST = adminRoute("accounts.purge_now", async (request, ctx, { params }: Context) => {
  const { sub } = await params;
  const { confirm } = await readBody(request, body);
  return adminJson(await purgeNow(ctx, sub, ctx.reason!, confirm), { status: 202 });
}, { stepUp: true, reason: true, rateLimit: "holds" });

Do not use production customer data to test this operation. Use an authorized staff test account and a disposable target in an appropriate environment; email, deletion, role and credential mutations have real effects.