Skip to main content

Start TOTP enrolment for the signed-in user

POST 
/auth/totp/enroll

Required role: viewer. An account or token with the viewer or admin role can call this operation.

Example request
curl --request POST \
  --header "Authorization: Bearer $HOSERVA_TOKEN" \
  --header "Content-Type: application/json" \
  --data @body.json \
  "https://$HOSERVA_HOST:8008/api/v1/auth/totp/enroll"

Generates a new secret (RFC 6238), stored encrypted with the machine key but not yet active — the account's existing active credential, if any, is untouched until confirmTotp activates the new one. Enrolling again before confirming replaces the still-pending secret. Once TOTP is already active on this account, replacing it requires proving the caller still holds the account: exactly one of the current password or a current TOTP code, in TotpEnrollRequest. Omitting both while TOTP is active is refused (totp_reverify_required); supplying both is refused too (totp_reverify_ambiguous), since each is one guess at the active credential and honouring both would spend two for the price of one request. Neither is required for a first enrolment.

Request​

Responses​

The new secret, pending confirmation.