immich-app/immich · error · UnauthorizedException

Elevated permission is required

Error message

Elevated permission is required

What it means

requireElevatedPermission guards endpoints that need a recently verified, elevated session. The AuthDto's session must carry hasElevatedPermission; if not, an UnauthorizedException (401) 'Elevated permission is required' is thrown. Elevated status is granted only after re-authentication (password confirmation) and typically expires.

Solutions

1. Re-authenticate to obtain an elevated session (confirm password via the appropriate endpoint) and retry the operation.
2. Log in again if the client cannot trigger re-confirmation.
3. For scripts, perform the elevated-confirmation call immediately before the protected call each run.
4. Check you are not using an API key/session type that cannot hold elevated permissions.

Example fix

// before
await api.changePassword(dto); // 401: elevated permission required
// after
await api.confirmPassword({ password }); // grants elevated session
await api.changePassword(dto);

// obtain an elevated session first
await api.confirmPassword({ password }); // 201 => session is elevated
// then perform the protected call

try {
  await api.changePassword(dto);
} catch (e) {
  if (e instanceof UnauthorizedException && e.message === 'Elevated permission is required') {
    await api.confirmPassword({ password });
    await api.changePassword(dto); // retry once
  } else {
    throw e;
  }
}

When it happens

Trigger: Calling a sensitive endpoint (e.g. changing password, downloading/ exporting sensitive data) with a session that never confirmed the password recently or whose elevated window has lapsed.

Common situations: Long-lived sessions/API keys without an elevated grant; automation scripts hitting protected endpoints without a password-reconfirmation step; user idling past the elevated-permission TTL then retrying an admin-style action.

Related errors

• Authentication required
• Denied access to admin only route
• Denied access to non-shared route
• Forbidden
• Invalid user token

AI-assisted analysis of immich-app/immich@e55ac299a4 (2026-09-15). Data as JSON: /api/errors/703b623262734206. Report an issue: GitHub.

Appendix: source

Thrown at server/src/utils/access.ts:370

      return access.stack.checkOwnerAccess(auth.user.id, ids);
    }

    case Permission.WorkflowRead:
    case Permission.WorkflowUpdate:
    case Permission.WorkflowDelete:
    case Permission.WorkflowLogs: {
      return access.workflow.checkOwnerAccess(auth.user.id, ids);
    }

    default: {
      return new Set<string>();
    }
  }
};

export const requireElevatedPermission = (auth: AuthDto) => {
  if (!auth.session?.hasElevatedPermission) {
    throw new UnauthorizedException('Elevated permission is required');
  }
};

View on GitHub (pinned to e55ac299a4)