Skip to content

The v1 docs follow nauthera-server's main branch and its 0.x releases on the way to 1.0, so fields and APIs can still change.

v1

unauthorized

Docs version v1 (main)Nauthera is pre-1.0, in a design-partner program

The caller is not signed in, or the sign-in or admin token no longer counts (401).

Meaning

  • Hosted sign-in UI: the request carries no sign-in session, or the pending sign-in between password and second factor has lapsed (auth.pending.ttl), as on the consent, device verification and MFA endpoints ("sign in to continue").
  • The MFA endpoints also answer it when the factor or recovery codes they act on do not exist, so factor state is never revealed.
  • Admin API: the token was absent or did not verify, or a DPoP-bound token failed its sender constraint. WWW-Authenticate says which; a challenge naming use_dpop_nonce means retry with the nonce sent in DPoP-Nonce.

Impact

A user whose sign-in step took too long sees "Your sign-in session expired" and signs in again; this is expected now and then. A dashboard user is sent to sign in again. An admin-API client getting it on every call has a broken token setup.

Diagnosis

  1. Read the WWW-Authenticate header on an admin-API answer.
  2. Look the request id up on the Troubleshooting page. Hosted UI refusals name a cause such as pending_expired, pending_absent, session_absent or session_expired. An admin token refusal is recorded as admin.access.denied with reason unauthenticated and a cause such as credential_missing, token_expired or a dpop_* cause.
  3. For lapsed pending sign-ins across many users, check auth.pending.ttl and the cache (cache.*), which holds pending sign-ins.

Mitigation

  • As a user: choose "Sign in again" and complete each step without long pauses.
  • As an admin-API caller: get a new token; for a DPoP-bound token send Authorization: DPoP <token> and a fresh proof on every call, and on a use_dpop_nonce challenge repeat the call once with the nonce from DPoP-Nonce.
  • As an operator: if pending sign-ins lapse for everyone, check that every replica reaches the same cache.

Escalation

Escalate when a freshly issued admin token is refused, or pending sign-ins lapse well inside auth.pending.ttl. Open an issue with the request id, the audit cause, the WWW-Authenticate value and the server version. Never attach tokens or proofs.

Problem code runbooks · Generated from internal/runbook/problems.yaml in nauthera-server.