school

POST /api/admin/support/tickets/:id/school (schools.approve, step-up; the staff-console specification). approve provisions the school
on the site, solves the ticket and mails the school-approved reply → {orgId, schoolId, emailed, adminLinked,
existing}; mail that didn't pass DMARC needs X-Admin-Reason. reject replies with text and tags the ticket.

Caller and authorization

Staff cookie session; permission schools.approve; fresh password + TOTP step-up (10 minutes). 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

Location	Name	Required	Meaning
path	`id`	Yes	Use the ID from an authorized staff response; source validators reject malformed IDs.
header	`X-Admin-CSRF`	Yes	Session-bound token from the staff page; not a developer credential.

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

{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "decision": {
          "const": "approve"
        },
        "name": {
          "type": "string",
          "minLength": 2,
          "maxLength": 120
        },
        "adminEmail": {
          "type": "string",
          "format": "email",
          "maxLength": 254
        },
        "adminName": {
          "type": "string",
          "description": "Optional school administrator display name; schoolApplication validator applies."
        },
        "note": {
          "type": "string",
          "maxLength": 5000
        }
      },
      "required": [
        "decision",
        "name",
        "adminEmail"
      ]
    },
    {
      "type": "object",
      "properties": {
        "decision": {
          "const": "reject"
        },
        "text": {
          "type": "string",
          "minLength": 1,
          "maxLength": 20000
        }
      },
      "required": [
        "decision",
        "text"
      ]
    }
  ]
}

Response and failures

Success: 200. POST /api/admin/support/tickets/:id/school (schools.approve, step-up; the staff-console specification). approve provisions the school
on the site, solves the ticket and mails the school-approved reply → {orgId, schoolId, emailed, adminLinked,
existing}; mail that didn't pass DMARC needs X-Admin-Reason. reject replies with text and tags the ticket.

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

Keep customer messages and attachment URLs out of general logs. Replies can send real email; notes remain internal. Render inbound HTML only in the console’s sandboxed, network-restricted frame.

Implementation contract

Source snapshot: admin/src/app/api/admin/support/tickets/[id]/school/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/support/tickets/:id/school (schools.approve, step-up; ADMIN.md §16). `approve` provisions the school
 * on the site, solves the ticket and mails the school-approved reply → {orgId, schoolId, emailed, adminLinked,
 * existing}; mail that didn't pass DMARC needs X-Admin-Reason. `reject` replies with `text` and tags the ticket.
 */
export const POST = adminRoute("schools.approve", async (request, ctx, { params }: Context) => {
  const id = ticketIdParam((await params).id);
  const body = await readBody(request, BODY);
  if (body.decision === "reject") return adminJson(await rejectSchool(ctx, id, { text: body.text }));
  return adminJson(await approveAsSchool(ctx, id, { name: body.name, adminEmail: body.adminEmail, adminName: body.adminName, note: body.note }));
}, { stepUp: true, rateLimit: "school-approve" });

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.

README — POST /api/admin/support/tickets/{id}/school

POST /api/admin/support/tickets/{id}/school#

Caller and authorization#

Request contract#

Response and failures#