auth

Open a disclosure reauthentication window with a TOTP code.

Changed on

The possession-factor half of the reveal ceremony (#58, permission-model ADR § The reveal guard). It is DISCLOSURE reauthentication, not account step-up: it opens a sliding window over one environment and changes nothing about the account.

The environment is RESOLVED AND AUTHORIZED under read(E) before its reauthentication policy is looked at. An environment the caller cannot reach answers exactly as a nonexistent one does — the uniform 401 this route gives every other refusal — so the policy-shaped 409 below is never an oracle for which environment ids exist or which are protected.

TOTP cannot bind its challenge to an enumerated unit, so it cannot honour a per-disclosure gate. Where the environment's effective window is 0 — which every protected environment is capped at — this route REFUSES with 409, naming the passkey ceremony as the remedy, and /auth/webauthn/reauth/* is the only path that opens a window there.

The reauth rotates the acting session; a browser session's rotated token is delivered on the __Host-hikyo cookie.

post/api/v1/auth/reauth/totp

Request

  • Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/v1/auth/reauth/totp
  • Auth: HTTP bearer

Request body

OR
OR
OR

Response

The window this reauthentication opened.

session_tokenstring

Rotated bearer returned only to Authorization-header callers; cookie-authenticated browser callers receive the rotated HttpOnly cookie and this field is omitted.

session_idstring required

A prefixed UUIDv7, e.g. org_0198….

environment_idstring required
environment_idsID[]
single_decisionboolean required

True where the effective window is zero — the window authorizes exactly one decision.

window_expiresstring date-time required

RFC 3339 UTC, microsecond precision.

Changes

    • info

      added to the request body oneOf list

    • info

      added the new developer-credential enum value to the request property ////////

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status