Grant a sudo-mode window by verifying a TOTP or recovery code

POST/api/auth/sudo/totp

sudoTotp

Authenticated (session-cookie) endpoint. Verifies a 6-digit TOTP code (or a single-use recovery code) and stamps `sessions.sudo_until = now() + 5min` — the counterpart to `/api/auth/sudo/password` for OAuth-claimed / passwordless accounts whose only step-up credential is their authenticator. A wrong/absent code returns `401 { error: "invalid_credentials" }` (no oracle on which factors an account holds). Bearer-PAT callers can't sudo (it's a session-row column) → 400. Per-session rate limit: 5 attempts per 15 min → `429 Too Many Requests` with `Retry-After`.

Requires authentication using a session cookie — see tokens and scopes.

curl

curl -X POST 'https://neosource.dev/api/auth/sudo/totp' \
  -b 'ns_session=$NEOSOURCE_SESSION' \
  -H 'Content-Type: application/json' \
  -d '{"code":"123456"}'

fetch

fetch("https://neosource.dev/api/auth/sudo/totp", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  credentials: "include",
  body: JSON.stringify({"code":"123456"}),
});

Request bodyrequired

application/json

SudoTotpRequest

object

Request body for `POST /api/auth/sudo/totp`. Grants a sudo window by verifying a TOTP code (or a single-use recovery code) instead of a password — the sudo path for OAuth-claimed / passwordless accounts, whose only step-up credential is their authenticator. Returns the same `SudoPasswordResponse` (`sudo_until`) as the password path.

coderequired: string
A 6-digit TOTP code, or a `xxxxx-xxxxx` recovery code.
example"123456"

additional propertiesnot allowed

Responses

200Sudo granted; window expires at `sudo_until`

application/json

SudoPasswordResponse

object

sudo_untilrequired: integerint64
Millis-since-epoch when the sudo window expires. The SPA can surface a countdown or just rely on retrying the original request — a fresh 403 means sudo has lapsed.

Standard errors

Bodies documented once for the whole API — see standard errors.

400Bearer-token caller has no session to grant sudo on
401Authentication required
429Rate limited — retry after the `Retry-After` header
500Internal server error
503Service temporarily unavailable / at capacity — retry after the `Retry-After` header
504Gateway timeout — the request exceeded the server's handling budget