Admin API specification notes

Scope and identity

Base URL: https://admin.handwrites.io. The staff pool and application are separate from customer, team and student identities. Staff API keys are not an authentication mechanism. The production session cookie is __Host-hwa_session, with HttpOnly, Secure, SameSite=Strict and Path=/; development uses hwa_session. The cookie value is opaque, while server storage identifies it by its hash. Absolute session lifetime is twelve hours; idle lifetime is thirty minutes. The session is bound to its recorded browser user agent and an active admitted staff account.

POST sign-in and challenge accept same-origin JSON before a staff session exists. Password-only tokens are refused: the completed flow must prove MFA_SETUP or SOFTWARE_TOKEN_MFA before issuing a session. The temporary Cognito challenge session and TOTP enrollment secret are sensitive transient values, not customer API tokens. Login attempts are limited to ten per IP or email in fifteen minutes. Staff self-service password recovery is not supplied; an authorized owner uses the staff reset workflow.

Request gates

The common wrapper checks session, active account, permission, fresh step-up where required, audit reason where required, then write CSRF. It returns a no-store response with Request-Id and logs a restricted event. Specific handlers add target checks, refusal rules and their own audit records.

For writes, send JSON with Content-Type: application/json from the console's own origin and include X-Admin-CSRF from the current staff page/session. Safe HTTP methods skip write CSRF, but still need authorization where applicable. The staff frontend exposes the current CSRF value in its rendered page; the value cannot be derived from a public API key.

A required X-Admin-Reason is URI-encoded text, decoded and trimmed server-side, with 3–300 characters. State why this particular access/action is necessary; do not include passwords, tokens or document text. Password plus TOTP step-up is fresh for ten minutes. See the permission matrix for defaults and individual READMEs for overrides.

Cloud metadata inspection uses an account/organisation reason marker for fifteen minutes and writes cloud.view before reading data. content=1 additionally requires accounts.content.read and a fresh step-up, with its own audit. It reveals permitted titles, names, emails and settings; it never returns document text, original files or audio bytes. Account billing has a separate target marker; aggregate platform billing does not require a reason.

Responses, pagination and retries

Errors normally have { "error": { "code": "...", "message": "..." } }. Keep Request-Id for diagnosis without retaining the request's secrets or customer content.

Condition	Client behavior
401 unauthenticated or invalid credentials	Start the appropriate staff sign-in flow; do not substitute a customer token.
403 forbidden	Explain the role restriction. Do not loop on reauthentication.
403 step_up_required	Run the staff step-up UI, then deliberately retry the intended operation.
400 reason_required	Ask for a reason for the specific target/action.
403 csrf	Reload/refresh the session's page token and verify same-origin JSON.
404 not_found	Recheck the selected target and access; do not enumerate identities.
409 conflict	Refresh current state and preserve the user's intent; version/owner invariants may have changed.
429 rate_limited	Honor Retry-After and stop repetitive submissions.
502/503 service unavailable	Surface the failed dependency; reconcile before replaying an uncertain mutation.

Use returned opaque cursors as provided. List limits differ by resource: many DynamoDB lists allow 1–100, filtered Cognito account search returns at most 60, and the sessions list is capped at 50. Do not assume every response uses the same pagination envelope. GET health reports liveness only.

There is no general idempotency-key promise for the staff API. Do not automatically replay email, invitations, account actions or configuration writes after an uncertain response. Credential revoke/API block operations are designed to report unchanged state on repetition, while school status/close operations explicitly use continuation cursors. A 202 response for purge, scheduled deletion or rollup only confirms acceptance.

Request and response schemas

The machine-readable reference covers every exported staff/health operation in the captured checkout, including re-exported customer handlers. Request schemas describe accepted fields; runtime trimming, validation, target checks and service constraints remain authoritative. Some service-projected success responses intentionally remain open object schemas: the README contains the exact handler and points to its source service. These are not generated public SDK guarantees.

Individual handler source snapshots support review, but imported historical planning comments are not deployment evidence. The source-status page identifies current-working-tree additions. Private mail and SNS callbacks are documented in the Internal edition, not as staff-cookie endpoints.

Admin API specification notes

Scope and identity#

Request gates#

Responses, pagination and retries#

Request and response schemas#

Scope and identity

Request gates

Responses, pagination and retries

Request and response schemas