Skip to content

Reauthentication Required

URI: https://docs.ankatech.co/errors/reauthentication-required
HTTP Status: 401 Unauthorized

When you see this

The operation requires a recent proof of the person's identity, and the token's last authentication is older than the deployment's reauthentication window (auth.reauthentication.max-age-seconds, 300 seconds by default, 60 to 900). The session is still valid: this is not an expired or revoked token. Nothing was read or changed.

The answer follows RFC 9470 (OAuth 2.0 Step Up Authentication Challenge Protocol). It always carries the challenge header, whose max_age is the window in seconds:

WWW-Authenticate: Bearer error="insufficient_user_authentication", error_description="A more recent authentication is required", max_age="300"

Operations that require a recent authentication:

  • on the Auth API, changing or removing the caller's own password, registering a passkey, enrolling an authenticator app, renaming or removing an authenticator, and regenerating recovery codes;
  • on the Admin API, every change to a tenant's or the deployment's identity providers, their domains and the email domains, the federated-link declarations, the authentication posture and allowance, a member's authentication path, a platform administrator's forced password reset or identity recovery, a correction of a member's login email, the appointment of a tenant administrator, a tenant administrator declaring a support-access grant, a platform administrator computing the log fingerprints of an identifier, and every quorum approval, rejection and quorum-policy change;
  • on the Auth API token endpoint, the token exchange by which a platform administrator enters a customer tenant.

Only a person's token is judged. Tokens of applications, actors and administrative workloads are never refused for this reason.

Common Causes

  • The person signed in, or last reauthenticated, longer ago than the window. A plain token refresh does not renew the proof; only a sign-in or a reauthentication does. For a member signed in through an identity provider, the proof time is the instant the provider states it authenticated the person: a provider that answered from its own single sign-on session gives the time of that earlier authentication, and one that states no instant gives none.
  • The token carries no proof time at all, for example a session that predates the platform's current release. It is treated as stale.
  • A platform administrator enters a tenant with a session proven only by a password or a TOTP code. Entering a tenant requires a recent user-verifying passkey or an identity provider approved for platform sign-in.

Response Example

An Admin API operation:

{
  "type": "https://docs.ankatech.co/errors/reauthentication-required",
  "title": "Reauthentication Required",
  "status": 401,
  "detail": "This operation requires a more recent authentication. Reauthenticate and retry the request; nothing was changed.",
  "instance": "/api/v3/admin/tenants/3f6c1a2e-8b4d-4e1f-9a7c-2d5e8f0b1c34/authentication-posture",
  "timestamp": 1790505600,
  "extensions": {
    "maxAge": 300,
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Content-Type: application/problem+json — the response follows RFC 9457 Problem Details. The window is extensions.maxAge. An Auth API body carries the same members with extensions.maxAge only: that service places no correlation identifier in the body (read the X-Correlation-Id response header); see Error Index & Overview.

The token endpoint answers a refused token exchange in the OAuth 2.0 error format, with Cache-Control: no-store and the same WWW-Authenticate header:

{
  "error": "insufficient_user_authentication",
  "error_description": "Entering a tenant requires a recent authentication with a passkey or an approved identity provider. Reauthenticate and retry; nothing was changed.",
  "error_uri": "https://docs.ankatech.co/errors/reauthentication-required",
  "type": "https://docs.ankatech.co/errors/reauthentication-required",
  "title": "Reauthentication Required",
  "status": 401,
  "detail": "Entering a tenant requires a recent authentication with a passkey or an approved identity provider. Reauthenticate and retry; nothing was changed.",
  "instance": "/api/v3/auth/token",
  "timestamp": 1790505600
}

How to Resolve

  1. Do not treat it as an expired session. Read max_age from the WWW-Authenticate header (or extensions.maxAge), and keep the session.
  2. Ask for a fresh proof on the session's refresh token: a refresh_token grant carrying max_age=<that value>. The token endpoint answers 403 insufficient_authorization with an auth_session; continue at POST /api/v3/auth/authorize-challenge with that auth_session, a new S256 code_challenge and no action, prove the factor offered, and redeem the resulting authorization code with the session's refresh token. The new access token carries a current reauth_time.
  3. Retry the original request with the new access token. Re-enter any secret the request carried (a password, a code) rather than replaying it from storage.
  4. If the reauthentication is refused because the identity has no factor to offer (for example no passkey or authenticator app enrolled), sign in again; the new session's proof is fresh.
  5. A platform administrator entering a tenant reauthenticates the platform session with a passkey or an approved identity provider, then exchanges again.

The admin console does all of this itself: it asks the person to confirm their identity and resends the request.

For full schema definitions, examples, and interactive testing, see the Developer Hub Reference.